文档开发者中心
我的
|

Live View Kit (实况窗服务)

LiveViewKit 进度可视化模板(LAYOUT_TYPE_PROGRESS)下,primary.content 设置多段 RichText 时 startLiveView 报 401「length exceeds the limit

30

【环境信息】

设备型号:【请填写,如 Mate 60 Pro】

HarmonyOS 版本:【请填写,如 HarmonyOS NEXT 5.x.x】

DevEco Studio / SDK 版本:【请填写】

涉及 Kit:Live View Kit(@kit.LiveViewKit),本地实况窗

【问题描述】 应用使用进度可视化模板(layoutData.layoutType = LAYOUT_TYPE_PROGRESS)展示车辆充电进度。需要在固定区 primary.content 展示一行带分色的富文本(标签用弱色、数值用高亮色),如「当前 90% | 预计 11:52 完成充电」。当 primary.content 设置为 5 段 RichText 时:

startLiveView 直接失败:code=401, message="Parameter error. The type of primary.content must be Array<RichText> [or the parameter length exceeds the limit]."

若实况窗已通过单段内容启动,再用 5 段内容调 updateLiveView,返回:{"resultCode":1,"message":"The primary data update failed"}

而当 primary.content 仅设置 1 段(如 [{text:"当前 90%"}])时,startLiveView 返回 resultCode:0 success,可正常显示与更新。

【关键请求体(5 段,失败)】

{"id":1,"event":"RENT","sequence":1,"timer":{"time":0,"isCountdown":false,"isPaused":false},

"liveViewData":{"primary":{"title":"充电中",

"content":[{"text":"当前 ","textColor":"#99FFFFFF"},{"text":"90%","textColor":"#FFFFFFFF"},{"text":" | 预计 ","textColor":"#99FFFFFF"},{"text":"11:52","textColor":"#FFFFFFFF"},{"text":" 完成充电","textColor":"#99FFFFFF"}],

"keepTime":0,"clickAction":{},

"layoutData":{"layoutType":3,"progress":90,"color":"#FF2CAF93","backgroundColor":"#FF4A4A4A","indicatorType":1,"indicatorIcon":"live_view_ic_charging.webp","nodeIcons":["live_view_ic_transparent.svg","live_view_ic_transparent.svg"],"lineType":2}},

"capsule":{"type":1,"status":1,"icon":"live_view_ic_logo.webp","backgroundColor":"#00000000","title":"充电中","content":"90%"}}}

对比:将 content 改为单段 [{"text":"当前 90%","textColor":"#FFFFFFFF"}] 时 startLiveView 成功。

【已排查】

单段 content → start/update 均成功;多段(5 段)→ start 401、update failed,唯一变量是 content 段数。

此前在非进度模板(如强调文本/左右文本模板)下,primary.content 设置多段 RichText 可正常显示,未报错。

官方文档进度可视化模板(配送场景)示例 content 也使用了多段(如「距商家 300 米 | 3 分钟到店」),与本现象矛盾,故怀疑是段数/单段长度/总字符数等存在未公开的限制。

【期望获取的帮助】

LAYOUT_TYPE_PROGRESS 进度模板下,primary.content 的 RichText 数组是否有段数上限或总字符长度上限?具体数值是多少?

该 401「length exceeds the limit」的确切触发条件是按段数、单段字符数、还是整体长度判定?

在进度模板下,若要实现「标签 + 高亮数值」的多段分色文本,官方推荐的正确写法是什么?应放 primary.content 还是 layoutData 的字段?

为何官方进度模板配送示例(多段)可用、而上述请求体不可用?两者差异点在哪?

点赞
1
收藏
1
回复
10
分享
举报
浏览258 发布于2026-06-26 05:53湖北
全部评论
最多点赞
最新发布
最早发布
|
推荐答复
该问题,我已经解决了,实况窗layout_type_progress
这块这个primary.content在设置richText文本格式的时候,对于分段是没有限制的,但是对于分段内的颜色是有限制,比如我当前分了五段,并且颜色都设置了一种,这种是可以的,但是五段内,颜色超过两种就会有问题
1
5楼回复于2026-06-26 07:31 来自湖北
在构建本地实况窗时,针对 layoutType: liveViewManager.LayoutType.LAYOUT_TYPE_PROGRESS 场景,需明确设置以下参数:当前进度百分比、前景与背景色值、以及指示器的显示方向与图标资源,以实现符合设计规范的外卖配送或出行进度可视化效果。
6楼回复于2026-06-26 07:52 来自广东

这个报错更像是进度可视化模板对 `primary.content` 有额外长度/段数限制,而不是 RichText 类型本身写错。接口类型允许 `Array<RichText>`,但具体模板在 start/update 时仍可能限制段数、总字符数或字段组合。

建议把固定区文案压缩成 1 到 2 段 RichText,颜色差异尽量只保留关键数值;更多状态信息放到 secondary 或业务页面里展示。也可以先用单段、两段、三段逐步递增验证上限,确认是段数超限还是总长度超限,再按模板约束做降级。

8楼回复于2026-06-29 01:21 来自四川

看你这个问题,应该不是 RichText 类型写错了,更像是 LiveViewKit 的 LAYOUT_TYPE_PROGRESS 模板对 primary.content 有额外限制。

很多人这里容易踩坑:接口定义里写的是:

收起
自动换行
深色代码主题
复制
primary.content: Array<RichText>

但是实际调用 LiveViewManager.startLiveView() 时,系统还会根据具体模板做二次校验,并不是所有模板都能无限塞 RichText。

你现在这个请求:

收起
自动换行
深色代码主题
复制
content:[
 {"text":"当前 ","textColor":"#99FFFFFF"},
 {"text":"90%","textColor":"#FFFFFFFF"},
 {"text":" | 预计 ","textColor":"#99FFFFFF"},
 {"text":"11:52","textColor":"#FFFFFFFF"},
 {"text":" 完成充电","textColor":"#99FFFFFF"}
]

拆成了 5 个 RichText 节点。

错误:

收起
自动换行
深色代码主题
复制
code=401
Parameter error.
The type of primary.content must be Array<RichText>
or the parameter length exceeds the limit

重点看后半句:

收起
自动换行
深色代码主题
复制
length exceeds the limit

说明类型已经认可了,失败点大概率是:

  • RichText 数组长度
  • 单个 text 长度
  • 整体序列化长度

而不是字段类型问题。

另外 progress 模板和普通文本模板不一样。

LAYOUT_TYPE_PROGRESS 本身已经有:

收起
自动换行
深色代码主题
复制
layoutData:{
    progress:90
}

这个字段负责:

  • 进度比例
  • 进度条展示
  • 指示器状态

按照 Live View Kit 的设计思路,primary.content 更多是辅助描述,例如:

收起
自动换行
深色代码主题
复制
当前充电中
预计11:52完成

不要把它当普通 ArkUI Text 那样拆很多段。

建议先改成这种:

收起
自动换行
深色代码主题
复制
"content":[
 {
   "text":"当前 90% | 预计 11:52 完成充电",
   "textColor":"#FFFFFFFF"
 }
]

测试一下。

如果单段成功,基本就能确定是 RichText 节点数量限制。

如果想保留颜色,可以减少节点:

例如:

收起
自动换行
深色代码主题
复制
[
 {
  "text":"当前 ",
  "textColor":"#99FFFFFF"
 },
 {
  "text":"90% | 预计11:52完成充电",
  "textColor":"#FFFFFFFF"
 }
]

不要拆:

收起
自动换行
深色代码主题
复制
当前
90%
|
预计
11:52
完成

这种粒度。

系统级实况窗不是普通页面渲染,节点越多,解析和布局成本越高。

为什么官方配送示例可以多段?

这个地方容易误会。

文档里的示例:

收起
自动换行
深色代码主题
复制
距商家300米 | 3分钟到店

虽然看起来是多段,但是实际:

  • 文本短
  • 节点少
  • 信息密度低

不是代表所有模板都支持任意数量 RichText。

Progress 模板还有自己的布局约束。

你这里:

收起
自动换行
深色代码主题
复制
startLiveView 失败
updateLiveView 失败

说明不是 updateLiveView 生命周期问题。

如果是更新问题,一般看:

  • sequence 是否连续
  • id 是否一致
  • 状态是否允许更新

但你启动阶段已经 401,优先看参数。

建议排查顺序:

收起
自动换行
深色代码主题
复制
5段RichText
→ 3段RichText
→ 2段RichText
→ 1段RichText

看哪个节点数量开始失败。

实际项目里这种充电进度场景建议:

收起
自动换行
深色代码主题
复制
layoutData.progress = 90
→ 负责进度展示

primary.content
→ 简单描述状态

不要让 primary.content 同时承担:

  • 状态
  • 百分比
  • 时间
  • 多颜色强调

这样稳定性会高很多。这个问题大概率是 LAYOUT_TYPE_PROGRESS 模板侧隐藏限制,不是 ArkTS 或 RichText 用法错误。

展开全部
7楼回复于2026-06-27 01:14 来自辽宁
嗯 ,支持一下。。。
4楼回复于2026-06-26 06:26 来自山东

从接口声明看,`primary.content` 的类型就是 `Array<RichText>`,`RichText` 只要求 `text`,`textColor` 可选且颜色使用 `#ARGB` 格式;`LAYOUT_TYPE_PROGRESS` 的 `layoutData` 只承载进度条相关字段,例如 `progress`、`color`、`backgroundColor`、`indicatorType`、`indicatorIcon`、`lineType`、`nodeIcons`。所以分色文字仍应放在 `primary.content`,不是放到 `layoutData` 里。

你这个 case 单段能启动、5 段启动时报 401,基本可以判断不是字段类型写错,而是进度模板运行时对 `primary.content` 做了额外校验。公开声明里没有给出段数/总字符数的明确上限,所以不建议按固定数值写死;建议先把 RichText 段数和总展示文本压到最小。

可以先把相邻同色文本合并,进度模板里优先保留一个关键高亮值,例如:

```

content: [

  { text: '当前 ', textColor: '#99FFFFFF' },

  { text: '90%', textColor: '#FFFFFFFF' },

  { text: ' | 预计 11:52 完成充电', textColor: '#99FFFFFF' }

]

```

如果必须同时高亮 `90%` 和 `11:52`,可以再试 4 段并进一步缩短文案;如果 4 段仍失败,就说明当前进度模板/设备侧服务对该区域的分段富文本支持更窄,建议退化为单段主文案,把次要信息放到 `title`、`capsule.content` 或扩展区。`layoutData` 继续只放进度条参数即可。

另外,示例里的 `clickAction: {}` 也建议处理一下:声明中它是 WantAgent,不需要点击行为时可以先去掉,或传真实 WantAgent。虽然你单段时能成功,说明它不是这次多段失败的主因,但避免空对象参与校验更稳。

如果官方配送示例多段可用,建议对比三点:段数是否更少、总文本是否更短、运行设备/LiveViewKit 版本是否一致。若同版本下 3 段可用、4/5 段失败,可以把最小复现和失败阈值反馈给官方,这更像模板运行时限制或文档示例与实现不一致。

展开全部
3楼回复于2026-06-26 06:08 未知归属地

基础模板

适用于不需要扩展区的内容较少、简易操作场景

  1. 当不填充扩展区内容时,仅显示1*4的卡片大小。图标、文本、辅助区规则与2*4一致。
  2. 使用1*4时,请注意在辅助区提供必要的功能操作和引导。

cke_2599.png

进度可视化模板

适用于打车、外卖等需要呈现完整进程及当前节点的场景

  1. 图标:支持表示来源的应用/服务图标
  2. 文本:支持双行主副文本,显示当前节点阶段和详细信息,其中副文本可选关键词采用强调色,支持一种强调色,且需要与胶囊底色等其他自定义颜色一致;
  3. 辅助区:支持添加辅助信息,如商品/商家图片等,挤占文本区域
  4. 扩展区:支持进度和节点的可视化显示,节点数支持 2-5 个,进度条支持 3 个样式可选,并组合不同的图片展示样式。进度条可定义高亮色,建议与文本强调色、胶囊底色等保持一致。

cke_4534.png 

进度样式说明

1. 应用可自定义活动进程节点个数 (最多 5 个)、节点 icon 和进度条搭配样式,进度条指示器 (pic 区域) 可在限定区域内展示派送员、车、派送物品等直观视觉样式。

2. 考虑卡片底板具有一定透明度及模糊材质,卡片内容会受到底部页面影响。应用设计时推荐使用圆形底板以增加对比度,节点底板颜色建议自定义高亮色。如未上传高亮色,已完成进度默认系统高亮蓝色 #317AF7,未完成进度显示系统黑白样式 (10% 黑/白)。若不需要圆形底板,也可选择设计有足够显色度、识别度的图标,展示在规定的图标区域内。已完成进度条和已完成进度节点背景色一致,未完成进度条和未完成进度节点背景色一致。

  • 请注意使用系统圆形底板需上传 svg 格式图标;若自定义底板,需上传 png 格式。不推荐无底板的样式,会造成进度条连接处显示异常。

3. 使用样式二时,支持在固定区域内展示骑手等插画图形短暂覆盖进度条节点位置,但不可直接显示进度条头尾无节点。

  • pic 可等比缩放,pic 区仅有最大高度限制,宽度根据需求自定义。不推荐扁而长的插画资源,会导致进度移动缓慢、比例失衡等问题。

样式一:采用圆点进度,已完成的进度条及节点底板推荐使用应用色

样式二:采用条状进度,已完成的进度条推荐使用应用色

样式三:采用较粗条状进度,已完成的进度条推荐使用应用色,也可搭配无 pic 场景突出进度条样式

图片类型:

1、气泡遮罩类:系统提供固定大小气泡,应用可替换裁切的为居中正圆区域,实际大小32*32vp。

2、自定义覆盖类:系统限制长宽区域,最大高度56vp,应用根据设计所需诉求提供对应资源。、

cke_5451.png

展开全部
2楼编辑于2026-06-26 06:11 来自北京
棒棒哒
1楼回复于2026-06-26 05:54 来自四川
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。