帮你快速理解、总结文档立即下载

实现实况窗(Live View)功能

最近更新时间:2026-09-15 10:41:33
我的收藏

限制说明

支持的 HarmonyOS 版本、设备范围、实况窗生命周期及能力限制,请以华为官方 通用约束限制 为准。
基础实况窗卡片/胶囊由 @kit.LiveViewKit 的 liveViewManager 按系统模板管理;扩展能力请以对应官方 API 为准。
客户端版本需支持实况窗能力,建议使用最新版本接入;低版本客户端使用实况窗推送时可能出现在线推送弹窗等兼容性问题。
远程更新/结束使用华为 Push Kit,推送证书配置请参考腾讯云 HarmonyOS 推送配置。
通过 Push Kit 创建对 event 有类别限制,具体以华为 通过 Push Kit 创建和更新实况窗的约束限制 为准。
当前 IM 接入方案中,业务侧需按 REST API 文档 保持客户端 view.id 与服务端 HmPayload.activityId 对应。

接入指引

步骤1:开通 AGC 权益与工程配置

1. 开通 AGC 权益
在 AppGallery Connect 控制台为应用开通:
2. 重新下载 Profile 并校验
开通权益后,重新下载 debug/release profile,用以下命令校验其包含实况窗能力:
openssl smime -verify -inform DER -in xxx.p7b -noverify -out /tmp/p.json 2>/dev/null \\
&& cat /tmp/p.json | python3 -m json.tool
按当前工程接入排查时,请确认 Profile 中包含以下能力;不同系统/工具版本的具体要求以华为官方文档为准:
app-services-capabilities.com.huawei.service.liveView.entry
app-services-capabilities.com.huawei.service.push.base_service
debug-info.device-ids 里包含您的测试机 UDID(仅 debug profile 需要)
3. 工程配置
agconnect-services.json 放在 hap 模块根目录(entry/ 的上一级,即 demo 根目录)
build-profile.json5 中 signingConfigs.type 与 profile 类型对齐(debug profile 配 debug 类型)
module.json5 里声明实况窗相关 metadata
4. 设备侧开关
在测试机上:设置 > 通知与状态栏 > 实况窗 > 本 App,手动打开允许开关。
5. 配置鸿蒙推送证书(远程推送必需)
证书创建、上传及证书 ID 配置方式,请参考腾讯云 HarmonyOS 推送配置文档,并以华为 AGC 与腾讯云 IM 控制台当前页面要求为准。
注意:
如果 startLiveView 报 1003500005 The right of liveView is not enabled.,可优先按上述 AGC、Profile、工程配置和设备开关逐项排查;具体原因以错误信息和华为官方文档为准。
更换 profile / 证书 / AGC 配置后,建议完全卸载旧 App,再 Clean Project、Rebuild 并重新签名安装;如果仍使用旧构建产物,可能继续表现为旧权益未生效,具体以实际构建和设备状态为准。

步骤2:检查服务可用性

import { liveViewManager } from '@kit.LiveViewKit';

// 设备能力检查
if (!canIUse('SystemCapability.LiveView.LiveViewService')) {
console.log('当前设备不支持实况窗能力');
return;
}

// 运行时服务开关检查
const enabled: boolean = await liveViewManager.isLiveViewEnabled();
if (!enabled) {
// 建议降级为普通通知,或引导用户到设置里打开开关
return;
}
说明:
本文示例的实况窗创建/更新/结束直接调用华为系统 API(@kit.LiveViewKit 的 liveViewManager)。
基础实况窗卡片/胶囊由 HarmonyOS 系统按模板渲染;如果需使用锁屏扩展、扩展区域等能力,请以对应官方 API 与场景文档为准。

步骤3:代码实现

1. 构造 LiveView。
本示例使用 LiveView 的 id(业务侧自定义的 activityId)、event(业务类型)和 liveViewData(展示数据,含 primary 和 capsule)这几个字段;其他可选字段请以 SDK 声明和华为官方 API 文档为准。
primary(下拉通知栏卡片 / 锁屏卡片)
const primary: liveViewManager.PrimaryData = {
title: '正在为您叫车',
content: [{ text: '预计 3 分钟后接驾' }], // 注意:这里是 RichText[] 结构
clickAction: clickAction, // WantAgent,点击卡片时跳转
layoutData: {
layoutType: liveViewManager.LayoutType.LAYOUT_TYPE_PROGRESS,
progress: 0,
// 本示例为进度布局提供节点图标;是否必填及具体约束请以对应官方模板文档为准
nodeIcons: [
'resource://base/media/ic_public_check.svg',
'resource://base/media/tab_contact_selected.svg',
'resource://base/media/ic_public_check.svg'
]
}
};
capsule(灵动岛 / 状态栏胶囊)
// 示例显式声明为 TextCapsule,使 title/content 获得对应类型;具体声明方式以 SDK 类型检查结果为准
const capsule: liveViewManager.TextCapsule = {
type: liveViewManager.CapsuleType.CAPSULE_TYPE_TEXT, // 用枚举,不要写数字字面量
status: 1, // SDK 声明为必填 number;示例使用 1
icon: 'resource://base/media/tab_contact_selected.svg',
title: '叫车中',
content: '预计 3 分钟后接驾', // TextCapsule.content 是 string,不是 RichText[]
backgroundColor: '#FF1E90FF' // 示例使用 #AARRGGBB;具体格式以官方 API/运行时校验为准
};
组装 LiveView
const view: liveViewManager.LiveView = {
id: genLiveViewId(), // 业务侧自定义,建议直接复用订单号,它就是 activityId
event: 'TAXI', // 业务类型;本地无枚举约束,Push Kit 创建场景类别限制见官网
liveViewData: { primary, capsule }
};
关于 activityId:
startLiveView 返回的 LiveViewResult 只有 resultCode 和 message,不会返回 ID,activityId 始终是您自己传进去的 view.id。
2. 客户端操作,添加启动、更新和停止逻辑。
// start
try {
const result = await liveViewManager.startLiveView(view);
console.log(`创建成功,activityId:${view.id},resultCode:${result.resultCode}`);
} catch (error) {
console.error(`创建失败:${error.code} ${error.message}`);
}

// update:复用创建时的 view 对象,只改展示内容,ID 不变
view.liveViewData.primary.title = '司机已接单';
view.liveViewData.primary.content = [{ text: '司机已接单,正在赶来' }];
// 建议:status 与创建时保持一致,阶段变化只改 title/content
view.liveViewData.capsule = {
type: liveViewManager.CapsuleType.CAPSULE_TYPE_TEXT,
status: 1, // 与创建时一致
icon: 'resource://base/media/tab_contact_selected.svg',
title: '接驾中', // 阶段变化靠这里
content: '司机已接单,正在赶来', // 阶段变化靠这里
backgroundColor: '#FF1E90FF'
};
await liveViewManager.updateLiveView(view);

// end
view.liveViewData.primary.title = '行程结束';
view.liveViewData.primary.content = [{ text: '行程已结束' }];
view.liveViewData.capsule = {
type: liveViewManager.CapsuleType.CAPSULE_TYPE_TEXT,
status: 1, // 与创建时一致
icon: 'resource://base/media/ic_public_check.svg',
title: '行程结束',
content: '行程已结束',
backgroundColor: '#FF1E90FF'
};
await liveViewManager.stopLiveView(view);
注意:
capsule.status 在 SDK 声明中是必填 number,未说明其取值语义。建议在同一实况窗的创建/更新/结束全过程中保持不变,阶段语义通过 title / content 表达;当前工程真机实测中曾出现 update 时改变 status 后胶囊不刷新的现象。
本示例通过 title / content 表达阶段语义,并在各阶段使用 CAPSULE_TYPE_TEXT;其他胶囊类型与字段请以官方 API 文档为准。
当前工程实测中,updateLiveView 对局部 mutate 可能未触发预期刷新,建议每次更新都新建一个 TextCapsule 对象整体替换 view.liveViewData.capsule;该建议不等同于官方 API 约束。
字段类型与排查提示
以下内容结合 SDK 类型声明、当前工程实测和示例代码整理;其中标注为建议或实测的内容不等同于华为官方规范。字段类型可参考华为 liveViewManager API 参考,其余规则以官方 API 文档和实际版本校验结果为准:
字段
类型/约束
错误写法 > 报错
capsule 声明类型
示例显式声明为 liveViewManager.TextCapsule,用于匹配 title/content 字段
只标 CapsuleData > arkts-no-untyped-obj-literals。
capsule.type
liveViewManager.CapsuleType 枚举
示例使用枚举;直接写数字时请以当前 ArkTS 类型检查结果为准。
capsule.status
SDK 声明为 number 且必填;取值语义未在 SDK 注释中说明,示例使用 1
传 0 > 401 range incorrect。
capsule.content
string
传 [{ text }] > 类型不兼容。
capsule.backgroundColor
示例使用 8 位 #AARRGGBB(含 alpha);SDK 声明的类型为 string
#1E90FF(6 位)> 401 length exceeds the limit。
primary.content
RichText[](即 [{ text }])
传 string > 类型不兼容。
primary.layoutData.nodeIcons
本示例在 LAYOUT_TYPE_PROGRESS 布局下提供
不填 > 参数校验失败。
3. 服务端远程更新和结束操作。
当 App 被杀 / 用户离线 / 需要跨进程或后台定时触发更新时,可考虑使用服务端远程链路。在当前 IM 接入方案中,本地创建时使用的 view.id 需要与业务后台调用推送接口时填入的 HmPayload.activityId 保持一致;建议复用订单号等业务主键,具体字段关系以 REST API 文档 为准。
在当前 IM 接入方案中,后续链路通常包括业务后台、IM 后台与华为 Push Kit 的服务端交互:
业务后台调用 IM 后台 REST 推送接口(HarmonyInfo.PushType = 7)
IM 后台透传给华为 messages:send
华为系统远程执行 create/update/end 操作
服务端 RESTAPI 的完整字段说明与请求示例,参见 离线推送 OfflinePushInfo 说明 — 鸿蒙实况窗推送。
注意:
在当前 REST API 方案中,实况窗推送使用 HarmonyInfo.PushType = 7;HmPayload 的生效范围及其他取值的校验行为,请以 REST API 文档 为准。
在当前 IM 接入方案中,客户端 SDK 不负责远程链路绑定,通常无需由客户端额外上报 token 或绑定关系;服务端推送依赖步骤1 中上传到 IM 控制台的鸿蒙证书(证书 ID)。
远程创建(operation=0)的 event 场景限制请以 华为官方约束限制 为准;不满足远程创建条件的场景,可按业务需要先采用本地创建。
HarmonyInfo.HmPayload 对应的 JSON Object 格式说明
字段名称
类型
选项
字段说明
activityId
Integer
必填
实况窗活动 ID,按当前 REST API 接入约定应与客户端创建实况窗时传入的 view.id 对应;建议复用订单号等业务主键,具体唯一性要求以服务端文档为准。
operation
Integer
必填
操作类型:0-创建,1-更新,2-结束。
event
String
必填
业务事件类型。通过 Push Kit 创建对 event 类别有限制,本地创建 view.event 为 string、无枚举约束。具体清单与限制场景见 通过 Push Kit 创建和更新实况窗的约束限制。
status
String
必填
当前业务状态,业务自定义(例如 HEADING_TO_DESTINATION)。notificationData.contentTitle 中可通过 {{status}} 占位符引用该字段。
version
Integer
必填
实况窗通知版本号,同一实况窗(activityId)内递增。
activityData
JSON Object
必填
实况窗展示数据:notificationData 为下拉通知栏/锁屏卡片数据,capsuleData 为灵动岛/状态栏胶囊数据。字段详情参见 华为官方文档。
REST API 请求示例
完整字段说明与请求示例请参考 鸿蒙实况窗推送。
{
"OfflinePushInfo": {
"HarmonyInfo": {
"PushType": 7,
"HmPayload": {
"activityId": 55,
"operation": 1,
"event": "TAXI",
"status": "HEADING_TO_DESTINATION",
"version": 2,
"activityData": {
"notificationData": {},
"capsuleData": {}
}
}
}
}
}
operation 用于区分创建、更新和结束,具体取值及字段要求请以 REST API 文档为准。
4. 更新频率限制。
通过 Push Kit 更新实况窗时,华为按业务场景实施频控(例如出行打车与赛事比分场景频控额度高于其余场景),超过频次部分将丢弃不下发。具体频控数值以华为官方文档为准,参见 通过 Push Kit 创建和更新实况窗的约束限制。

实践场景

接入前 Checklist

以下清单可用于接入前自查;具体要求以华为和腾讯云对应版本文档为准:
分类
检查项
AGC 与 Profile
AGC 已开通”推送服务权益“ + “实况窗服务权益”。
Profile 里含 com.huawei.service.liveView.entry + com.huawei.service.push.base_service。
Profile debug-info.device-ids 里有测试机 UDID(debug profile)。
工程配置
agconnect-services.json 放在 hap 模块根目录(entry/ 的上一级)。
module.json5 声明了实况窗相关 metadata。
build-profile.json5 的 signingConfigs.type 与 profile 类型对齐。
编码约束
capsule 显式声明为 liveViewManager.TextCapsule。
示例中 capsule.type 使用枚举 CAPSULE_TYPE_TEXT。
capsule.status 建议全生命周期保持不变(阶段变化只改 title/content)。
capsule.content 是 string,primary.content 是 RichText[]。
capsule.backgroundColor 是 8 位 #AARRGGBB。
LAYOUT_TYPE_PROGRESS 布局下 primary.layoutData.nodeIcons 已填。
设备与安装
测试时确认设备“设置 > 通知与状态栏 > 实况窗 > 本 App”允许开关已按系统提示开启。
更换配置后建议完全卸载 > Clean > Rebuild > 冷启动;如果遇到旧权益或旧配置问题,以实际构建产物和设备状态为准。
服务端
IM 控制台已上传鸿蒙证书(AGC 服务账号密钥 JSON),证书 ID 已就绪。
业务后台 HmPayload.activityId 与客户端 view.id 保持对应(建议复用订单号)。
实况窗推送使用 HarmonyInfo.PushType = 7。

常见报错速查

接入过程中高频出现的报错与现象,按下表定位:
报错 / 现象
原因
解决
startLiveView 报 1003500005 The right of liveView is not enabled.
实况窗权益未生效
建议依次排查:
1. AGC 是否开通“推送服务权益" + "实况窗服务权益”;
2. Profile 是否含 com.huawei.service.liveView.entry 和 com.huawei.service.push.base_service(用步骤1 的 openssl 命令校验);
3. 测试机 UDID 是否在 debug-info.device-ids 里;
4. 设备实况窗开关是否打开;
5. 更换配置后是否重新安装了 App。
换新 profile 后依然报 1003500005
旧 hap 里嵌入的还是老 profile,系统按老权益判定
建议完全卸载 App > Clean Project > Rebuild > 重新签名安装;如果覆盖安装或热重载后仍异常,再按该流程重试。
编译报 Object literal must correspond to some explicitly declared class or interface / Property 'title' does not exist on type 'TimerCapsule'
capsule 未显式声明类型
显式声明为 liveViewManager.TextCapsule,不能只标 CapsuleData 或省略类型。
startLiveView 报 401 The type of capsule.status must be number [or the parameter range is incorrect]
status 传了 0
SDK 仅声明该字段为必填 number;当前环境传 0 曾返回此错误,具体取值范围以官方文档和实际版本校验为准。
startLiveView 报 401 The type of capsule.backgroundColor must be string [or the parameter length exceeds the limit]
当前环境中传入 6 位 RGB 时出现该报错
当前示例改用 8 位 #AARRGGBB,例如 #1E90FF > #FF1E90FF;具体格式以官方 API 与运行时校验为准。
updateLiveView 返回成功,但灵动岛胶囊没刷新,primary 卡片却刷新了
实测中曾出现:update 时改变了 capsule.status(例如用 1/2/3 表示阶段)。官方未定义该字段取值语义,此为实测现象
可尝试让 status 在同一实况窗内保持不变,阶段变化只通过 title / content 表达。
LAYOUT_TYPE_PROGRESS 布局报"参数校验失败"
当前环境中未填写 primary.layoutData.nodeIcons 时出现该问题
当前示例传入 Array<string | image.PixelMap>,节点数量按业务阶段配置;具体必填性和数量要求以官方模板文档为准
远程 Push 下发实况窗一直不到达
双端 ID 不一致 / PushType 有误 / event 不支持远程创建
建议确认 IM 控制台鸿蒙证书已上传且有效;确认 HmPayload.activityId 与客户端 view.id 保持对应;确认 HarmonyInfo.PushType = 7;Push Kit 创建(operation=0)对 event 类别有限制(具体见官网),不满足远程创建条件的场景可按业务需要先本地创建。