扩展模块
首先我们创建一个不引用任何模块的 Egret 空项目,在命令行中输入
egret create demo --type empty
您会看到在项目文件夹中有一个 egretProperties.json 文件,这个文件描述了当前项目的一些信息。
其中包含一个 modules
字段,这部分就是用来配置扩展模块和第三方库的。
为了统一管理,Egret官方库按照模块呈现,这样设计的目的是避免加载不需要的模块,减少最终代码的体积,提高加载速度。
目前 Egret 的官方库分为8个模块
egret 必备的核心库
game 制作游戏会用到的类库,比如 MovieClip,URLLoader 等
res 资源加载库,所有涉及资源载入的工作,都可以通过这个模块来完成
tween 动画缓动类
dragonbones 龙骨动画库,用来制作一些复杂的动画效果
socket 用来通讯的 WebSocket 库
gui 老版本的 UI 库
eui 新增的 UI 库,使用起来更加的方便
您需要用哪个库,就配置哪个。比如我想用 game tween eui
这3个模块,只要像下面这样添加到配置文件里就可以了
然后命令行里使用 egret build -e
命令,引擎会自动把使用到的类库放到你的项目里。
你会发现,在项目的 libs/modules
文件夹下,原来只有一个 egret 文件夹,现在多了game eui 和tween三个文件夹,这些就是使用到的类库。
同样的,如果您在 egretProperties.json 配置文件里把模块名删掉,libs/modules
文件夹下也会删掉对应的类库。
使用egret create project_name
命令创建的项目,默认会带4个官方模块:egret game res tween
标准第三方库
准备第三方库
第三方库可以是标准的 ts 库,也可是你在网上下载现成的 js 库,或者是自己写的 js 库。
由于 js 与 ts 在语法结构上的差异,在 ts 中不能直接调用 js 库的 API,所以TypeScript 团队提供了一套虚构声明语法,可以把现有代码的 API 用头文件的形式描述出来,扩展名为 d.ts(d.ts 命名会提醒编译器这种文件不需要编译)。这套虚构定义语法,让你不需要去实现函数体里的代码,类似定义interface和抽象类。
幸运的是目前,大多数流行的 js 类库已经由官方提供,或者由热心的社区开发者提供了对应的 d.ts 文件。当然,如果没有,您也可以自己编写。这里有篇教程讲得很详细,里边也包含一个庞大的 d.ts 库,以及管理这些库的方法:使用JS类库。
另外,由于一些流行的 js 库在快速更新,可能会有你找到的 d.ts 文件定义与 js 库的版本不一致而导致其中的 API 并没有完全对应的问题。遇到这种情况,要么寻找对应版本的 js 库,要么就需要您自己修改一下 d.ts 文件了。
至于具体修改方法,在对照原 d.ts 的基础上,你可能还需要熟悉 ts 接口方面的语法,可以参考这里:ts接口教程。
创建第三方模块
当我们准备好了要用的第三方库,还需要把它编译成 egret 需要的模块结构。
比如现在有一个名为 weixinapi 的 js 库,它包含3个文件
jweixin-1.0.0.js
jweixin-1.0.0-additional.js
weixinapi.d.ts
第 1 步 要创建一个egret第三方库的项目文件,在命令行中输入
cd .. (首先跳出Egret 项目)再创建第三方库项目
egret create_lib libsrc
第三方库项目与 Egret 项目不能嵌套。请不要在Egret 项目目录下面创建第三方库项目。
您会发现刚刚创建的第三方库项目和我们平时看到的 Egret 项目结构是不同的,里面包含2个空文件夹 bin、src、libs(如果没有请自行加上)
,还有一个 package.json 的配置文件。
第 2 步 把准备好的那3个文件拷贝到src文件夹中。
第 3 步 如果需要引用到其他的第三方库的代码,请把引用到的库文件(主要是 .d.ts 文件)放到 libs 目录下,libs 下不要放其他除了 .d.ts 外的其他 .ts 文件。
第 4 步 打开 package.json,将3个文件写入到 files 下面,如果文件有先后依赖顺序,一定得注意顺序。
package.json文件中:
{
"name": "egret",
"version": "3.1.2",
"modules": [
{
"name": "weixinapi",
"description": "weixinapi",
"files": [
"jweixin-1.0.0.js",
"jweixin-1.0.0-additional.js",
"weixinapi.d.ts"
],
"root": "src"
}
]
}
第 5 步 在命令行中输入编译命令
egret build
libsrc(指的是上面 “egret create_lib libsrc” 中的 libsrc )
编译完成后,您会发现,在 bin 文件夹下,生成了一个 weixinapi文件夹(文件夹名字是由 package.json文件中"name": "weixinapi"决定的),里面有个3个文件
weixinapi.d.ts 描述文件
weixinapi.js 在 Egret 项目里,debug 模式时使用的 js 库
weixinapi.min.js 在 Egret 项目里,发布后的正式版使用的 js 库,经过压缩,体积比 jszip.js 小
使用第三方模块
和使用官方的扩展模块方法类似,在modules
里填写相关的信息
egretProperties.json文件中:
{
"native": {
"path_ignore": []
},
"publish": {
"web": 0,
"native": 1,
"path": "bin-release"
},
"egret_version": "3.1.2",
"modules": [
{
"name": "egret"
},
{
"name": "res"
},
{
"name": "eui"
},
{
"name": "weixinapi",
"path": "../libsrc"
}
]
}
"name": "weixinapi" 第三方库的名称
"path": "../libsrc" 刚才我们创建的第三方库的路径,绝对路径或者相对路径
这里需要注意的是,weixinapi 需要放置在 Egret 项目目录的外面。
最后命令行里使用 egret build -e
命令,引擎会把自定义的第三方库引用进来,在 libs/modules
路径下,你会看到 jszip 这个库,并且在 index.html
中的 modules_files
块中,会加入 jszip 的 script 标签。
<!--这个标签为通过egret提供的第三方库的方式生成的 javascript 文件。删除 modules_files 标签后,库文件加载列表将不会变化,请谨慎操作!-->
<!--modules_files_start-->
<script egret="lib" src="libs/modules/egret/egret.js" src-release="libs/modules/egret/egret.min.js"></script>
<script egret="lib" src="libs/modules/egret/egret.web.js" src-release="libs/modules/egret/egret.web.min.js"></script>
<script egret="lib" src="libs/modules/res/res.js" src-release="libs/modules/res/res.min.js"></script>
<script egret="lib" src="libs/modules/eui/eui.js" src-release="libs/modules/eui/eui.min.js"></script>
<script egret="lib" src="libs/modules/weixinapi/weixinapi.js" src-release="libs/modules/weixinapi/weixinapi.min.js"></script>
<!--modules_files_end-->
所有需要对 api 的 .d.ts 文件,请放在 src 下面,即需要在 package.json 里配置,其他的请放在 libs 下面。
其他第三方库
除了使用 egret 提供的标准的第三方库的方式,我们还提供了另外一种可以通过 index.html 来直接配置的方式。
- 代码请放在 libs 目录下面,但是不要放在 libs/modules 下面。
- 在 index.html 中的 other_libs_files 块中,配置自定义的第三方库。需要填写 egret=”lib” 以及 src-release。
所有放在 libs 目录下面的文件,以 ts 作为扩展名的文件只能是 .d.ts
(如 a.d.ts)文件,不能有纯 ts 文件(如 a.ts)。