平台能力

微应用运行时自动注入全局对象 xunlei，它是微应用访问宿主能力的唯一入口。本页是 API 总览与权限模型，各模块的详细用法见对应章节。

调用约定

• 访问宿主能力一律返回 Promise：任务、存储、WebView 等异步 API 都需要 await；
• 只读快照与日志是同步的：xunlei.info、xunlei.settings 属性读取和 xunlei.logger.* 不返回 Promise；
• 无需引入：xunlei 是全局对象，页面与事件脚本中直接使用；TypeScript 工程依赖 @xunlei-open/miniapp-types 即可获得类型提示。

API 总览

模块	能力	所需权限	详细文档
xunlei.info	微应用自身信息（identity / name / author / title / version），只读	无	数据与日志
xunlei.logger	日志输出（debug / info / warn / error）	无	数据与日志
xunlei.settings	读取用户设置（只读快照，按 manifest.settings[].name 挂载）	无	数据与日志
xunlei.storage	页面与事件脚本共享的键值对存储（get / set / remove / clear / keys），按微应用隔离并持久化	无	数据与日志
网络请求（fetch 等）	访问 network.urls白名单内的地址	network	能力与限制
xunlei.tasks	下载任务管理（create / createGroup / list / detail / update / delete / file.access）	按具体方法声明权限，见下表	任务 API
xunlei.events	注册生命周期事件回调（onResolve / onStart / onError / onDone）	无	钩子事件
xunlei.runtime.blob	把 Blob / 数据流转为可下载的临时 URL	blob	任务 API · Blob 与数据下载
xunlei.runtime.webview	打开受控辅助 WebView（页面数据提取、表单操作）	webview	辅助 WebView
xunlei.host.env	宿主环境查询（默认下载目录 / 主题模式），页面与事件脚本可用	无	页面与窗口
xunlei.host.ui	宿主界面操作（目录选择器 / 跳转任务列表），仅页面可用	无	页面与窗口

权限模型

涉及宿主敏感资源的能力，必须在 manifest 的 permissions 中预先声明：

权限	保护对象	说明
network	直接网络请求	配合 network.urls 白名单使用，见网络白名单
tasks.create	xunlei.tasks.create、xunlei.tasks.createGroup	创建下载任务或任务组
tasks.list	xunlei.tasks.list	查询任务列表
tasks.detail	xunlei.tasks.detail	查询任务详情
tasks.file.access	xunlei.tasks.file.access	获取任务文件的只读访问 URL
tasks.update	xunlei.tasks.update	修改任务
tasks.delete	xunlei.tasks.delete	删除任务（含删除文件）
blob	xunlei.runtime.blob	完整的 Blob 数据转 URL 能力
webview	xunlei.runtime.webview	完整的辅助 WebView 能力

不需要权限的能力：存储、日志、设置读取、xunlei.info、事件注册、xunlei.host。

校验语义

理解权限模型的三个要点：

1. API 表面不收缩：xunlei.tasks 始终以完整形态暴露，未声明权限时调用对应方法会返回 PERMISSION_DENIED 错误（而不是方法消失），便于统一做错误处理：

   try {
     await xunlei.tasks.list();
   } catch (error) {
     // error.code === 'PERMISSION_DENIED'
     // error.details.permission 为缺失的权限名，如 'tasks.list'
   }

2. 页面与事件脚本均可调用任务 API：两个运行时都注入完整的 xunlei.tasks，各方法按上表对应的权限校验。未声明 webview 权限时，isAvailable() 返回 false，open() 返回 PERMISSION_DENIED。

3. 事件上下文单独授权：scripts[].event 与 scripts[].match 声明了事件脚本的触发范围。ctx.task.meta.req.setUrl()、ctx.task.continue() 等上下文方法不受任务权限控制；事件脚本直接调用 xunlei.tasks 方法时仍须声明对应权限。

权限不足 vs 宿主能力不可用

权限不足返回 PERMISSION_DENIED；宿主侧能力暂时不可用（如任务系统未就绪）属于其它错误类型。两者错误码不同，排查问题时先区分。

错误格式

平台 API 的错误统一为 { code, message, details } 结构，常见错误码及处理建议见错误码。

下一步

• 任务 API — 微应用最核心的能力
• 数据与日志 — 存储与设置