白鹭从0开始 - 爱码网

一、入口文件说明

项目中的index.html 为项目的入口文件，下面是 body 标签里的默认配置，您可以根据项目需求修改。

<div style="margin: auto;width: 100%;height: 100%;" class="egret-player"
data-entry-class="Main"
data-orientation="auto"
data-scale-mode="showAll"
data-frame-rate="30"
data-content-width="640"
data-content-height="1136"
data-multi-fingered="2"
data-show-fps="false" data-show-log="false"
data-show-fps-style="x:0,y:0,size:12,textColor:0xffffff,bgAlpha:0.9">
</div>

data-entry-class：文件类名称。
data-orientation：旋转模式。
data-scale-mode：适配模式。
data-frame-rate：帧频数。
data-content-width：游戏内舞台的宽。
data-content-height：游戏内舞台的高。
data-multi-fingered：多指最大数量。
data-show-fps：是否显示 fps 帧频信息。
data-show-log：是否显示 egret.log 的输出信息。
data-show-fps-style：fps面板的样式。支持5种属性，x:0, y:0, size:30, textColor:0xffffff, bgAlpha:0.9

在 script 标签内，有项目的启动参数,如下图所示

egret.runEgret({ renderMode: "webgl", audioType: 0,
calculateCanvasScaleFactor:function(context) {
var backingStore = context.backingStorePixelRatio ||
context.webkitBackingStorePixelRatio ||
context.mozBackingStorePixelRatio ||
context.msBackingStorePixelRatio ||
context.oBackingStorePixelRatio ||
context.backingStorePixelRatio || 1;
return (window.devicePixelRatio || 1) / backingStore;
}});

参数是一个对象，包括以下3个可选属性：

“renderMode”: 引擎渲染模式，”canvas” 或者 “webgl”
“audioType”: 使用的音频类型，0:默认，2:web audio，3:audio
“calculateCanvasScaleFactor”：屏幕的物理像素适配方法，使用默认的即可

二、项目配置文件说明

项目的根文件夹下有名为 egretProperties.json 的配置文件，引擎所涉及的配置均存储在此。

整体结构

白鹭从0开始

engineVersion 字段

项目当前用来运行游戏的 egret 引擎版本，

compilerVersion 字段

项目当前使用的 egret 命令行版本，比如执行 build,publish 等命令，每个版本略有不同

template 字段

如果存在该字段，在发布 Html5 项目时，会使用 template/web/index.html 来作为入口文件。点击查看更多详情

target 字段

执行 build 和 publish 命令时的目标类型。

web：会编译成 Html5 项目
wxgame：会编译成微信小游戏项目
bricks：会编译 QQ 玩一玩项目
android：会编译成安卓项目
iOS：会编译成 iOS 项目

modules 字段

定义项目中引用的所有库文件。
每一个库都是形如 { "name":"moduleName" , "path":"modulePath"} 的配置信息。
name 字段是库名。path 字段是库文件存放路径，如果没有此字段，取默认值${EGRET_DEFAULT}

{
"egret_version":"5.2.6",
"modules":[
{
"name":"egret",
},
{
"name":"tween",
"path":"${EGRET_APP_DATA}/4.0.3"
},
{
"name": "particle",
"path": "../libsrc"
},
{
"name": "promise",
"path": "./promise"
}
]
}

path 字段中可以包括库文件版本号

path 字段所对应的路径可能在项目中，也可能在项目外。

如果在项目中，项目运行时直接加载此路径所对应的库。
如果在项目外，引擎编译时会首先将此路径所对应的库拷贝至项目中的 libs/modules 文件夹中，然后加载该文件夹中的库。

修改该配置中的内容后，需要执行 egret clean 命令进行重新构建，以保证改动生效。

urlParams 字段 (3.1.6 以上支持)

针对egret run命令添加URL参数，

{
"urlParams":{
"okok":12,
"id":455464564
}
}

例如上面这个配置，在执行egret run后会在浏览器里打开地址：

http://10.0.4.63:3000/index.html?okok=12&id=455464564

模块配置

在项目配置文件egretProperties.json中， modules 字段可以定义项目中引用的所有库文件。

每一个库都是形如 { "name":"moduleName" , "path":"modulePath"} 的配置格式。
name 字段是库名，path 字段是库文件存放路径，

path 字段中可以包括库文件版本号

path 字段所对应的路径可能在项目中，也可能在项目外。

如果在项目中，项目运行时直接加载此路径所对应的库。
如果在项目外，引擎编译时会首先将此路径所对应的库拷贝至项目中的 libs/modules 文件夹中，然后加载该文件夹中的库。

引擎库分为2种

内置库，主要包括:

egret 引擎核心库
egret3d 引擎 3D 库
assetsmanager 资源管理模块
dragonBones 龙骨
eui UI 组件库
game 游戏库
media 多媒体库
socket websocket 网络通讯库
tween 缓动动画库

内置库可以省略path字段，默认和egret_version 使用相同的版本。也可以在path字段里单独设置该库使用的版本

第三方库

白鹭官方提供了一些常见的第三方库供开发者使用。

开发者也可以在项目中配置自己的库。

使用示例：

{
"egret_version":"5.2.6",
"modules":[
{
"name":"egret",
},
{
"name":"tween",
"path":"${EGRET_APP_DATA}/5.0.3"
},
{
"name": "particle",
"path": "../libsrc"
},
{
"name": "promise",
"path": "./promise"
}
]
}

该配置表示:

egret 模块使用 egret_version 的 5.2.5 版本
tween 模块使用 5.0.3 版本
particle 模块的路径在项目外面
promise 模块的路径在项目里面
tsconfig 配置文件

tsconfig.json 是 Typescript 项目的配置文件，TypeScript 编译器编译代码之前，会首先读取这个配置文件，并根据其中的属性来设置 TypeScript 项目的编译参数。

使用方式

1 ) 在创建 egret 项目时，会自动在项目根目录下生成名为 “tsconfig.json” 的文本文件。

2 ) 下面为引擎默认的参数，可以根据您项目的需求，自己修改。：
```
 
```
{
"compilerOptions": {
"target": "es5",
"outDir": "bin-debug",
"experimentalDecorators": true,
"lib": [
"es5",
"dom",
"es2015.promise"
],
"types": []
},
"include": [
"src",
"libs"
]
}
下面我们详细说明一下 compilerOptions 里的字段。
target:编译之后生成的JavaScript文件需要遵循的标准，默认为 es5，兼容性比较好，不建议修改
outDir:编译出来的js文件，放到哪个目录下，默认编译到 bin-debug 里，目前暂不支持修改
experimentalDecorators:启用实验性质的语法装饰器，引擎里的部分库使用了最新的语法，需要开启这个配置
lib: 编译需要的库文件，默认有3个，你可以根据需求自行添加
其他常用参数
- "sourceMap": true:把.ts 文件编译成.js 文件时，生成对应的 .js.map 文件，该文件可以让用户直接在浏览器里调试 ts 文件
- "removeComments": true: 编译 .js 时删除原本 .ts 文件中的注释。
3 ) 设置其他字段，比如与 compilerOptions 平级的还有一个 include 字段,表示哪些文件会参与编译。在引擎 4.x 之前的版本里，该字段为 exclude, 表示哪些文件不参与编译

4 ) 执行 egret build 命令，可以按照配置文件来编译 egret 项目。

更详细的编译参数，您可以参考 tsconfig.json 的官方文档。

TypeScript详细手册参考：TypeScript Handbook（中文版）
编译顺序说明

在 Egret 中，需使用 TypeScript 编写程序，最终编译成浏览器可读的 JavaScript。

JavaScript 是一种脚本语言，浏览器按脚本的顺序来执行。实际上浏览器会根据 <script> 标签中脚本的载入顺序来执行脚本。当某个脚本引用了一个未载入的脚本中的变量时，浏览将报出相应的错误。

一般情况下，在 Egret 项目中并不需要手动处理编译顺序，因为egret编译器已经帮助开发者处理好了。但是有一种情况是编译器不能处理的，需要手动加上 <reference> 标签来告诉编译器项目中类的依赖关系。下面是具体的代码和解决的方法。

TypeScript详细手册参考：TypeScript Handbook（中文版）

测试依赖关系

新建一个 Egret 项目，这里使用 egret create test 创建一个 Egret 默认项目。

建立若干测试类，项目的结构如下:

如上所示，创建了一个 Test 文件夹，内部创建了 Call 文件夹，在 Call 内部创建了 TestCall.ts。同时在 Test 文件夹内创建 TestA.ts 和 TestB.ts。其余的 Main.ts 和 LoadingUI.ts 等这里用不到，在此忽略。

在 TestA.ts 中代码如下：
```
 
```
class TestA{
public static arr:Array<any> = ["t","e","s","t","c","a","l","l"];
}
TestB.ts 中代码如下:
```
 
```
class TestB{
public static testBStr:string = TestA.arr.join("");
}
这两个类都只有一个静态成员。其中 TestA 类存放了一个数组,TestB 类将这个数组的内容拼接成一个字符串并保存下来。到目前为止我们编译运行并没有发现异常。

下面在TestCall.ts 中加入对 TestB 类的调用。
```
 
```
class TestCall{
public static test:any = egret.getDefinitionByName(TestB.testBStr);
}
这种情况解决方法是告诉编译器项目中的类的依赖关系。在 TypeScript 中，使用<reference>标签来表示引用关系。在 reference 标签中可以标记依赖文件的相对路径。所以只需要在 TestB 类之前加入如**释即可：
```
 
```
///<reference path="TestA.ts" />
```
 
```
class TestB{
public static testBStr:string = TestA.arr.join("");
}
上面这种情况一般发生在静态成员的引用上，还有其他情况在极小概率下可能导致该现象，如果遇到，请加入依赖关系标签来告诉编译器正确的加载方式。

编译运行之后发现浏览器会报如下TestB.js:11 Uncaught ReferenceError错误：

当我们添加了 TestB.testBstr 的调用之后浏览器发现 TestA 类并没有被定义，进而导致 testBStr 这个属性页找不到了。在编译之后检查生成的 index.html 文件会发现 TestB.js 是在 TestCall.js 之前加载的，而 TestA.js 是在最后加载的。当 TestB.js 调用 TestA.js 中的文件的内容时浏览器将会报错。

上面的调用关系在代码中显然是成立的，编译器并没有报错。而编译器并没有生成正确的载入顺序，主要是因为其无法确认这种类的静态成员的互相引用的顺序。当在 TestCall.ts 中引用了TestB.ts 中的内容时自动将 TestB.js 放在 TestCall.js 之前进行加载。由于无法检测到 TestB.ts 中对 TestA.ts 的静态成员的引用，所以导致了以上情况的发生。

解决方法
这种情况解决方法是告诉编译器项目中的类的依赖关系。在 TypeScript 中，使用<reference>标签来表示引用关系。在 reference 标签中可以标记依赖文件的相对路径。所以只需要在 TestB 类之前加入如**释即可：
```
 
```
///<reference path="TestA.ts" />
```
 
```
class TestB{
public static testBStr:string = TestA.arr.join("");
}
上面这种情况一般发生在静态成员的引用上，还有其他情况在极小概率下可能导致该现象，如果遇到，请加入依赖关系标签来告诉编译器正确的加载方式。
扩展库简介

扩展库说明

根据不同的项目需求，您可以选择不同扩展库，这里主要介绍下常见的扩展库
res资源加载库：RES模块是Egret为开发者准备的一套功能完善的资源加载机制。当开发者编写游戏时，无需关心资源加载的细节，只需要指定加载的资源，并且在对应的逻辑位置中添加相应的执行加载代码即可。详细了解参考这里，api文档这里。
eui界面制作库：EUI是一套基于Egret核心显示列表的UI扩展库，它封装了大量的常用UI组件，能够满足大部分的交互界面需求，即使更加复杂的组件需求，您也可以基于EUI已有组件进行组合或扩展，从而快速实现需求。详细了解参考这里，api文档这里。
DragonBones龙骨动画库：DragonBones是一套2D骨骼动画的库，当开发者使用DragonBones pro导出的动画文件时，必须使用DragonBones库来解析和控制动画。详细了解参考这里，api文档这里。
game库：game库主要提供了1、使用Texture Merger制作的动画文件的解析和控制，2、提供了ScrollView 是用于滑动的辅助类，将一个显示对象传入构造函数即可。可以在指定的尺寸范围内显示超过该范围的显示对象。并可以在此范围内随意拖动。3、使用了egret封装的定时函数。详细了解参考这里，api文档这里。
socket库：WebSocket是基于H5规范的，WebSocket 类用于发送和接收数据,WebSocket 标准在很大程度上简化了复杂的双向网络沟通和连接管理。详细了解参考这里，api文档这里。
egret实验功能库: 对照片选择器功能，可以选择手机照片并显示，目前只支持 Web 端。

第三方扩展库

准备

第三方库可以是标准的 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第三方库的项目文件，在命令行中输入
```
 
```
1. egret create_lib demo
执行完成之后可以看到新建了一个 demo 文件夹，文件夹内有两个文件 package.json tsconfig.json。
在 demo 文件夹内创建src bin typings 目录。

根据 TypeScript / JavaScript 不同类型的类库，有两种情况：

TypeScript库

直接将ts文件放到src目录下。

修改tsconfig.json文件：
```
 
```
1. {
2. "compilerOptions": {
3. "target": "es5",
4. "noImplicitAny": false,
5. "sourceMap": false,
7. // 是否生成.d.ts文件。如果是typescript库设置为true，如果是javascript库设置为false
8. "declaration": true,
10. "outFile": "bin/demo/demo.js", // 生成的库文件的路径
11. },
12. "include": ["src"]
13. }
JavaScript库

将js文件放到src目录下，将对于的 .d.ts 文件放到typings目录下。

修改tsconfig.json文件：
```
 
```
1. {
2. "compilerOptions": {
3. "target": "es5",
4. "noImplicitAny": false,
5. "sourceMap": false,
7. // 是否生成.d.ts文件。如果是typescript库设置为true，如果是javascript库设置为false
8. "declaration": false,
10. "outFile": "bin/demo/demo.js", // 生成的库文件的路径
12. // 是否允许编译js文件。如果是typescript库设置为false，如果是javascript库设置为true
13. "allowJs": true
14. },
15. "include": ["src"]
16. }
修改package.json 文件：
```
 
```
1. {
2. "name": "jszip",
3. "compilerVersion": "5.2.7",
5. // 新增一个字段
6. "typings": "typings/demo.d.ts"
7. }

执行命令
```
 
```
1. 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文件：

```json
{
“engineVersion”: “5.2.7”,
“compilerVersion”: “5.2.7”,
“template”: {},
“target”: {
```
 
```
1. "current": "web"
},
“eui”: {
```
 
```
1. "exmlRoot": [
2. "resource/eui_skins"
3. ],
4. "themes": [
5. "resource/default.thm.json"
6. ],
7. "exmlPublishPolicy": "commonjs"
},
“modules”: [
```
 
```
1. {
2. "name": "egret"
3. },
4. {
5. "name": "eui"
6. },
7. {
8. "name": "assetsmanager"
9. },
10. {
11. "name": "tween"
12. },
13. {
14. "name": "promise"
15. },

// 新增一个字段
{
"name": "demo", // 第三方库的name
"path": "./libs/demo" // 路径
}
]

}

3. 编译引擎。
```shell
egret build

执行之后，就可以在当前项目中使用的引入的第三方库了。

引擎提供的第三方库

Egret提供了几个实用的第三方库，开发者可以根据需求自行下载使用。

JSZip库

下载地址： https://github.com/egret-labs/egret-game-library/tree/master/jszip

教程文档：http://developer.egret.com/cn/github/egret-docs/extension/jszip/jszip/index.html
mouse鼠标支持库

下载地址：https://github.com/egret-labs/egret-game-library/tree/master/mouse

教程文档：http://developer.egret.com/cn/github/egret-docs/extension/mouse/mouse/index.html
P2物理系统库

下载地址：https://github.com/egret-labs/egret-game-library/tree/master/physics

教程文档：http://developer.egret.com/cn/github/egret-docs/extension/p2/p2/index.html
Particle粒子库

下载地址：https://github.com/egret-labs/egret-game-library/tree/master/particle

教程文档：http://developer.egret.com/cn/github/egret-docs/extension/particle/introduction/index.html
Tiled瓦片地图库

下载地址：https://github.com/egret-labs/egret-game-library/tree/master/tiled

教程文档：http://edn.egret.com/cn/docs/page/718

整体结构

engineVersion 字段

compilerVersion 字段

template 字段

target 字段

modules 字段

urlParams 字段 (3.1.6 以上支持)

使用方式

测试依赖关系

解决方法

扩展库说明

第三方扩展库

准备

创建第三方库

JavaScript库

TIP

使用第三方库

引擎提供的第三方库