---
name: mccharts
description: 为 HarmonyOS / ArkTS 项目接入、配置、调试或迁移莓创图表 mccharts（@mcui/mccharts），处理图表更新、事件、手势、联动与原生 PNG 导出。用于用户明确使用 mccharts 的任务；普通 Web ECharts 或其他图表库不适用。
license: Apache-2.0
metadata:
  version: "1.0.0"
  library-version: "3.0.0"
---

# 莓创图表 mccharts

帮助使用 `@mcui/mccharts` 3.0.0 编写 HarmonyOS 原生图表。本文与参考文件是普通 Markdown，不依赖特定 Agent、MCP 服务或专属终端工具。技能安装方式见 [INSTALL.md](INSTALL.md)。

## 先确认接入对象

1. 读取用户项目的 `oh-package.json5`、锁文件、已有图表页面和本项目约定，确认实际安装版本。
2. 新接入优先使用 `McChartsV2`、`McChartsController` 和公开 `Options` 类型，均从 `@mcui/mccharts` 导入。
3. 3.0.0 的注册表可用性需要当次核实。不要因精确版本不存在而改装 `latest`、2.8.9 或 npm 同名包。按 [接入参考](references/integration.md) 使用已发布的精确版本或官方提供的 HAR。
4. 若用户实际使用其他版本，以该版本的公开声明和文档为准，明确版本差异；不要把本技能的 3.0.0 API 直接套上去。

## 按任务读取参考

| 任务 | 读取 |
| --- | --- |
| 添加依赖、第一张图、组件属性、空白图排查 | [integration.md](references/integration.md) |
| 更新数据、重置、事件、坐标、图表联动、生命周期 | [controller.md](references/controller.md) |
| 图表类型、option、dataset、dataZoom、地图、性能边界 | [options.md](references/options.md) |
| 原生 PNG、工具箱导出、导出报错 | [export.md](references/export.md) |
| 2.8.9、旧包名、McLineChart/McBarChart、旧控制器迁移 | [migration.md](references/migration.md) |

只读取当前任务需要的文件；这些参考可离线使用。更多示例由提供此技能的官网开发文档和在线编辑器提供；下载页应提供对应入口。

## 不可混淆的行为

- `McChartsController` 是 `McEChartsController` 的公开别名；`McChartController`（少一个 `s`）属于另一套基础图表 API，不能替换它。
- `McChartsV2.options` 通过新引用更新，不递归监听数组内部修改。固定入口 `McLineChart` / `McBarChart` 的 `options` 仅在挂载时读取，后续通过对应 controller 更新。
- 一个 controller 绑定一张图，组件存活期间不替换 controller。需要多个图表时分别创建 controller。
- controller 命令返回 `false` 表示仍待执行，不代表命令丢失；不要因此循环重发。读取、坐标查询和导出需要图表已挂载且待执行命令已处理。
- 组件 `onChartEvent` 收到 `{ eventName, params }`；controller 的 `onEvent` 回调直接收到原始 `params`。不要混用这两种载荷。
- 原生宿主没有 DOM、Canvas 或 WebView 回退。浏览器预览可以辅助检查 option，但不能证明原生文字、手势、导出或性能一致。
- 导出用 `McChartsV2`，显式开启 `rasterText: true`，只支持 PNG、`pixelRatio: 1` 和空 `excludeComponents`；它返回 Promise，不自动保存相册。

## 实施与验证

先建立最小可显示的图表，再加入用户需要的交互与样式；保留现有页面架构、依赖管理方式及生命周期。不要为接入图表更换整套应用框架。

使用用户项目已有的 HarmonyOS 构建工具。若环境提供 `devecocli`，可在工程根目录执行 `devecocli build`；也可使用项目既有 DevEco Studio / Hvigor 流程。本技能不要求安装另一套 Agent 或 CLI。

按改动验证实际行为：首帧显示、数据更新、事件载荷、离开/返回页面；涉及手势、地图或导出时在目标设备/模拟器检查对应操作。构建成功只证明编译；无法运行设备时说明未验证项，不把浏览器截图或主机测试当作原生验收。

交付时指出修改文件、实际包版本、完成的验证与尚未验证的行为。不要把本技能版本、mccharts 产品版本和底层 ECharts 引擎版本混为一谈。