更新记录

1.0.0(2026-11-18)

第一版


平台兼容性

uni-app(4.51)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ - - √ √ 6.0 15 √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(4.51)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - 6.0 15 √ -

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

wen-live-activity

Android 实时进度通知、iOS Live Activities 和鸿蒙实况窗接入。

功能介绍

  1. 创建、更新、暂停、恢复、结束与删除实时活动。
  2. 标题、摘要、进度、倒计时、按钮与主题样式配置。
  3. 实例标识、版本冲突检测及用户操作事件读取。
  4. 活动列表、本机状态持久化、过期及恢复处理。

平台兼容性

项目 要求
HBuilderX 5.26 或更新版本
uni-app / uni-app x Vue 3;原生 App
Android API 23 起;部分系统能力有更高版本要求
iOS 16.2 起;以设备能力及宿主配置为准
HarmonyOS 使用 app-harmony 源码及其声明的 SDK / 权限
Web / 小程序 不提供原生能力

插件测试使用方法

  1. 在插件市场绑定自己的项目 AppID,将插件导入项目的 uni_modules/wen-live-activity。本地使用时也可直接复制完整插件目录。
  2. 打开“示例项目”,在 HBuilderX 的 manifest 中填写自己的 AppID。需要第三方服务时填写自己申请的配置。
  3. 制作包含本插件的自定义基座,或重新云打包 App。标准基座、WGT 热更新不能增加原生模块。
  4. 安装到真机,授予本次操作所需的系统权限,再使用页面中的功能按钮。
  5. 更换原生依赖、权限或平台配置后重新打包。示例源码和文档不附带 Key、Token、账号密码或签名私钥。

使用示例

import { nativeLiveActivityRequest } from '@/uni_modules/wen-live-activity'

nativeLiveActivityRequest('start', JSON.stringify({
  "activityId": "order-001",
  "config": {
    "title": "配送进度",
    "text": "骑手正在配送",
    "progress": 35
  },
  "consent": true
}), (raw: string) => {
  const result = JSON.parseObject(raw)
  if (result == null) return
  if (result.getNumber('code') != 0) {
    uni.showToast({ title: result.getString('message') ?? '操作失败', icon: 'none' })
    return
  }
  console.log(result['data'])
})

API 介绍

原生入口接收 operation、JSON 字符串 payload 和回调。回调统一返回 { code, message?, data? };code 为 0 表示成功。

nativeLiveActivityRequest

nativeLiveActivityRequest(operation:string,payload:string,done:(result:string)=>void):void

配置参数

配置通过打开/启动操作传入;其他操作参数以示例调用为准。

参数 类型 默认值 说明
title string "任务进行中" 通知标题;最长 80
text string "实时状态会显示在通知和锁屏上" 内容摘要;最长 240
bigText string "" 展开详情;最长 1500
subText string "" 辅助标签;最长 80
shortText string "进行中" 状态栏短文本;最长 7
template enum "progress" 通知样式;可选 progress / bigText / standard
icon enum "activity" 图标;可选 activity / download / delivery / navigation / timer / workout
color string "#246BFD" 强调色;最长 7
category enum "progress" 系统分类;可选 progress / status / event / transport
progress number 0 当前进度;最小 0;最大 1000000
progressMax number 100 总进度;最小 1;最大 1000000
indeterminate boolean false 不确定进度
segments array [] 彩色进度区段
points array [] 进度里程碑
styledByProgress boolean true 按进度区分已完成部分
trackerIcon boolean true 显示进度追踪图标
endpointIcons boolean true 显示起终点图标
chronometer enum "none" 系统计时器;可选 none / elapsed / countdown
timeBaseMs number 0 计时起点或倒计时终点 UTC 毫秒;最小 0;最大 8640000000000000
showWhen boolean false 显示通知时间
ttlMs number 3600000 活动有效期毫秒;最小 1000;最大 86400000
completionTtlMs number 30000 结束通知保留毫秒,0 为移除;最小 0;最大 86400000
promote boolean true 请求系统实时活动提升
visibility enum "private" 锁屏内容可见性;可选 private / public / secret
publicTitle string "活动正在进行" 锁屏脱敏标题;最长 80
publicText string "解锁后查看详细进度" 锁屏脱敏内容;最长 240
ongoing boolean true 持续通知
onlyAlertOnce boolean true 更新不重复提醒
groupKey string "" 分组标识;最长 40
sortKey string "" 排序标识;最长 40
channelId string "live" 通道标识;最长 40
channelName string "实时活动与进度" 通道名称;最长 60
channelDescription string "展示主动开启的活动、进度与计时" 通道说明;最长 200
channelImportance enum "default" 首次创建通道重要程度;可选 low / default / high
channelSound boolean false 首次创建通道声音
channelVibration boolean false 首次创建通道振动
channelBadge boolean false 首次创建通道角标
actions array [{"id":"pause","title":"暂停","type":"togglePause"},{"id":"complete","title":"完成","type":"complete"},{"id":"open","title":"查看","type":"open"}] 通知操作按钮
actionHandling enum "event" 按钮处理方式;可选 event / state
requireUnlock boolean true 锁屏操作要求解锁
route string "/pages/live-activity/index" 点击返回页面;最长 200
metadata object {} 本地业务附加信息;最长 2048
updateIntervalMs number 1000 合并通知更新的最短毫秒间隔;最小 250;最大 10000
xiaomiEnabled boolean false 启用小米公开协议扩展
xiaomiBusiness string "progress" 小米业务场景;最长 40
xiaomiParams object {} 小米经授权模板 param_v2 内容;最长 16000

JavaScript 封装接口

普通 uni-app 页面可使用插件目录中的 client.js。调用前先完成平台权限申请;异步操作用 await / catch 处理。具体参数类型见同目录的 client.d.ts 或 index.d.ts。

createLiveActivityClient

createLiveActivityClient(transport) 返回的方法:

方法与参数 原生 operation
capabilities() capabilities
permissions() permissions
requestPermission() requestPermission
settings(kind='notifications', channelId='live') settings
channels() channels
start(config, {id='',consent=false,harmony}={}) start
configureHarmony(handle, patch, {expectedRevision}={}) configureHarmony
update(handle, patch, {expectedRevision}={}) update
pause(handle, {expectedRevision}={}) pause
resume(handle, {expectedRevision}={}) resume
end(handle, {state='completed',text,expectedRevision}={}) end
restore(handle) restore
get(activityId) get
list(limit=50, options) list
events(afterId=0, limit=100) events
recentEvents(limit=100) recentEvents
ackEvents(throughId) ackEvents
remove(handle, {expectedRevision}={}) remove
clearHistory() clearHistory
diagnostics() diagnostics
subscribe(listener, {intervalMs=1500,onError=()=>{},includeConfig=true,activeOnly=false}={}) list
subscribeEvents(listener, {afterId=0,limit=100,intervalMs=1500,onError=()=>{},acknowledge=false}={}) events

在项目页面中定制

场景预设、按钮排版、页面文案和配色由示例项目的 pages 目录及项目自身的公共文件管理;安装插件不需要接收这些页面。可以直接修改页面,或按自己的设计重新编写。插件只提供原生能力、参数默认值及校验,不再导出业务 PRESETS。

配置函数只接收配置对象,不接收场景名称;多种预设在页面里定义,再把对象传入。未提供的字段由插件补齐默认值。

import { createActivityConfig } from '@/uni_modules/wen-live-activity/client.js'

// 这份对象写在自己的页面里,字段值可由表单或业务数据产生。
const options = { title: '我的订单', text: '正在准备', progress: 20 }
const config = createActivityConfig(options)

使用注意

  • Android 展示形式为系统通知,不是 iOS 灵动岛。系统和厂商决定实际布局。
  • iOS 使用前需要在宿主工程添加随插件提供的 Widget Extension,并配置自己的 Team、Bundle ID 和能力。
  • 鸿蒙实况窗需要相应系统版本与宿主权限。远程推送凭据不在插件内生成或分发。

隐私、权限声明

1. 本插件需要申请的系统权限列表

<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.POST_PROMOTED_NOTIFICATIONS"/>
<uses-permission android:name="android.permission.VIBRATE"/>

iOS 用途说明在 app-ios/Info.plist 中,鸿蒙权限在 app-harmony/module.json5 中;宿主仍需按实际业务说明用途并配置能力。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明

处理应用传入的活动标题、摘要、进度和用户操作事件,用于本机系统展示;远程更新需由宿主配置自己的推送服务。

3. 本插件是否包含广告

不包含广告。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android:POST_NOTIFICATIONS,用于活动通知;POST_PROMOTED_NOTIFICATIONS,用于系统支持时请求实时活动提升;VIBRATE,用于用户启用的通知振动。具体授权及展示由系统版本和通知设置决定。 iOS:需要开启 Live Activities 能力并集成 Widget Extension,配置 NSSupportsLiveActivities;活动是否允许展示由系统和用户设置控制。 HarmonyOS:需要用户允许通知;实况窗还需相应平台能力、业务准入及系统开关。当前插件模块未声明相机、麦克风或定位权限。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。