HarmonyCharts 快速上手（HarmonyOS / ArkTS）

一句话说明（What）

HarmonyCharts 是面向 HarmonyOS / ArkTS 的高性能图表库，用于在鸿蒙应用中快速构建可交互的数据可视化。

适用场景（When）

适用：

• 鸿蒙应用内的报表与趋势分析
• 多端（手机/平板/车机）的统一图表体验
• 需要轴、图例、联动等交互能力的场景

不适合：

• 仅需静态图片展示且无交互需求

通过鸿蒙第三方中心仓库安装（OHPM）

推荐通过 OHPM 依赖管理直接安装 HarmonyCharts。

方式一：命令行安装

ohpm install @ymhc/harmonycharts

方式二：手动添加依赖

在 oh-package.json5 中添加：

dependencies: {
  "@ymhc/harmonycharts": "1.0.1"
}

安装完成后在 ArkTS 中直接引入：

import { BaseLine } from '@ymhc/harmonycharts';

完整页面示例（ArkTS 可直接运行）

import { BaseLine } from '@ymhc/harmonycharts';
import type { BaseLineConfig } from '@ymhc/harmonycharts';

@Entry
struct Index {
  @Prop baseLineConfig: BaseLineConfig = {
    categories: ['Mon', 'Tue', 'Wed', 'Thu'],
    series: [{ name: 'Trend', data: [120, 200, 150, 80] }],
    tooltip: { show: true, trigger: 'axis', confine: true },
    legend: { show: true }
  };

  build() {
    Column() {
      BaseLine({ config: this.baseLineConfig, chartHeight: 220 })
    }
  }
}

基础用法（How - Basic）

增加 tooltip

tooltip: { show: true, trigger: 'axis' }

添加 legend

legend: { show: true }

设置 grid

grid: { top: 24, left: 16, right: 16, bottom: 28 }

配置项说明（API）

HarmonyChartsOption 常用项

参数	说明	类型	默认值
xAxis	X 轴配置	XAxisOption	未设置
yAxis	Y 轴配置	YAxisOption	未设置
series	图表系列	SeriesOption[]	[]
tooltip	提示框	TooltipOption	未设置
legend	图例	LegendOption	未设置
grid	网格	GridOption	未设置
dataZoom	缩放	DataZoomOption	未设置

事件与交互（Events）

点击事件

chart.on('click', (params) => {
  // 处理点击
});

轴指示器

使用 axisPointer 与 tooltip.trigger: 'axis' 组合。

高级用法（Advanced）

• 多 grid 多轴联动
• dataZoom inside/slider 同步
• emphasis / blur / select 状态链路

注意事项 / 设计说明（Notes）

• HarmonyCharts 不支持 any / unknown，配置项需显式类型。
• 渲染阶段避免频繁创建对象，建议复用 option。

核心问题（Q&A）

Q: 最小可运行配置长什么样？
A: 只要提供 xAxis / yAxis / series 即可渲染，详见「快速上手」示例。

Q: 新手最容易踩的坑是什么？
A: 主要是类型不显式（ArkTS 禁止 any/unknown）和频繁创建新对象导致性能抖动。

Q: 想要交互最先开哪几个？
A: 优先开启 tooltip 与 legend，再按需加 dataZoom 和 axisPointer。