普通小游戏开发
API
开放能力
数据分析
视频拍摄器
多端支持

分包加载

基础库 1.88.0 及以上版本开始支持,开发者工具请使用大于等于 2.0.6 且小于 3.0.0 的版本,可点击下载

使用方法

  1. 分包配置

假设游戏的目录结构如下:

├── game.js
├── game.json
├── images
│   ├── a.png
│   ├── b.png
├── stage1
│   └── game.js
│   └── images
│       ├── 1.png
│       ├── 2.png
└── stage2.js

game.json 中的配置:

注意这里 subPackages 是驼峰命名

{
  ...
  "subPackages": [
    {
      "name": "stage1",
      "root": "stage1/" // 可以指定一个目录,目录根目录下的 game.js 会作为入口文件,目录下所有资源将会统一打包
    }, {
      "name": "stage2",
      "root": "stage2.js" // 也可以指定一个 JS 文件
    }
  ]
  ...
}

subPackages 中,每个分包的配置有以下几项:

字段类型说明
rootstring分包根目录或者 js
namestring分包别名,tt.loadSubpackage可以使用
  1. 分包加载

通过 tt.loadSubpackage API 来触发分包的下载,调用 tt.loadSubpackage 后,将触发分包的下载与加载(如果分包指定的是一个目录,则自动加载目录下的 game.js, 如果分包指定的是一个 js 文件,则自动加载该 js 文件),在加载完成后,通过 tt.loadSubpackage 的 success 回调来通知加载完成。

同时,tt.loadSubpackage 会返回一个 LoadSubpackageTask,可以通过 LoadSubpackageTask 获取当前下载进度。

示例代码:

const loadTask = tt.loadSubpackage({
  name: 'stage1', // name 可以填 name 或者 root
  success: function(res) {
    // 分包加载成功后通过 success 回调
  },
  fail: function(res) {
    // 分包加载失败通过 fail 回调
  }
});

loadTask.onProgressUpdate(res => {
  console.log('下载进度', res.progress);
  console.log('已经下载的数据长度', res.totalBytesWritten);
  console.log('预期需要下载的数据总长度', res.totalBytesExpectedToWrite);
});

打包原则

配置在 subPackages 字段内的目录或 js 文件,将按照配置打包成一个个「分包」,没有配置在 subPackages 中的目录和 js,将会被打包到主包中。

引用原则

  • stage1 无法 require stage2 JS 文件,但可以自己 package 内的 JS 文件
  • stage1 无法使用 stage2 的资源,但可以自己 package 内的资源

低版本兼容

由字节小程序后台编译来处理旧版本客户端的兼容,后台会编译两份代码包,一份是分包后代码,另外一份是整包的兼容代码。
新客户端用分包,老客户端还是用的整包,完整包会把各个 subPackages 里面的的资源打包在一起。
开发者可以通过以下代码进行兼容

// 如果需要动态加载分包下的一个 js, 假设是 stage1 是一个分包目录
if (tt.loadSubpackage) { // 新版本支持分包,有 tt.loadSubpackage API,代码包被打成了多个包,需要调用 tt.loadSubpackage 加载对应的 js
    tt.loadSubpackage({
        name: 'stage1',
        success: function (res) {
            require('stage1/a.js');//这里可以加载分包中的其他非入口文件,并且没有被加载过的
        }
    });
} else { // 老版本不支持分包,没有 tt.loadSubpackage API, 代码包被打成了整包,直接加载即可
    require('stage1/a.js');
}
点击纠错
评价此篇文档