分包加載

隨著小遊戲的玩法越來越豐富，開發者對於擴大包大小的需求越來越強烈，所以我們推出了小遊戲分包加載這個功能。所謂的分包加載，即把遊戲內容按一定規則拆分這幾包，在首次啟動時先下載必要的包，這個必要的包我們稱為主包，開發者可以在主包內觸發其它分包的下載，從而把首次啟動的下載耗時分散到遊戲運行中。

開發者可以使用框架封裝的分包加載能力，也可以在不使用框架的情況下直接使用 game.json 配置分包，相關詳情如下。

使用限制：

目前小遊戲分包大小有以下限制：

• 整個小遊戲所有主包+分包大小不超過 20M
• 主包不超過 4M
• 單一普通分包不限制大小
• 單一獨立分包不超過 4M

使用分包

配置方法

假設支持分包的小程序目錄結構如下：

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

game.json 中的配置：

{
  ...
  "subpackages": [
    {
      "name": "stage1",
      "root": "stage1/" // Specify a directory; the game.js in the root directory will be the entry file, and all resources in the directory will be packaged together
    }, {
      "name": "stage2",
      "root": "stage2.js" // You can also specify a JS file
    }
  ]
  ...
}

subpackages 中，每個分包的配置有下列幾項：

欄位	類型	說明
root	String	分包根目錄
name	String	分包別名，,分包預下載時可以使用
independent	String	分包是否是獨立分包

打包原則

• 聲明subpackages後，將按subpackages配置路徑進行打包，subpackages配置路徑外的目錄將被打包到主包中。
• subpackage的根目錄不能是另外一個subpackage內的子目錄。

引用原則

• packageA無法require packageB JS文件，但可以require主包、packageA內的JS文件； 使用
• packageA無法使用packageB的資源，但可以使用主包、packageA內的資源。

獨立分包

獨立分包是小遊戲中一種特殊類型的分包，可以獨立於主包和其他分包運行。以獨立分包路徑啟動小遊戲時，客戶端會僅下載獨立分包並啟動遊戲，不會下載主包，以實現部分場景下快速啟動遊戲的需求。開發者可以按需將某些具有一定功能獨立性的頁面配置到獨立分包中，可以大幅提高頁面開啟速度。

獨立分包啟動後，開發者可以按需使用wx.loadSubpackage介面預先下載主套件或其他分包，並在適當時機（例如使用者點擊開始遊戲時）執行已下載的程式碼套件邏輯。

配置方法

假設小遊戲目錄結構如下：

.
├── game.js
├── game.json
├── moduleA
│   └── game.js
├── moduleB
│   └── game.js
└── utils

開發者透過在game.json的subpackages欄位中對應的分包配置項中定義independent欄位聲明對應分包為獨立分包。

{
  "subPackages": [
    {
      "name": "moduleA",
      "root": "/moduleA/", // Regular subpackage
    },
    {
      "independent": true, // Independent subpackage, specify a directory; the game.js in the root directory will be the entry file, and all resources in the directory will be packaged together
      "name": "moduleB",
      "root": "/moduleB/",
    }
  ]
}

遊戲內分享指定獨立分包頁面：

// Share with friends or groups
wx.shareAppMessage({
  title: 'Share the title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})
Share on Moments
wx.onShareTimeline({
  title: 'Share the title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})
// Add to Favorites
wx.addToFavorites({
  title: 'Favorite title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})

獨立分包內，下載其他分包：

const loadTask = wx.loadSubpackage({
  name: "/moduleA/", // Download another subpackage
  success(res) {
    console.log("load moduleA success", res);
  },
  fail(err) {
    console.error("load moduleA fail", err);
  },
});

注意事項

• 一個小遊戲中可以有多個獨立分包。
• 小遊戲獨立分包啟動只對冷啟動有效。
• 獨立分包屬於分包的一種。普通分包的所有限制都對獨立分包有效。
• 獨立分包中不能依賴主包和其他分包中的內容，包括 JS 文件和資源文件。
• wx.shareAppMessage參數或wx.onShareAppMessage回參的path必須是game.json中定義的獨立分包的root欄位。

分包加載

我們提供了 wx.loadSubpackage() API 來觸發分包的下載，調用 wx.loadSubpackage 後，將觸發分包的下載與加載，在加載完成後，通過 wx.loadSubpackage 的 success 回調來通知加載完成。

同時，wx.loadSubpackage 會傳回一個 LoadSubpackageTask，可以透過 LoadSubpackageTask 取得目前下載進度。

示例代碼：

const loadTask = wx.loadSubpackage({
  name: "stage1", // name can be either the name or the root
  success: function (res) {
    // Callback for successful subpackage loading
  },
  fail: function (res) {
    // Callback for failed subpackage loading
  },
});

loadTask.onProgressUpdate((res) => {
  console.log("Download progress", res.progress);
  console.log("Downloaded data length", res.totalBytesWritten);
  console.log("Expected total data length", res.totalBytesExpectedToWrite);
});

分包預下載

我们提供了 wx.preDownloadSubpackage() API 来触发分包的预下载，调用 wx.preDownloadSubpackage 后，将触发分包的下载与加载，在加载完成后，通过 wx.preDownloadSubpackage 的 success 回调来通知加载完成。预加载完成后，需要使用 wx.loadSubpackage 执行分包代码。

wx.preDownloadSubpackage 與 wx.loadSubpackage 的差異： wx.preDownloadSubpackage 只下載程序碼包，不自動執行程序碼；wx.loadSubpackage 下載完碼包後會自動執行程序碼。

示例代碼：

// Preload
const loadTask = wx.preDownloadSubpackage({
  name: "stage1",
  success: function (res) {
    // Callback for successful subpackage preloading
  },
  fail: function (res) {
    // Callback for failed subpackage preloading
  },
});

loadTask.onProgressUpdate((res) => {
  console.log("Download progress", res.progress);
  console.log("Downloaded data length", res.totalBytesWritten);
  console.log("Expected total data length", res.totalBytesExpectedToWrite);
});

// Execute subpackage code logic at an appropriate time
wx.loadSubpackage({
  name: "stage1",
});