导入映射（实验性）

Cocos Creator 从 v3.3 开始实验性支持 导入映射（Import maps）。

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

使用

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

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

别名映射

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

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

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

  1. // import-map.json
  3. {
  4.     "imports": {
  5.         "foo": "./assets/lib/foo.ts"
  6.     }
  7. }
  • "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
  3. {
  4.     "imports": {
  5.         "bar/": "./assets/lib/bar-1.2.3/"
  6.     }
  7. }

除了 "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 中的所有功能。