qg.loadSubpackage

基础信息说明

功能概述：触发小游戏分包加载，获取加载进度及结果

项目	说明
版本要求	无
前提条件	已在工程配置中声明对应分包
使用限制	无
相关教程	无

参数说明

qg.loadSubpackage(option)

属性名	类型	说明
name	String	分包的名字，需要和分包配置中的值对应，支持配置中的 name 或 root
success	Function	分包加载成功回调，回调参数为底层 onload 返回的数据（通常为空对象）
fail	Function	分包加载失败回调，回调参数结构为 { errMsg, errcode, statusCode }
complete	Function	分包加载完成回调（无论成功失败都会执行），参数同 success/fail

返回值说明

同步方法：qg.loadSubpackage() 为同步接口，调用后立即返回 LoadSubpackageTask 实例。

属性名	类型	说明
loadSubpackageTask	LoadSubpackageTask	分包加载任务对象，用于监听进度

LoadSubpackageTask 对象方法

方法名	类型	说明
onProgressUpdate(callback)	Function	订阅分包加载进度事件，回调参数为 { progress, totalBytesWritten, totalBytesExpectedToWrite }
offProgressUpdate(callback)	Function	取消订阅对应的进度事件

回调结果说明

success、fail、complete 以及 onProgressUpdate 注册的回调均为异步事件，由底层 system.distribution.loadSubpackage 在加载流程中触发。
触发时机如下：

success：分包资源加载完成后触发
fail：加载过程中发生错误触发
complete：加载流程结束后触发（成功或失败都会执行）
onProgressUpdate：加载过程中多次触发进度更新

回调成功

success / complete 成功形态

属性名	类型	说明
data	any	底层 loadSubpackage 成功回调数据（通常为空对象）

onProgressUpdate 回调

属性名	类型	说明
progress	Number	加载进度百分比（0-100）
totalBytesWritten	Number	已下载字节数，单位 Bytes
totalBytesExpectedToWrite	Number	预计需要下载的总字节数，单位 Bytes

回调失败

fail / complete 失败形态

属性名	类型	说明
errMsg	String	错误描述
errcode	Number	错误码，常见值：1000（分包不存在）、1001（参数错误）、1003（内部异常），或底层 errorCode

注：失败回调不包含 statusCode 字段；若需定位底层错误，请参考 errcode 与日志

错误码

错误码	错误信息	说明
1000	分包不存在	调用的分包未在工程配置中声明或名称错误
1001	参数错误	未传入 name 时立即回调 fail/complete
1003	内部错误	调用底层 loadSubpackage 发生异常
-	err.errorCode	底层返回的其他错误码

示例代码

// 触发分包加载
const task = qg.loadSubpackage({
  name: 'package-b',
  success(data) {
    console.info('加载分包 package-b 成功')
  },
  fail(err) {
    console.info('加载分包 package-b 失败', err)
  },
  complete(res) {
    console.info('分包加载结束', res)
  }
})

// 监听加载进度
function handleProgress({ progress, totalBytesWritten, totalBytesExpectedToWrite }) {
  console.log('package-b 下载进度', progress)
  console.log('package-b 已经下载的数据长度', totalBytesWritten)
  console.log('package-b 预期需要下载的数据总长度', totalBytesExpectedToWrite)
}

task.onProgressUpdate(handleProgress)

// 如需停止监听
// task.offProgressUpdate(handleProgress)

注意事项

name 为必填项，缺失时任务不会启动
主包或子包不能引用未加载的包中的模块
回调函数引用需一致，才能通过 offProgressUpdate 正确移除
建议在 complete 回调中进行资源释放或状态清理

上一篇:API概览

下一篇:触摸事件

文档内容是否有帮助？

有帮助

无帮助