您的位置: 首页  >  文章  >  白鹭从0开始

白鹭从0开始

分类: 文章 • 2023-04-08 13:07:42

一、入口文件说明

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

  1. <div style="margin: auto;width: 100%;height: 100%;" class="egret-player"
  2. data-entry-class="Main"
  3. data-orientation="auto"
  4. data-scale-mode="showAll"
  5. data-frame-rate="30"
  6. data-content-width="640"
  7. data-content-height="1136"
  8. data-multi-fingered="2"
  9. data-show-fps="false" data-show-log="false"
  10. data-show-fps-style="x:0,y:0,size:12,textColor:0xffffff,bgAlpha:0.9">
  11. </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 标签内，有项目的启动参数,如下图所示

 
  1. egret.runEgret({ renderMode: "webgl", audioType: 0,
  2. calculateCanvasScaleFactor:function(context) {
  3. var backingStore = context.backingStorePixelRatio ||
  4. context.webkitBackingStorePixelRatio ||
  5. context.mozBackingStorePixelRatio ||
  6. context.msBackingStorePixelRatio ||
  7. context.oBackingStorePixelRatio ||
  8. context.backingStorePixelRatio || 1;
  9. return (window.devicePixelRatio || 1) / backingStore;
  10. }});

参数是一个对象，包括以下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}

  1. {
  2. "egret_version":"5.2.6",
  3. "modules":[
  4. {
  5. "name":"egret",
  6. },
  7. {
  8. "name":"tween",
  9. "path":"${EGRET_APP_DATA}/4.0.3"
  10. },
  11. {
  12. "name": "particle",
  13. "path": "../libsrc"
  14. },
  15. {
  16. "name": "promise",
  17. "path": "./promise"
  18. }
  19. ]
  20. }

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

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

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

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

urlParams 字段 (3.1.6 以上支持)

  • 针对egret run命令添加URL参数，
  1. {
  2. "urlParams":{
  3. "okok":12,
  4. "id":455464564
  5. }
  6. }

例如上面这个配置，在执行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字段里单独设置该库使用的版本

第三方库

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

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

使用示例：

  1. {
  2. "egret_version":"5.2.6",
  3. "modules":[
  4. {
  5. "name":"egret",
  6. },
  7. {
  8. "name":"tween",
  9. "path":"${EGRET_APP_DATA}/5.0.3"
  10. },
  11. {
  12. "name": "particle",
  13. "path": "../libsrc"
  14. },
  15. {
  16. "name": "promise",
  17. "path": "./promise"
  18. }
  19. ]
  20. }

该配置表示:

  • 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 默认项目。

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

    白鹭从0开始

    如上所示，创建了一个 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错误：

    白鹭从0开始

    当我们添加了 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 需要的模块结构。

  1. 创建一个egret第三方库的项目文件，在命令行中输入

     
    1. egret create_lib demo

    执行完成之后可以看到新建了一个 demo 文件夹，文件夹内有两个文件 package.json tsconfig.json。

  2. 在 demo 文件夹内创建src bin typings 目录。

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

    TypeScript库

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

    修改tsconfig.json文件：

     
    1. {
    2. "compilerOptions": {
    3. "target": "es5",
    4. "noImplicitAny": false,
    5. "sourceMap": false,
    6.  
    7. // 是否生成.d.ts文件。 如果是typescript库设置为true，如果是javascript库设置为false
    8. "declaration": true,
    9.  
    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,
    6.  
    7. // 是否生成.d.ts文件。 如果是typescript库设置为true，如果是javascript库设置为false
    8. "declaration": false,
    9.  
    10. "outFile": "bin/demo/demo.js", // 生成的库文件的路径
    11.  
    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",
    4.  
    5. // 新增一个字段
    6. "typings": "typings/demo.d.ts"
    7. }

  1. 执行命令

     
    1. egret build demo

    会根据 tsconfig.json中的 outFile字段生成库文件，压缩文件以及 .d.ts 文件。

    bin 目录中生成的demo文件夹就是我们可以使用的第三方库文件夹。

TIP

如果你已经有了demo.js、demo.min.js、demo.d.ts三个文件，那么你不需要执行以上步骤，直接将这三个文件放到同一个文件夹demo内，然后使用即可。

使用第三方库

  1. 将demo文件夹复制到项目libs目录中（不可以放到modules内）。

  2. 编辑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. },
 
  1. // 新增一个字段
  2. {
  3. "name": "demo", // 第三方库的name
  4. "path": "./libs/demo" // 路径
  5. }
  6. ]

}

 
  1.  
  2. 3. 编译引擎。
  3.  
  4. ```shell
  5. egret build

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

引擎提供的第三方库

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

相关推荐