更新记录

1.0.1（2026-10-16）

• 优化文档结构，将公开类型、平台支持、原生目录及各端接入步骤统一整合到示例使用说明，清理重复文档和失效入口。

1.0.0（2026-10-16）

• 新增统一实时活动接口，支持能力检查、创建、更新、结束、查询、只读恢复与事件订阅。
• 新增 Android 系统渠道适配与显式普通通知降级，返回实际提交渠道、降级原因和可见性状态；厂商胶囊需对应系统、业务准入及用户许可。
• 新增普通通知权限主动申请、拒绝后的设置引导与返回检查，支持授权超时和迟到回调处理。
• 新增活动句柄、代际与递增序号管理，以及统一参数校验、错误码和回调合同。
• 新增 uni-app Vue3 与 uni-app x 业务示例、原生诊断、脱敏日志、一键复制、固定快照分段报告及接入文档。
• 新增 iOS ActivityKit / Widget 扩展和 Harmony Live View Kit 适配源码；两端仍待原生编译、签名或完整包及设备验收，暂不声明验证通过。

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

流体云 灵动岛 实时活动与系统胶囊UTS插件

介绍

让用户切出 App 后，仍能掌握任务的下一步。lizhao-live-activity 为 uni-app 和 uni-app x 提供统一的实时活动接口，将进度、预计完成时间和服务状态交给系统展示，减少反复打开 App 查看进展的操作。

从文件传输到配送履约，用同一组 API 完成创建、更新、结束和恢复；符合设备与业务条件时接入系统活动，业务明确允许时可降级为普通通知。顶部胶囊、锁屏和通知栏的实际呈现由系统决定，不承诺所有手机都能显示同一种效果。

功能特色

• 业务调用更统一：创建、更新、结束、查询与恢复使用同一套接口，减少各品牌接入时重复维护的业务流程。
• 任务状态更可靠：活动句柄、代际和递增序号约束拦截旧请求与迟到更新，避免已结束活动被旧数据复活。
• 授权和降级有完整路径：可显式申请普通通知权限；拒绝后停止创建，必要时引导用户设置，返回后重新检查。只有业务允许才降级，保留实际渠道和原因。
• 接入问题更容易定位：通知许可、活动开关、厂商权益、业务审核、场景配置与扩展分别报告；提交成功和实际可见性分别返回。
• 示例可以直接上手：提供 uni-app Vue3 与 uni-app x 两种任务页面，包含真实 API 调用、完整诊断、一键复制及固定快照分段，不默认上传日志。

接入范围：Android 提供系统渠道适配与普通通知降级，普通通知授权及生命周期已有 MuMu 原生实测；厂商胶囊需准入并在对应真机联调。iOS / Harmony 提供适配源码，尚需完成 Apple 原生编译、扩展签名或 Harmony 完整包及设备验收，暂不标为验证通过；HONOR 系统渠道、Web 和小程序不支持。完整条件见 uni_modules/lizhao-live-activity/example/readme.md。

适合哪些场景

下载与导入

1. 在插件市场详情页通过 HBuilderX 导入，或将完整源码目录导入自己的项目。插件 ID 为 lizhao-live-activity。

2. 保留完整的 uni_modules/lizhao-live-activity/ 目录和插件名称，不单独复制 utssdk。

3. 页面只从插件根目录导入：@/uni_modules/lizhao-live-activity。uni-app 使用 .vue 页面，uni-app x 使用 .uvue 与 UTS；按下面的实际文件路径查看对应写法。

4. 在项目 pages.json 注册示例页面路径，路由不带 .vue 或 .uvue 扩展名。首次加入原生插件或原生依赖、权限、资源变化后，重新原生联编或制作并安装匹配的自定义基座；只更新页面资源无法给旧基座补入原生能力。

接入方式选择

插件不申请悬浮窗、读取全部通知或无障碍权限，不绘制仿系统胶囊。业务尚未确定时，可先接公共接口；厂商审核通过后填入对应场景配置。

示例与使用说明

公开类型、平台支持、原生目录与iOS扩展构建步骤均已整合到上述统一使用说明。

在 pages.json 注册对应示例。示例可检查能力、配置场景、创建/更新/结束、恢复句柄、检查错误并一键复制完整诊断报告。

从基础到进阶：按业务模块使用

前置：按需申请通知权限

用户点击启用通知时调用以下真实接口。默认不传requestNotificationPermission时只是检查；申请结束后必须读notificationPermission，不能仅凭success判断用户同意。

import { getLiveActivityCapabilities, LiveActivityCapabilities, LiveActivityFail } from '@/uni_modules/lizhao-live-activity'
getLiveActivityCapabilities({
  requestNotificationPermission: true,
  success: (result: LiveActivityCapabilities): void => {
    for (const channel of result.providers) {
      if (channel.provider == 'notification') {
        if (channel.notificationPermission.state == 'ready') console.log('通知已开启，可继续创建')
        else console.log('通知尚未开启，请由用户选择前往系统应用设置', channel.notificationPermission.reason)
      }
    }
  },
  fail: (error: LiveActivityFail): void => { console.log(error.errCode, error.errMsg, error.nativeMessage) },
  complete: (result): void => { console.log('授权检查已结束', result.success) }
})

此申请只涉及普通通知，不能开启厂商权益、Android promotion或ActivityKit开关。支持Android/iOS的普通通知流程，其他端显式请求返回9251002。完整示例含拒绝后的设置入口和返回刷新：uni_modules/lizhao-live-activity/example/uniappx/index.uvue、uni_modules/lizhao-live-activity/example/uniapp/index.vue。

基础：创建一条任务活动

将完整插件放入 uni_modules/lizhao-live-activity，先重新制作包含本插件的自定义基座或正式包。普通通知需先获得通知授权，可使用下面的主动申请路径；iOS 系统活动还必须构建、签名并嵌入 Widget 扩展。

下面的真实调用在可用系统活动上提交；显式允许的设备可走普通通知。缺少权限、场景或扩展时会进入 fail，请按错误处理。

import {
  startLiveActivity, updateLiveActivity, endLiveActivity,
  LiveActivityHandle, LiveActivityMutationResult, LiveActivityFail
} from '@/uni_modules/lizhao-live-activity'

let handle: LiveActivityHandle | null = null
let revision = 0

startLiveActivity({
  activityId: 'transfer-001',
  content: { title: '文件传输', statusText: '正在传输', progress: 20 },
  fallbackPolicy: 'notification',
  success: (result: LiveActivityMutationResult) => {
    handle = result.handle
    revision = result.revision
    console.log(result.provider, result.submittedPresentation, result.visibility)
    // 由业务安全保存handle与revision，不能根据业务ID重建generation。
  },
  fail: (error: LiveActivityFail) => {
    console.log(error.errCode, error.errMsg, error.provider, error.stage, error.nativeCode)
  },
  complete: (result) => { console.log('请求已结算', result.success) }
})

切后台前先在前台创建活动。该接口不保证 JS 定时器在后台运行，也不保证杀进程后继续产生业务更新。

模块一：更新进度并结束活动

更新和结束使用创建结果的同一 handle，只有成功后才推进本地 revision。所有回调均在异步边界按 success/fail → complete 顺序结算一次。

const current = handle
if (current != null) {
  updateLiveActivity({
    handle: current as LiveActivityHandle,
    revision: revision + 1,
    content: { title: '文件传输', statusText: '还剩1分钟', progress: 70 },
    success: (result: LiveActivityMutationResult) => { revision = result.revision },
    fail: (error: LiveActivityFail) => { console.log(error.errCode, error.errMsg) }
  })
}
// 上一次请求结算后再结束；示例不并发调用更新与结束。
function finishTask(): void {
  const target = handle
  if (target == null) return
  endLiveActivity({
    handle: target as LiveActivityHandle, revision: revision + 1,
    dismissalPolicy: 'immediate',
    success: (result: LiveActivityMutationResult) => { revision = result.revision; handle = null },
    fail: (error: LiveActivityFail) => { console.log(error.errCode, error.errMsg) }
  })
}

模块二：按审核场景配置系统渠道

厂商配置通过有类型的 configuration 传入。以下配置项应替换为平台为你自己的包名、签名和业务下发的值；填写配置不等于审核已通过。

import { getLiveActivityCapabilities, LiveActivityProviderConfiguration } from '@/uni_modules/lizhao-live-activity'
const configuration: LiveActivityProviderConfiguration = {
  xiaomi: { business: '平台审核的业务标识', protocol: 'auto' },
  vivo: { scene: '平台审核的场景标识', template: 'progress' },
  harmony: { event: '平台授权的事件' }
}
getLiveActivityCapabilities({
  configuration: configuration,
  success: (result) => { console.log(result.platform, result.providers) },
  fail: (error: LiveActivityFail) => { console.log(error.errCode, error.errMsg) }
})
// 创建时传同一configuration；OPPO还需environment/intentName/entityName/serviceId。

模块三：接收状态并释放订阅

独立事件订阅使用 onLiveActivityEvent(callback) 返回的令牌，再调用 offLiveActivityEvent(token) 释放自己的订阅。iOS remote-token 只回传业务，业务按自己的安全链路交给服务端；默认诊断不保存该 token。插件不包含服务端 APNs 或厂商推送平台。

模块四：恢复句柄与处理结果未知

已有句柄时用 getLiveActivity 查询；首次创建超时尚未取得句柄时，用创建前保存的稳定 activityId 调用 recoverLiveActivity，从真实登记与系统查询结果恢复。该方法只读，不创建或更新活动。得到超时或未知提交结果后先查询，不自动重试创建。完整调用见两种宿主的示例页。

API 用途速查

成功结果包含 requestId、handle、revision、provider、requestedPresentation、submittedPresentation、submissionState、visibility、visibilitySource、fallbackReason、nativeCode/nativeMessage。visibility=unknown 表示系统没有可核实的展示回执，不是失败，也不能解释为可见。

超时、无效回执，或9251017中“原生提交后登记写入失败”等不确定结果，先通过getLiveActivity或recoverLiveActivity查询核验，再决定下一步。收到fail不代表原生操作一定未发生，不能据此自动重建或重试。

查询返回 found 和 snapshot（不存在为null）；snapshot分别报告注册状态、原生状态及观察来源。超时9251020表示提交结果未知，业务先查询核对，不立即自动重试创建/更新。首次创建尚未取得句柄时，调用recoverLiveActivity({activityId, success, fail, complete})，从snapshot.handle恢复登记的generation；它不会重试创建，登记损坏时也不伪装没有活动。业务应在创建前保留稳定activityId。事件包括状态、点击、关闭、远程token和错误；平台不能可靠提供的事件不会伪造。

错误码说明

errSubject 固定为 lizhao-live-activity。fail还保留 api/requestId/provider/stage、脱敏原生代码、类型、原因、堆栈和retryAfterMs；0不表示允许立即重试。

注意事项

权限、平台差异与基座

市场兼容标记：√ 表示支持，x 表示不支持，- 表示尚不确定。Android 的支持标记不表示每台设备都有顶部胶囊，也不表示所有品牌业务资格已开通。

各端的源码、编译与设备记录分别列在 uni_modules/lizhao-live-activity/example/readme.md。iOS/Harmony 的 - 不能解读成即买即用或已完成真机适配。

Android配置声明POST_NOTIFICATIONS、POST_PROMOTED_NOTIFICATIONS；后者仅对应支持的系统。默认能力查询只读；用户点击授权或创建前需要通知许可时，显式设置requestNotificationPermission=true。Android13+未授予时请求系统权限，低版本不请求不存在的运行时权限；iOS仅未决定时弹普通通知授权。已拒绝、通知总开关或专属渠道关闭时，由示例提示用户打开系统应用设置，返回后重新检查，不能把“设置已打开”当作已授权。不用前台服务维持页面定时器；厂商权益、通知许可、实时活动开关和场景审核仍为独立条件。

授权需要前台上下文，并发申请明确失败；原生权限等待上限90秒，公共请求等待上限120秒。授权被拒绝时能力查询可成功返回，但notificationPermission仍为blocked，不代表有权发送通知。超时后先只读查询，不自动重试或创建；纯startLiveActivity仍按已有许可检查，不隐藏弹窗。示例在创建前负责按需发起显式申请。Harmony/Web/小程序尚未适配此申请选项，返回9251002，不影响默认只读查询。

iOS必须按 uni_modules/lizhao-live-activity/example/readme.md 的“iOS扩展接入”章节在Mac/Xcode编译扩展，将正式签名appex放入uni_modules/lizhao-live-activity/utssdk/app-ios/Plugins（需自行创建的扩展输出目录），并配置宿主nativeResources/ios/ios-extension.json。仅复制Swift源码不能替代扩展；不要将证书、私钥或生产描述文件提交插件。

iOS的PrivacyInfo.xcprivacy声明仅为迁移本应用自己的历史登记而访问UserDefaults，采用CA92.1；不读取其他应用的数据。理由含义见Apple required reason API说明。活动登记与诊断保留在本机，不默认上传。

新建后将App切后台，系统可继续展示已创建活动；杀进程后的业务更新需要APNs或厂商服务端通路。本插件不承诺所有品牌/机型/旧系统都可在顶部刘海区显示。

需要重新制作匹配的自定义基座或原生包。 原生UTS、Kotlin/Swift/ArkTS、权限资源、Widget扩展、平台配置或构建身份改变后均需重新联编；appResource/WGT不能替换旧基座里的原生代码。具体可用性以能力查询、匹配的原生包及目标设备结果为准，转换或导出不能替代设备验收。

• 系统接受提交不等于胶囊可见；visibility=unknown 不能当作已经展示。
• 切后台后更新依赖实际平台通路，不保证JS定时器持续运行。
• 不复用旧代际，不更新已结束或被用户关闭的活动；降级为普通通知需要业务显式同意。

作者系列 UTS 插件

以下为作者已在 DCloud 插件市场上架的 UTS 插件，可按业务场景组合使用。最新发布内容可查看作者主页。