文档中心

setGameLoadSubpackageListener ​

设置加载小游戏分包监听器 ​

setGameLoadSubpackageListener 用于处理小游戏的分包（Subpackage）加载请求。为了优化首次启动速度，大型小游戏通常会将资源拆分为多个分包。当游戏运行到需要特定资源的代码时，引擎会触发此回调，要求宿主 App 完成对应分包的下载与安装。

方法声明 ​

java
/**
 * 设置加载小游戏分包监听者
 * * @param listener 分包加载监听器。当小游戏逻辑请求加载分包时触发回调。
 */
void setGameLoadSubpackageListener(SUDRTGameHandle.GameLoadSubpackageListener listener);

内部接口与 Handle ​

java
public interface GameLoadSubpackageListener {
    /**
     * 当小游戏请求加载分包时回调
     *
     * @param handle 用于向引擎反馈分包下载/安装的结果与进度
     * @param root   分包的标识（通常对应游戏配置中的 root 字段），用于拼凑下载 URL
     */
    void onLoadSubpackage(SUDRTGameHandle.GameLoadSubpackageHandle handle, String root);
}

运行流程 ​

  1. 触发：JS 层调用 wx.loadSubpackage 或类似 API。
  2. 回调：SDK 触发 onLoadSubpackage，并传入 root 参数。
  3. 下载：宿主 App 根据 root 从自己的 CDN 下载对应的分包资源（通常是 .zip 或目录）。
  4. 反馈：

  • 下载中：调用 handle.progress(written, total) 更新进度条。

  • 成功：调用 handle.success(absolutePath)，告知引擎分包解压后的存放路径。

  • 失败：调用 handle.failure(errorMsg)。

代码示例 ​

java
gameHandle.setGameLoadSubpackageListener(new SUDRTGameHandle.GameLoadSubpackageListener() {
    @Override
    public void onLoadSubpackage(SUDRTGameHandle.GameLoadSubpackageHandle handle, String root) {
        // 1. 根据 root 拼接下载地址
        String downloadUrl = "https://cdn.example.com/game/subpackages/" + root + ".zip";
        
        // 2. 执行下载逻辑 (伪代码)
        Downloader.download(downloadUrl, new DownloadCallback() {
            @Override
            public void onProgress(long current, long total) {
                // 通知引擎下载进度，游戏内进度条会随之变化
                handle.progress(current, total);
            }

            @Override
            public void onFinish(File file) {
                // 3. 下载并解压完成后，告知引擎分包所在的绝对路径
                // 如果传 null，引擎会尝试使用默认的路径推导机制
                handle.success(file.getParent());
            }

            @Override
            public void onError(String error) {
                // 告知引擎加载失败，JS 层会进入 fail 回调
                handle.failure(error);
            }
        });
    }
});

注意事项 ​

  • 路径要求：handle.success 传入的路径应该是包含分包资源的文件夹路径，且该文件夹结构需符合小游戏包规范（包含 game.js 等）。
  • 并发处理：虽然 SDK 通常会排队请求分包，但宿主 App 的下载逻辑应具备处理并发或重复请求的能力。
  • 用户体验：分包加载通常发生在游戏过程中，建议在 onLoadSubpackage 开始时显示原生的加载 Loading 或确保游戏内有相应的 UI 提示。