导入映射(实验性)

Cocos Creator 从 v3.3 开始实验性支持 导入映射(Import maps)

导入映射控制 TypeScript/JavaScript 的导入行为,尤其是可指定对 裸说明符 的解析。

使用

通过编辑器顶部菜单栏的 项目 -> 项目设置 -> 脚本 中的 导入映射 项即可指定导入映射文件的路径。设置完成后,导入映射功能开启,使用的导入映射将从指定的文件中读取。

注意:导入映射文件的路径是至关重要的,因为导入映射中的所有相对路径都是相对于导入映射文件本身路径。

别名映射

若有一个模块被项目中所有的模块所使用,而开发者并不希望其他模块以相对路径的方式引用它,而是为它起一个别名,那么便可以选择使用导入映射。

例如,某个模块真实的绝对路径为 <项目>/assets/lib/foo.ts,我们希望所有模块可以以 import {} from 'foo'; 的方式来引用它,操作步骤如下:

首先,在项目目录下创建一个导入映射文件 import-map.json

  1. // import-map.json
  2. {
  3. "imports": {
  4. "foo": "./assets/lib/foo.ts"
  5. }
  6. }
  • "imports":指定应用到所有模块的 顶级映射(Top level imports)。
  • "foo":指定我们要映射的模块名。
  • "./assets/lib/foo.ts":指定如何映射 "foo""./assets/lib/foo.ts" 是相对路径,导入映射中的所有相对路径都是相对于导入映射文件本身的位置的,因此 ./assets/lib/foo.ts 将解析为绝对路径 <项目>/assets/lib/foo.ts

然后在任意模块中使用以下方式引用模块时,'foo' 都将解析为模块 <项目>/assets/lib/foo.ts

  1. import * as foo from 'foo';

目录映射

导入映射还允许映射指定目录下的所有模块。

例如,要映射项目 assets/lib/bar-1.2.3 目录下的所有模块,则导入映射的 json 文件如下所示:

  1. // import-map.json
  2. {
  3. "imports": {
  4. "bar/": "./assets/lib/bar-1.2.3/"
  5. }
  6. }

除了 "bar/" 指定的是我们要映射的目录,其余的与 别名映射 一致。

这样项目中的模块都能以 import {} from 'bar/...' 的形式来引用目录 bar-1.2.3 中的模块。

例如:

  1. import * as baz from 'bar/baz';
  2. import * as quux from 'bar/qux/quux';

'bar/baz' 将解析为模块 <项目>/assets/lib/bar-1.2.3/baz.ts
'bar/qux/quux' 将解析为模块 <项目>/assets/lib/bar-1.2.3/qux/quux.ts

TypeScript 配置

TypeScript 并不支持导入映射,在使用时可能会导致出现找不到模块的报错,所以我们需要通过额外的配置来告诉 TypeScript 类型检查器额外的模块解析信息。

例如上述中的两个例子,可以在项目目录下的 tsconfig.json 文件中配置 paths 字段(若没有该字段,可自行补上),如下所示:

  1. // tsconfig.json
  2. {
  3. "compilerOptions": {
  4. "paths": {
  5. // 注意:这里的相对路径是相对于 tsconfig.json 所在的路径
  6. // 由于本例中 tsconfig.json 和 import-map.json 位于同一目录,因此这里的相对路径也相似。
  7. "foo": ["./assets/lib/foo"],
  8. "bar/*": ["./assets/lib/bar-1.2.3/*"]
  9. }
  10. }
  11. }

更多关于导入映射的功能,请参考 导入映射

支持情况

Cocos Creator 支持 Import Maps Draft Community Group Report, 12 January 2021 中的所有功能。