当用户打开手机存储管理时，一个多彩的环形图表直观地展示了各类文件占用了多少空间——照片、视频、应用、音乐……每一段彩色圆弧代表一个类别，占比越大弧越长。这就是数据面板的典型应用场景：用视觉化的方式呈现比例关系，让数据一目了然。

HarmonyOS NEXT ArkUI 提供了 DataPanel 组件——一个用于展示多类别比例数据的环形数据面板。本文将深入讲解 DataPanel 的 API 和使用技巧，并构建一个"设备存储空间分析器"——支持多设备切换、分类明细查看、高占用预警和一键清理。

关键词：HarmonyOS、ArkUI、DataPanel、数据面板、存储分析、环形图表、比例可视化

一、DataPanel 组件 API

1.1 基本用法

DataPanel({
  values: [28, 35, 22, 8, 5, 12, 18],
  max: 128
})
  .width(220)
  .height(220)

核心参数与属性：

参数/属性 类型 说明
values number[] 各类别的数值数组，每个值对应一段圆弧
max number 最大值，所有 values 之和不应超过 max
.width() / .height() Length DataPanel 的尺寸（推荐宽高相等）

DataPanel 自动为每段圆弧分配不同颜色——从暖色（红/橙）到冷色（蓝/紫）再到中性色（灰），按 values 数组的顺序依次渲染。开发者不需要手动指定每段的颜色，组件内置了协调的配色方案。

1.2 values 与 max 的关系

DataPanel 是一个环形图，总弧长对应 max 值。每个 values[i] 占据弧长比例为 values[i] / max。未占满的部分（max - sum(values)）自动留白，表示剩余空间。

Demo 中将设备总容量作为 max，各类别实际使用量作为 values：

// 内部存储 128GB，各类别使用量
DataPanel({
  values: [28, 35, 22, 8, 5, 12],  // 各类别 GB 数
  max: 128                            // 总容量 128GB
})

已用 110GB 显示为彩色圆弧，剩余 18GB 显示为空白区域——用户一眼就能看到空间占用和剩余情况。

注意：values 中各元素的值不应超过 max。如果某个值超过 max，该段圆弧会占满整个环形，其他数据无法正确显示。Demo 中通过 getValues() 方法确保每个设备的所有类别之和不超过总容量。

1.3 DataPanel 不提供的功能

DataPanel 是一个纯粹的比例可视化组件——它只负责画圆弧。以下功能需要开发者自己实现：

  • 颜色图例：DataPanel 自动配色，但不提供颜色查询 API。Demo 中在 StorageCategory 类中自行定义了 dotColor 字段，用 ● 字符模拟颜色指示点。
  • 标签/数值标注：圆弧上没有文字。所有标签和数值通过额外的 Text 组件在 DataPanel 外部显示。
  • 交互/点击：DataPanel 不支持点击某段圆弧高亮或弹出详情。所有交互通过页面其他元素（设备切换标签、清理按钮）实现。
  • 动画：DataPanel 不提供入场动画或数据变化时的过渡动画。

理解这些限制有助于合理规划页面布局——DataPanel 作为视觉核心占据中央位置，周边的标签、列表、按钮共同构成完整的信息展示。

二、存储空间分析器的整体设计

2.1 页面架构

DataPanelPage
├── 标题栏 — "存储空间分析" + 已用百分比
├── 设备切换标签（内部存储 / SD 存储卡）
├── DataPanel 环形图卡片
│   ├── DataPanel 组件（220×220）
│   ├── 已用 GB / 共 GB 文字
│   └── 可用 GB 文字
├── 高占用预警横幅（使用率 ≥ 80% 时显示）
│   ├── 警告文字
│   └── "一键清理"按钮
├── 存储明细列表
│   ├── 每个类别的色点 + 名称 + GB + 百分比
│   └── 可用空间行（绿色）
└── 存储建议卡片

2.2 数据类设计

Demo 中定义了两个类：

class StorageCategory {
  name: string;     // 类别名称
  size: number;     // 占用大小（GB）
  dotColor: string; // 图例色点颜色

  constructor(name: string, size: number, dotColor: string) {
    this.name = name;
    this.size = size;
    this.dotColor = dotColor;
  }
}

class DeviceProfile {
  name: string;                  // 设备名称
  total: number;                 // 总容量（GB）
  categories: StorageCategory[]; // 各类别数据

  getUsed(): number { /* 遍历累加 size */ }
  getFree(): number { return this.total - this.getUsed(); }
  getUsagePercent(): number { /* 已用百分比 */ }
  getValues(): number[] { /* 提取各类别 size + 可用空间 */ }
}

StorageCategory 封装单个存储类别。dotColor 用于存储明细列表中类别名称前的色点——因为 DataPanel 不提供颜色查询 API，开发者需要在数据层自行维护颜色映射。

DeviceProfile 封装一个完整的设备存储快照。getValues() 方法将各类别的 size 提取为 number[]，并追加可用空间，构成 DataPanel 的 values 参数：

getValues(): number[] {
  let vals: number[] = [];
  for (let i = 0; i < this.categories.length; i++) {
    vals = vals.slice().concat(this.categories[i].size);
  }
  let free = this.getFree();
  if (free > 0) {
    vals = vals.slice().concat(free);
  }
  return vals;
}

这里将可用空间也加入 values——DataPanel 会自动为它分配一个颜色，使得环形图中包含一块代表"可用空间"的圆弧。用户不需要在心理上将空白区域换算为剩余空间。

2.3 双设备数据

Demo 模拟了两个设备存储快照：

内部存储（128GB）：

类别 大小 占比 色点颜色
照片与截图 28GB 22% #FF6B6B（红）
视频文件 35GB 27% #FF9F43（橙）
应用与游戏 22GB 17% #1677FF（蓝）
音乐与音频 8GB 6% #A29BFE（紫）
文档资料 5GB 4% #00B894（绿）
缓存与其他 12GB 9% #636E72（灰）
可用空间 18GB 14% #52C41A（绿）

已用 110GB（86%），空闲 18GB（14%）。

SD 存储卡（64GB）：

类别 大小 占比 色点颜色
照片备份 15GB 23% #FF6B6B
视频录制 20GB 31% #FF9F43
音乐收藏 8GB 13% #A29BFE
文档备份 3GB 5% #00B894
其他文件 5GB 8% #636E72
可用空间 13GB 20% #52C41A

已用 51GB（80%），空闲 13GB（20%）。

两个设备的数据差异让设备切换功能有了实际意义——用户可以看到不同设备的存储状况。
在这里插入图片描述

三、设备切换

3.1 切换标签

两个设备标签使用 ForEach 渲染，选中的标签为蓝底白字加粗，未选中的为灰底灰字：

ForEach(this.getDevices(), (device: DeviceProfile, idx: number) => {
  Text(device.name)
    .fontSize(13)
    .fontColor(idx === this.deviceIndex ? '#FFFFFF' : '#666677')
    .fontWeight(idx === this.deviceIndex ? FontWeight.Bold : FontWeight.Normal)
    .padding({ top: 8, bottom: 8, left: 16, right: 16 })
    .borderRadius(18)
    .backgroundColor(idx === this.deviceIndex ? '#1677FF' : '#F2F3F5')
    .onClick(() => { this.deviceIndex = idx; })
}, ...)

3.2 联动更新

@State deviceIndex 驱动所有相关区域更新：

  1. DataPanel — values 通过 this.getCurrentDevice().getValues() 获取，设备切换后自动变化
  2. 标题栏百分比 — 重新计算已用比例
  3. 用量文字 — "已用 X GB / 共 Y GB"自动更新
  4. 存储明细列表 — 按新设备的类别重新渲染
  5. 高占用预警 — 根据新设备的使用率决定是否显示

所有这些更新都通过 @State 响应式机制自动完成，不需要手动刷新任何区域。
在这里插入图片描述

四、高占用预警

4.1 条件显示

当设备使用率达到 80% 或以上时，在 DataPanel 图表下方显示预警横幅：

if (this.getCurrentDevice().getUsagePercent() >= 80) {
  Row() {
    Text('存储空间不足，建议清理不常用的文件和应用')
      .fontSize(13).fontColor('#FF4D4F').layoutWeight(1)
    Text('一键清理')
      .fontSize(12).fontColor('#FFFFFF').fontWeight(FontWeight.Medium)
      .padding({ top: 6, bottom: 6, left: 14, right: 14 })
      .borderRadius(14).backgroundColor('#FF4D4F')
      .onClick(() => {
        promptAction.showToast({ message: '已清理缓存文件', duration: 1500 });
      })
  }
  .width('100%')
  .padding({ top: 12, bottom: 12, left: Spacing.LG, right: Spacing.LG })
  .backgroundColor('#FFF1F0')
  .borderRadius(BorderRadius.LG)
  ...
}

内部存储（86% 已用）满足条件，预警横幅显示。SD 卡（80% 已用）也满足（>= 80），同样显示预警。

预警横幅使用浅红色背景（#FFF1F0）+ 红色文字，在白色卡片群中非常显眼。"一键清理"按钮调用 promptAction.showToast() 模拟清理操作——在实际应用中这里可以触发真实的缓存清理逻辑。

五、存储明细列表

5.1 类别行

每个类别一行，包含色点指示器（● 字符）、类别名称、占用大小和百分比：

ForEach(this.getCurrentDevice().categories, (cat: StorageCategory, idx: number) => {
  Row() {
    Row() {
      Text('●')  // 色点指示器
        .fontSize(12)
        .fontColor(cat.dotColor)
        .margin({ right: 8 })
      Text(cat.name)
        .fontSize(14).fontColor('#1a1a2e')
    }
    .layoutWeight(1)

    Column() {
      Text(cat.size.toString().concat(' GB'))
        .fontSize(14).fontColor('#1a1a2e').fontWeight(FontWeight.Medium)
      Text(Math.round((cat.size / this.getCurrentDevice().total) * 100)
        .toString().concat('%'))
        .fontSize(11).fontColor('#CCCCDD')
    }
    .alignItems(HorizontalAlign.End)
  }
  .width('100%').padding({ top: 10, bottom: 10 })
  ...
})

右侧数值使用两行排列——GB 数在上（14sp，深色加粗），百分比在下（11sp，浅灰）。这种设计让用户同时看到绝对值和相对比例。

5.2 可用空间行

列表最后使用绿色色点显示可用空间：

Text('●')
  .fontSize(12)
  .fontColor('#52C41A')
  .margin({ right: 8 })

绿色色点（#52C41A）与上面各类别的彩色色点形成对比，传达"剩余空间充裕"的正面信息。当可用空间很少时（内部存储仅 18GB），绿色"可用空间"标签给人以希望——还有空间可以管理。

六、DataPanel vs Progress vs Gauge

这三个组件都与"进度/比例"相关，但适用场景不同：

维度 DataPanel Progress Gauge
数据维度 多类别（5-10 段） 单一进度（0-100%） 单一指标（如速度、温度）
视觉形态 环形多色分段 水平条/环形单色 仪表盘指针
典型场景 存储分析、预算分配、成分构成 下载进度、任务完成度 速度表、CPU 温度
交互能力 无（纯展示） 无（纯展示） 无（纯展示）
颜色控制 自动配色（不可自定义） 可自定义颜色 可自定义颜色

选择建议：

  • 展示"多个部分如何组成整体"→ 用 DataPanel
  • 展示"一个任务完成到什么程度"→ 用 Progress
  • 展示"一个指标在某个范围内的位置"→ 用 Gauge

七、交互流程演示

7.1 默认状态

进入页面，默认显示"内部存储"的存储分析。DataPanel 环形图显示 7 段彩色圆弧（6 个类别 + 1 段可用空间）。标题栏显示"86% 已用"。由于 86% ≥ 80%，预警横幅显示。

环形图下方用量文字显示"已用 110GB / 共 128GB"和"18GB 可用"。

7.2 查看明细

在存储明细列表中，可以看到每个类别的详细信息。视频文件最大（35GB，27%），照片其次（28GB，22%）。可用空间仅 18GB（14%），排在最后。

7.3 切换设备

点击"SD 存储卡"标签。DataPanel 环形图更新为 SD 卡的数据——圆弧段数变为 6 段（5 个类别 + 可用空间）。标题栏变为"80% 已用"。预警横幅仍然显示（因为 80% ≥ 80%）。

用量文字变为"已用 51GB / 共 64GB"和"13GB 可用"。

7.4 一键清理

点击内部存储预警横幅中的"一键清理"按钮。Toast 提示"已清理缓存文件"。在实际应用中，这里会触发缓存文件扫描和清理逻辑。

7.5 查看建议

页面底部显示存储建议卡片，提供三个实用建议：定期清理缓存、云端备份照片视频、卸载不常用应用。

八、总结

本文通过"设备存储空间分析器"这个实战案例，全面讲解了 ArkUI DataPanel 数据面板组件的使用方法。核心知识点包括：

  1. DataPanel 基础 API：values + max 比例映射 + 自动配色机制
  2. 多类别数据建模：StorageCategory 类封装名称/大小/色点 + DeviceProfile 类封装设备快照
  3. 动态值计算：getValues() 提取各类别 size + 追加可用空间构成 values 数组
  4. 多设备切换：@State deviceIndex 驱动 DataPanel/用量文字/明细列表联动更新
  5. 高占用预警：getUsagePercent() >= 80 条件渲染预警横幅 + 一键清理交互
  6. 色点图例：因 DataPanel 不提供颜色查询 API，在数据类中自行维护 dotColor 字段
  7. DataPanel vs Progress vs Gauge：三个比例组件的适用场景对比

DataPanel 是"比例构成"场景的最佳可视化方案。它比表格更直观（圆弧比例一目了然），比文字描述更简洁（一张图代替一段话）。虽然它不提供颜色查询、点击交互和动画效果，但通过合理的数据建模和周边 UI 元素的配合，可以构建出专业而实用的数据概览页面。

# harmonyos # 华为 # 交互 # 安全 # microsoft
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

【无标题】

avatar 人工智能6S服务平台

拆解二维码名片生成器：原生鸿蒙页面的实现路径与调试方法

这张二维码名片页面的核心体验可以概括为：一个名片标题、一块二维码样式预览、一项可编辑姓名、三条固定身份信息、一个保存按钮和一条会随点击变化的反馈文案。它通过简单的纵向布局把内容和操作组织在一张屏幕中，用户可以先查看示例，再修改姓名，最后点击保存并看到完成提示。它的价值不在于功能数量多，而在于每个交互都容易观察。输入框展示了文本状态如何变化，按钮展示了操作如何改变完成状态，条件提示展示了同一位置如何

avatar 人工智能6S服务平台
cover

2026企业BI工具怎么选？六大维度一次讲透

avatar 人工智能6S服务平台