egret-docs-master/Engine2D/projectConfig/libraryProject
guofei 4fe0162b34 fist commit 2024-06-19 13:32:32 +08:00
..
README.md fist commit 2024-06-19 13:32:32 +08:00

README.md

第三方扩展库

准备

第三方库可以是标准的 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第三方库的项目文件在命令行中输入

    egret create_lib demo
    

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

  2. 在 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"
    }
    
    
  3. 执行命令

    egret build demo
    

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

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

TIP

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

使用第三方库

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

  2. 编辑egretProperties.json文件:

    {
      "engineVersion": "5.2.7",
      "compilerVersion": "5.2.7",
      "template": {},
      "target": {
        "current": "web"
      },
      "eui": {
        "exmlRoot": [
          "resource/eui_skins"
        ],
        "themes": [
          "resource/default.thm.json"
        ],
        "exmlPublishPolicy": "commonjs"
      },
      "modules": [
        {
          "name": "egret"
        },
        {
          "name": "eui"
        },
        {
          "name": "assetsmanager"
        },
        {
          "name": "tween"
        },
        {
          "name": "promise"
        },
    
    
        // 新增一个字段
        {
          "name": "demo",  // 第三方库的name
          "path": "./libs/demo"  // 路径
        }
      ]
    }
    
  3. 编译引擎。

    egret build
    

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

引擎提供的第三方库

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