离线应用
1. 离线应用概述
产品背景
本离线应用功能主要应用于矿山等无信号、无网络环境下进行资产盘点作业。由于传统在线轻应用无法在断网环境中运行,亟需构建一套可在本地运行的离线解决方案。
目的
为用户提供在网络不可达区域仍可正常使用轻应用的能力,保障核心业务(如资产盘点)的连续性和可靠性。
整体说明
- 支持范围:公有云平台与私有化系统均支持该功能。
- 计费模式:此功能为独立计费项,企业需开通后方可使用相关能力。
- 功能依赖:基于现有"网页应用"能力扩展,增加"离线包管理"模块。
- 使用前提:管理员需开启离线包开关,才能上传离线包。
2. 身份认证与免登机制
JS-API的身份认证与免登功能专为轻应用设计,非轻应用网页不可调用。
使用限制
- 所有API仅可在轻应用上下文中调用。
- 用户取消关注轻应用后,相关缓存文件将被清空。
接口通用参数
所有接口支持以下回调参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| success | Function | 否 | 接口调用成功的回调函数 |
| fail | Function | 否 | 接口调用失败的回调函数 |
getAuthCode:获取免登授权码
用于获取一次性的应用免登授权码 qt_code,供后端换取用户身份信息。
调用方式
qt.getAuthCode({
success: function(res) {
// res.qtCode 即为授权码
}
});
success 返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qtCode | String | 授权码,仅能使用一次,使用后即失效 |
⚠️ 注意:
qtCode具有一次性和时效性,建议立即传至服务端处理。
getUserInfo:获取用户信息
用于直接获取当前用户的公开信息。
调用方式
qt.getUserInfo({
success: function(res) {
// res.name, res.avatarUrl
}
});
success 返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| name | String | 用户名 |
| avatarUrl | String | 用户头像URL |
3. 文件操作API
文件操作API允许离线应用预加载资源并进行本地管理,提升用户体验和性能。
qt.file.download:下载文件到本地
将远程文件缓存至本地,避免重复请求。
调用方式
qt.file.download({
url: "https://example.com/file.jpg",
localId: "https://resource/unique_id", // 或 iOS: qingtui://resource/unique_id.jpg
header: {'content-type': 'image/jpeg'}, // 可选
showProgress: false // 是否显示进度条,默认false
});
请求参数
| 编号 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 1 | url | string | 是 | 文件服务器提供的完整下载地址 |
| 2 | localId | string | 是 | 本地唯一标识符 • 安卓/鸿蒙: https://resource/文件唯一标识符• iOS: qingtui://resource/文件唯一标识符.文件后缀 |
| 3 | header | object | 否 | HTTP请求头,如 { 'content-type': 'image/jpeg' } |
| 4 | showProgress | bool | 否 | 是否显示下载进度,默认为 false;批量下载时不建议设为 true |
qt.file.remove:删除本地缓存文件
根据 localId 删除已缓存的本地文件。
调用方式
qt.file.remove({
localId: "https://resource/unique_id"
});
请求参数
| 编号 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 1 | localId | string | 是 | 要删除的文件本地ID |
qt.file.read:读取本地文件(仅iOS)
iOS客户端需通过此接口读取本地文件内容,采用分片传输机制。
调用方式
qt.file.read({
localId: "qingtui://resource/unique_id.jpg"
});
返回参数(success回调)
| 参数 | 类型 | 说明 |
|---|---|---|
| localId | string | 当前读取的文件本地ID |
| partCount | int | 分片总数 |
| partNumber | int | 当前分片编号,从1开始 |
| body | string | 当前分片的Base64编码字符串 |
📌 说明:当
partNumber == partCount时表示文件传输结束。
fail 错误码
| 错误码 | 说明 |
|---|---|
| 404 | localId对应本地资源不存在 |
💡 提示:安卓与鸿蒙系统可通过
localId直接访问文件,无需调用read接口。
4. 离线应用功能详解
管理后台功能
创建应用
- 在原有"网页应用"基础上增加"离线包管理"功能。
- 需配置客户端离线包URL,用户点击应用图标时将打开离线包。
- 开启"离线包"开关后,才出现"上传离线包"按钮。
计费项控制
| 场景 | 行为 |
|---|---|
| 企业未开通计费项 | 点击"上传离线包"时弹出付费功能提示 |
| 企业曾开通但已停服 | 不允许上传新离线包,历史版本仍可使用 |
上传离线包
支持上传ZIP格式离线包,最大不超过10M。
校验规则
| 编号 | 校验时机 | 校验内容 | 规则 | 提示信息 |
|---|---|---|---|---|
| 1 | 点击上传按钮时 | 是否已有未发布的版本 | 不允许多个未发布版本共存 | 当前已有未发布的离线包 |
| 2 | 打开文件选择器 | 文件格式 | 仅支持 .zip 格式 | 过滤非zip文件 |
| 3 | 点击打开文件 | 文件大小 | ≤10MB | 离线包大小不能超过10M |
| 4 | 上传过程中 | 版本号是否存在 | 包内必须包含有效版本号 | 未检测到正确的版本号,请检查后重新上传 |
| 5 | 上传过程中 | 版本号比对 | 不能低于当前版本,不能重复上传 | 不能低于当前版本 / 不能重复上传版本 |
⚠️ 上传中断行为:
- 用户可点击取消上传,无需二次确认;
- 若关闭页面或返回上级,上传自动取消。
离线包构建规则
| 类别 | 规则说明 |
|---|---|
| 版本号 | 格式为 XX.XX.XX,每位为0-99之间的数字,建议代表"大版本.小版本.热修版本";版本比较按数值大小进行 |
| 离线包ID | 每个应用唯一,8位数字,系统自动生成,不可更改 |
| 离线版本ID | 每个上传版本的内部存储ID,研发用途,命名应区别于离线包ID |
离线包列表
- 排序规则:按版本倒序排列,高版本在上。
- 版本来源:取自离线包内的版本号信息。
- 操作时间:记录最后一次操作的时间及操作人姓名。
状态与操作映射
| 当前状态 | 可执行操作 | 操作说明 |
|---|---|---|
| 未发布 | 发布、删除、下载 | 初始状态 |
| 已发布(当前版本) | 回到上一版本、下载 | 仅当存在更早版本时显示"回到上一版本" |
| 已发布(非当前) | 下载 | 更高版本已发布 |
| 已更新 | 下载 | 被更高版本覆盖 |
| 已回退 | 下载 | 曾被回退过 |
🔔 操作提示:
- 发布:确认发布后覆盖当前版本,旧版本不可用。
- 删除:需二次确认是否删除。
- 回到上一版本:只能回退一个版本,跳过"已回退"状态版本。
- 下载:浏览器原生下载功能。
异常处理:多人操作冲突
当多个管理员同时操作同一离线包时:
- 点击"发布、删除、回退"前校验数据一致性;
- 若发现其他管理员已操作,弹窗提示:"页面数据有变化,刷新后重试";
- 点击【确定】后刷新页面。
应用下架
| 操作 | 行为说明 |
|---|---|
| 关闭"网页应用"能力 | 若无其他能力启用,且应用有使用者,则提示需保留至少一项能力;否则可直接关闭 |
| 手动下架应用 | 应用管理页面封存,仅保留历史记录,"下载"按钮可用;重新上架后功能恢复 |
| 无离线包/入口的应用 | 直接关闭,不显示任何功能入口 |
离线包关闭
- 用户可手动关闭离线包功能;
- 关闭后所有操作按钮置灰不可用;
- 访问时提示:"页面不见啦"。
客户端功能
添加/移除应用
| 操作 | 行为说明 |
|---|---|
| 添加应用 | 自动触发离线包下载,下载中不可使用 |
| 移除应用 | 清除本地离线包数据 |
| 修改为离线地址 | 已关注用户在下次打开轻推时自动下载离线包 |
| 修改为在线地址 | 不立即清除离线包,待用户取消关注时再删除 |
| 首次下载中点击使用 | 显示下载进度和"正在加载"提示 |
| 下载失败 | 自动重试 |
离线包更新
| 场景 | 行为说明 |
|---|---|
| 打开轻推时检测更新 | 后台静默下载新版本,用户无感知 |
| 更新未完成时点击使用 | 打开已下载的老版本 |
| 正在使用时更新完成 | 继续使用当前版本,不影响操作 |
| 从悬浮窗进入 | 若新版本已更新完成,则打开新版本;若页面不存在则跳转首页 |
离线包下载/更新触发条件
以下任一操作会触发离线包检查与下载/更新:
- 点击悬浮窗进入应用
- 点击消息进入应用
- 点击"进入轻应用"按钮
- 点击工作台图标打开应用
⚠️ 加载行为:
- 未下载:进入加载页,提示"正在下载",完成后方可使用。
- 有更新且联网:进入加载页,提示"正在更新";若超5秒未完成,提供"下次再更新"选项,点击需二次确认。
- 有更新但无网:直接进入老版本。
- 访问非本人关注的离线应用:统一提示"页面不见啦"。
5. 其他能力
离线扫码
支持扫描设备二维码,在无网络情况下:
- 若二维码对应的信息已预下载至本地,可直接解析并跳转至落地页;
- 实现本地数据匹配与快速响应。
网络判断机制
- 应用具备网络环境监听能力;
- 当检测到网络恢复或切换时,自动尝试上传本地缓存数据;
- 保证离线期间产生的数据最终同步至服务器。
离线缓存能力
- 提供稳定的数据缓存服务;
- 支持结构化数据、文件资源的持久化存储;
- 防止因断网、崩溃等原因导致数据丢失;
- 结合JS-API实现高效读写控制。
6. 开发注意事项
使用限制
- 所有JS-API仅限在轻应用中使用,普通网页无法调用。
- 用户取消关注轻应用时,系统将自动清空其相关的所有缓存文件。
qt.file.download的localId必须符合平台规范(iOS与安卓/鸿蒙不同)。qt.file.read仅适用于iOS,安卓与鸿蒙通过URI直接访问。
错误码处理
| 错误码 | 触发场景 | 建议处理方式 |
|---|---|---|
| 404 | localId 对应的本地资源不存在 | 检查文件是否已正确下载,或是否已被删除 |
兼容性要求
- 文档中提及需明确兼容性需求,但未给出具体机型、操作系统版本或浏览器类型列表。
- 建议开发前与产品团队确认兼容范围,确保覆盖主流设备。
性能与安全建议
- 性能优化:确保页面滚动流畅,输入反馈及时,减少卡顿。
- 断网体验:断网状态下仍能浏览本地缓存内容。
- 安全机制:账户在其他终端修改密码后,当前会话应立即失效并退出。
7. 附录
API参考
| 编号 | API名称 | 功能说明 | 平台限制 |
|---|---|---|---|
| 1 | qt.getAuthCode | 获取免登授权码qt_code | 轻应用专用 |
| 2 | qt.getUserInfo | 获取用户姓名与头像 | 轻应用专用 |
| 3 | qt.file.download | 下载文件至本地缓存 | 轻应用专用 |
| 4 | qt.file.remove | 删除本地缓存文件 | 轻应用专用 |
| 5 | qt.file.read | 读取本地文件内容(iOS分片返回) | 仅iOS需调用,安卓/鸿蒙直接访问 |
参数说明
通用参数
| 参数 | 类型 | 说明 |
|---|---|---|
| success | Function | 成功回调函数 |
| fail | Function | 失败回调函数 |
qt.file.download 参数
| 参数 | 类型 | 说明 |
|---|---|---|
| url | string | 远程文件地址 |
| localId | string | 本地唯一标识,遵循平台规范 |
| header | object | 可选HTTP请求头 |
| showProgress | boolean | 是否显示进度条 |
qt.file.read 返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| localId | string | 文件本地ID |
| partCount | int | 总分片数 |
| partNumber | int | 当前分片序号(从1开始) |
| body | string | Base64编码的分片数据 |
错误码对照表
| 错误码 | 说明 | 可能原因 | 建议措施 |
|---|---|---|---|
| 404 | localId对应本地资源不存在 | 文件未下载成功、已被删除、路径错误 | 重新下载或检查localId有效性 |