仪表
仪表用环形进度展示一个数值在范围中的位置。适合做电量、完成率、健康分、预算占用等展示。
用法
在编辑器底部点加号,添加 仪表,然后设置:
| 字段 | 常用填写 |
|---|---|
| 当前值 | 0.72 / ${progress} |
| 最小值 | 0 |
| 最大值 | 1 / 100 |
| 颜色 | 在颜色编辑器里选单色、线性或分段 |
仪表的中心内容和说明文字通过子组件表达,但只识别 层叠 子组件:
仪表
├─ 层叠 ← 中心内容
│ └─ 文本,「内容」填 72%
└─ 层叠 ← 说明文字
└─ 文本,「内容」填 今日
如果只有 1 个可见层叠,它只作为中心内容,不会重复作为说明文字。
属性
| 字段 | 可填写 | 说明 |
|---|---|---|
| 当前值 | 0.6 / ${value} | 当前进度值 |
| 最小值 | 0 | 进度范围下限 |
| 最大值 | 1 / 100 | 进度范围上限 |
| 起始角度 | 210 | 仪表环开始角度 |
| 终止角度 | 150 | 仪表环结束角度 |
| 环宽 | 12 / 12vp | 仪表环宽度;不支持百分比 |
| 颜色 | 颜色编辑器 | 支持单色、线性、分段,也支持整段变量绑定 |
| 宽 / 高 | auto / 100 / ${size} | 仪表尺寸 |
| 水平偏移 / 垂直偏移 / Z 轴偏移 | 0 / 8 / ${x} | 只移动显示位置,不改变原本占位 |
| 内边距 / 外边距 | 8 / 8,8,8,8 | 四周留白 |
| 显示 | true / false / ${show} | 控制是否显示 |
| 背景色 | #FFFFFF / ${color} | 仪表背景 |
| 圆角 | 0 / 8 / 50% | 背景圆角 |
| 旋转角度 | 0 / 15 / ${angle} | 顺时针旋转角度 |
| 不透明度 | 0 到 1 | 1 为完全不透明 |
颜色
「颜色」不是普通文本字段。编辑器会打开专用颜色面板:
- 单色:一整条仪表环用同一个颜色。
- 线性:用多个色标做渐变,每个色标有颜色和偏移。
- 分段:最多 9 段,每段有颜色和权重;权重非法时按
0处理。
动态颜色时,在颜色面板的“变量绑定”里填 ${colors},JS 顶层变量返回对象:
let colors = {
kind: "segments",
segments: [
{ color: "#34C759", weight: 30 },
{ color: "#FF9500", weight: 40 },
{ color: "#FF3B30", weight: 30 },
],
}
线性渐变:
let colors = {
kind: "linear",
stops: [
{ color: "#0A59F7", offset: 0 },
{ color: "#34C759", offset: 1 },
],
}
单色:
let colors = {
kind: "single",
color: "#0A59F7",
}
子组件规则
仪表只把可见层叠当作槽位:
| 子组件情况 | 显示结果 |
|---|---|
| 没有层叠 | 只显示仪表环 |
| 1 个层叠 | 第 1 个层叠显示到中心 |
| 2 个及以上层叠 | 第 1 个层叠显示到中心,最后 1 个层叠显示为说明文字 |
| 直接放文本、图片、图标 | 不会作为仪表槽位显示 |
如果要显示中心百分比、标题、单位,把它们放进第一个层叠。如果要显示说明文字,放进最后一个层叠。
例:动态完成率
JS:
let done = 72
let progress = done / 100
仪表:
| 字段 | 填写 |
|---|---|
| 当前值 | ${progress} |
| 最小值 | 0 |
| 最大值 | 1 |
| 起始角度 | 210 |
| 终止角度 | 150 |
中心层叠里放文本:
| 组件 | 字段 | 填写 |
|---|---|---|
| 文本 | 内容 | ${done}% |
| 文本 | 字号 | 18 |
注意事项
说明文字需要 API 23+
说明文字只在 HarmonyOS API 23+ 显示。低于 API 23 时,说明文字不显示,卡片不会因此崩溃。
文本不是最小值 / 最大值槽位
仪表的「最小值」和「最大值」是数值范围,不是两个独立文字位置。需要文字就放进中心层叠或说明文字层叠。
分段颜色最多 9 段
超过 9 段会截断。空颜色不会传给系统,避免显示异常。