页面与窗口

本页介绍微应用 UI 的入口、窗口配置以及页面开发的细节。

页面入口

manifest.json 的 entry 字段声明微应用的页面入口，指向包内的页面文件：

json

{
  "entry": {
    "url": "index.html"
  },
  "window": {
    "width": 900,
    "height": 700
  }
}

url 必须是包内相对路径，指向的文件必须存在于构建产物中；
打开微应用时，迅雷创建独立窗口并从本地加载该页面；
window.width / window.height 配置窗口内容可视区的初始宽高（单位 px），不包含标题栏和边框；
窗口标题固定为 manifest 的 title，修改页面的 document.title 不会改变窗口标题。

其它入口形式

除包内页面外，入口还支持直接打开一个已有的 Web 页面（in_app_webview 类型），适合把现成 Web 应用接入迅雷分发的场景。详见进阶 · in_app_webview 入口。

页面开发

微应用页面就是标准的 Web 前端工程：

框架自由：Vue / React / 原生 JS 均可，脚手架已内置对应模板；
构建工具：使用官方 @xunlei-open/miniapp 工具链（脚手架已内置，提供开发、构建、校验与打包命令，基于 Vite）；
类型支持：依赖 @xunlei-open/miniapp-types 后，全局对象 xunlei 自带完整 TypeScript 类型提示，无需手动声明。

// 页面代码中直接使用，无需 import
const info = xunlei.info;
const task = await xunlei.tasks.create({ req: { url: '...' } });

资源引用

页面引用的 JS / CSS / 图片 / 字体 / 媒体等资源，构建后必须位于微应用包内（远程资源会被拦截，详见能力与限制）；
使用相对路径引用包内资源，例如 <img src="./assets/logo.png">；
data: / blob: 形式的内存资源（如 Canvas 导出预览）可以正常使用。

页面内导航

页面容器内允许：

包内页面之间的跳转；
SPA 路由（history 路由 / hash 路由均可，推荐 hash 路由以获得最稳的兼容性）。

禁止（会被平台拦截）：

跳转到远程 HTTP(S) 页面；
window.open 打开新窗口；
表单提交到外部地址。

宿主环境与界面

xunlei.host 提供宿主环境信息与宿主界面操作：env 读取宿主当前状态（页面与事件脚本均可用），ui 操作宿主界面（仅页面可用，事件脚本不注入）。两者均无需权限。

// 读取宿主默认下载目录与当前主题
const dir = await xunlei.host.env.defaultDownloadDir();
const mode = await xunlei.host.env.themeMode(); // 'light' | 'dark'

// 打开宿主目录选择器，用户取消时返回 null（不视为错误）
const picked = await xunlei.host.ui.pickDirectory({ defaultPath: dir });
if (picked) {
  xunlei.logger.info('用户选择的目录', picked.path);
}

// 跳转到宿主任务列表页，可选高亮指定任务
await xunlei.host.ui.openTaskList({ taskId: task.id });

API	说明
`host.env.defaultDownloadDir()`	宿主默认下载目录（绝对路径）；用户在宿主中修改后，后续调用返回新值
`host.env.themeMode()`	宿主当前主题模式（`light` / `dark`）；宿主设置为跟随系统时返回解析后的结果
`host.ui.pickDirectory(opts?)`	打开宿主目录选择器；`opts.defaultPath` 指定对话框初始定位的目录，未指定时定位到宿主默认下载目录
`host.ui.openTaskList(opts?)`	跳转宿主任务列表页；`opts.taskId` 指定高亮的任务，任务不存在或不可见时仅跳转、不高亮

按需查询，不要缓存为常量

环境值是查询时刻的当前值：用户更换下载目录、切换主题后，后续调用返回新值。需要跟随主题时，在页面激活等时机重新查询。

生命周期

微应用窗口随用户操作打开与关闭，容器生命周期由迅雷管理；
微应用被重载、停用或卸载时，页面及其打开的辅助 WebView 会被自动关闭；
页面代码不应假设后台常驻：把需要持久化的数据及时写入 xunlei.storage。

下一步

平台能力 — xunlei 对象与权限模型
任务 API — 在页面里创建下载任务

页面与窗口 ​

页面入口 ​

页面开发 ​

资源引用 ​

页面内导航 ​

宿主环境与界面 ​

生命周期 ​

下一步 ​