文章目录
- 组件概述
- 核心 API 与参数
- 1. 组件构造参数
- 2. 关键枚举
- 3. 基础样式属性
- 示例代码功能说明
- 代码逐段解析
- 1. 数据定义
- 2. 布局容器
- 3. 单段环形数据面板（核心）
- 4. 多段环形数据面板
- 5. 线性数据面板
- 运行效果
- 总结
组件概述
DataPanel（数据面板组件）是 HarmonyOS 6 提供的可视化数据展示组件，支持环形（Circle）和线性（Line）两种展示类型，可灵活呈现单段/多段数据占比、进度等信息，广泛应用于系统状态展示、存储使用率、版本进度等场景。
核心 API 与参数
1. 组件构造参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
values | number[] | 是 | 数据数组： - 单段数据：数组长度为1（如 [30]），表示单一占比；- 多段数据：数组长度>1（如 [50,12,8,5]），表示多维度占比总和 |
max | number | 是 | 数据最大值（通常设为100表示百分比，也可自定义业务最大值） |
type | DataPanelType | 是 | 展示类型： - DataPanelType.Circle：环形展示；- DataPanelType.Line：线性展示（注：官方文档中Linear与Line为同一类型，API 中可互通） |
2. 关键枚举
| 枚举值 | 说明 | 适用场景 |
|---|---|---|
DataPanelType.Circle | 环形数据面板 | 占比类数据（如使用率、完成率） |
DataPanelType.Line | 线性数据面板 | 多段趋势/分段进度（如多节点完成状态） |
3. 基础样式属性
| 属性名 | 类型 | 说明 |
|---|---|---|
width/height | number | 组件宽高：环形建议设为正方形（如168x168），线性建议宽远大于高（如300x20） |
position | {x: number, y: number} | 绝对定位：用于调整辅助文本（如%）的位置 |
示例代码功能说明
示例实现三类 DataPanel 展示效果：
- 单段环形数据面板：展示30%的占比数据，叠加版本号文本；
- 多段环形数据面板：展示多维度数据总和占比（50+12+8+5=75%），叠加存储使用率文本；
- 线性数据面板：展示9段均分数据（每段10%）的线性进度条。
代码逐段解析
1. 数据定义
public valueArr: number[] = [10, 10, 10, 10, 10, 10, 10, 10, 10]- 定义线性数据面板的数据源，9个10%的分段数据，总和90%（未占满100%，剩余10%为空白）；
- 使用
public修饰，保证组件内可直接调用。
2. 布局容器
build() { Column({ space: 5 }) { // 环形数据面板行容器 Row() { ... }.margin({ bottom: 59 }) // 线性数据面板 DataPanel(...) }.width('100%').margin({ top: 5 }) }- 整体采用
Column纵向布局，环形面板与线性面板间距5vp； Row容器承载两个环形面板，横向排列，右侧间距44vp。
3. 单段环形数据面板（核心）
Stack() { // 单段环形数据面板 DataPanel({ values: [30], max: 100, type: DataPanelType.Circle }).width(168).height(168) Column() { Text('30').fontSize(35).fontColor('#182431') Text('1.0.0').fontSize(9.33).lineHeight(12.83).fontWeight(500).opacity(0.6) } Text('%') .fontSize(9.33) .lineHeight(12.83) .fontWeight(500) .opacity(0.6) .position({ x: 104.42, y: 78.17 }) }.margin({ right: 44 })关键说明：
Stack堆叠容器：实现“环形面板 + 中心文本 + 百分比符号”的叠加效果；DataPanel配置：values: [30]表示30%占比，max: 100为百分比基数，Circle类型渲染环形；- 中心文本：展示核心数值“30”和版本号“1.0.0”，通过字体大小/透明度区分主次；
- 绝对定位：
%符号通过position精准定位到环形右侧，提升视觉完整性。
4. 多段环形数据面板
Stack() { DataPanel({ values: [50, 12, 8, 5], max: 100, type: DataPanelType.Circle }).width(168).height(168) Column() { Text('75').fontSize(35).fontColor('#182431') Text('已使用98GB/128GB').fontSize(8.17).lineHeight(11.08).fontWeight(500).opacity(0.6) } Text('%') .fontSize(9.33) .lineHeight(12.83) .fontWeight(500) .opacity(0.6) .position({ x: 104.42, y: 78.17 }) }关键说明：
values: [50,12,8,5]：4段数据总和75，对应中心文本“75%”；- 环形自动按数据占比分割为4个颜色段（使用系统默认配色）；
- 中心文本替换为存储使用率描述（已使用98GB/128GB），贴合实际业务场景。
5. 线性数据面板
DataPanel({ values: this.valueArr, max: 100, type: DataPanelType.Line }).width(300).height(20)关键说明：
type: DataPanelType.Line：渲染线性进度条，宽300vp、高20vp符合线性展示视觉习惯；values: this.valueArr：9段10%的数据，线性面板会分割为9个等宽的颜色段；- 无叠加文本：纯线性展示，适用于多节点状态、分段进度等场景。
运行效果
| 组件类型 | 展示效果 |
|---|---|
| 单段环形 | 168x168 环形面板，30%区域填充系统默认色，中心显示“30”+“1.0.0”，右侧显示“%”； |
| 多段环形 | 168x168 环形面板，按50/12/8/5的占比分割为4个颜色段，中心显示“75”+“已使用98GB/128GB”，右侧显示“%”； |
| 线性面板 | 300x20 线性进度条，均分9个10%的颜色段，总占比90%，剩余10%为空白； |
运行效果如图：
总结
环形面板布局
- 建议使用
Stack堆叠容器叠加文本，实现“数据面板+核心数值”的复合展示； - 环形宽高需设为相同值（正方形），否则会拉伸变形。
- 建议使用
数据逻辑
values数组总和可小于/等于max：小于时剩余部分为空白，等于时填满整个面板；- 多段环形的颜色由系统自动分配，如需自定义可通过
colors属性扩展（示例未使用）。
文本定位
- 辅助文本（如%）建议使用
position绝对定位，需根据环形尺寸微调x/y值，保证视觉对齐； - 中心文本建议通过
Column居中，字体大小建议为环形宽度的1/5~1/4（如168宽度对应35字号）。
- 辅助文本（如%）建议使用
兼容性说明
- 支持设备：Phone/平板/PC/智慧屏（API 7+）；
- 类型兼容：
DataPanelType.Linear与DataPanelType.Line为同一类型，可互换使用； - 样式扩展：示例未使用
strokeWidth（环形宽度/线性高度）、colors（自定义颜色）等属性，可参考官方文档扩展。
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力
