防止原文档失效,转自egret文档《第三方库的使用方法》
问题点:
在生成完 .d.ts 文件后,Egret 中能直接引入使用,但是发包时却缺少 index.html 等文件,说明存在一定的问题,所以还是得需要跟着官方文档一步一步前行。
第三方扩展库
准备
第三方库可以是标准的 ts 库,也可是在网上下载现成的 js 库,或者是开发者自己写的 js 库。
由于 js 与 ts 在语法结构上的差异,在 ts 中不能直接调⽤用 js 库的 API,所以TypeScript 团队提供了一套虚构声明语法,可以把现有代码的 API ⽤头⽂件的形式描述出来,扩展名为 d.ts(d.ts 命名会提醒编译器这种⽂件不需要编译)。这套虚构定义语法,让开发者不需要去实现函数体里的代码, 类似定义interface和抽象类。
幸运的是目前,⼤多数流⾏的 js 类库已经由官方提供,或者由热⼼的社区开发者提供了对应的 d.ts 文件。当然,如果没有,开发者也可以⾃⼰编写。详情可以参考JS类库及管理这些库的方法。
另外,由于一些流行的 js 库在快速更新,可能会发生找到的 d.ts ⽂件定义与 js 库的版本不一致⽽导致其中的 API 并没有完全对应的问题。遇到这种情况,要么寻找对应版本的 js 库,要么就需要开发者自己修改一下 d.ts 文件。
至于具体修改方法,在对照原 d.ts 的基础上,你可能还需要熟悉 ts 接⼝方⾯的语法,可以参考ts接⼝教程。
创建第三方库
当我们准备好了要用的第三方库,还需要把它编译成 egret 需要的模块结构。
- 创建一个egret第三方库的项目文件,在命令行中输入
egret create_lib demo
执行完成之后可以看到新建了一个 demo 文件夹,文件夹内有两个文件 package.json
tsconfig.json
- 在 demo 文件夹内创建
src
bin
typings
目录。
根据 TypeScript / JavaScript 不同类型的类库,有两种情况:
TypeScript库
- 直接将ts文件放到
src
目录下。 - 修改
tsconfig.json
文件:
{
"compilerOptions": {
"target": "es5",
"noImplicitAny": false,
"sourceMap": false,
// 是否生成.d.ts文件。 如果是typescript库设置为true,如果是javascript库设置为false
"declaration": true,
"outFile": "bin/demo/demo.js", // 生成的库文件的路径
},
"include": ["src"]
}
JavaScript库
- 将js文件放到
src
目录下,将对于的 .d.ts 文件放到typings
目录下。 - 修改
tsconfig.json
文件:
{
"compilerOptions": {
"target": "es5",
"noImplicitAny": false,
"sourceMap": false,
// 是否生成.d.ts文件。 如果是typescript库设置为true,如果是javascript库设置为false
"declaration": false,
"outFile": "bin/demo/demo.js", // 生成的库文件的路径
// 是否允许编译js文件。 如果是typescript库设置为false,如果是javascript库设置为true
"allowJs": true
},
"include": ["src"]
}
- 修改
package.json
文件:
{
"name": "jszip",
"compilerVersion": "5.2.7",
// 新增一个字段
"typings": "typings/demo.d.ts"
}
- 执行命令
egret build demo
会根据 tsconfig.json
中的 outFile
字段生成库文件,压缩文件以及 .d.ts 文件。
bin
目录中生成的demo
文件夹就是我们可以使用的第三方库文件夹。
TIP
如果你已经有了demo.js
、demo.min.js
、demo.d.ts
三个文件,那么你不需要执行以上步骤,直接将这三个文件放到同一个文件夹demo
内,然后使用即可。
使用第三方库
将
demo
文件夹复制到项目libs目录中(不可以放到modules
内)。编辑
egretProperties.json
文件:
{
"engineVersion": "5.2.33",
"compilerVersion": "5.2.33",
"template": {},
"target": {
"current": "web"
},
"modules": [
{
"name": "egret"
},
{
"name": "eui"
},
{
"name": "assetsmanager"
},
{
"name": "game"
},
{
"name": "tween"
},
{
"name": "promise"
},
// 新增一个字段
{
"name": "demo", // 第三方库的name
"path": "./libs/demo" // 路径
}
]
}
- 重新编译下Egret引擎
执行之后,就可以在当前项目中使用的引入的第三方库了。