返回官网 Developer Docs / Component

McChartsV2

声明式图表组件。完整属性、可选值、事件、手势与在线效果。

声明式组件mccharts 3.0.0API 19 工程@mcui/mccharts 3.0.0
实时预览可直接编辑 option
3.0.0 当前版本 · 按图表类型查看 option 属性 图表文档 → 更新日志
这是技术预览,不是生产发布。

@mcui/mccharts 3.0.0 尚未发布到 ohpm,生产根目录尚未切换。 API 可能调整;性能、功耗、连续动画与像素画质尚未完成设备验收。 旁边的实时预览可直接编辑选项并查看效果。

01 / COMPONENT

声明式图表组件

McChartsV2 是 mccharts 的推荐入口:传入 option,按引用替换更新; 需要命令式操作时再绑定 McChartsController。

1必填属性:options
可选controller / 事件 / 手势
按引用options 更新语义
360 × 390客户端验证视口
这个页面只讲 McChartsV2。

旧入口 McLineChart / McBarChart 与命令式 McChartsController 各自有独立文档页;即使属性看起来相同,也按组件分别维护。

02 / GET STARTED

快速开始

当前以本地 HAR 组件的方式接入。工程编译 API 19,仅包含 arm64-v8a。

运行环境

环境要求 / 状态说明
开发工具DevEco Studio + DevEco CLI构建、签名、安装与页面级联调。
运行测试Node 24运行时 JS 的构建与主机测试。
编译 APIAPI 19仅 arm64-v8a。
真机验证nova 12 Ultra · API 24安装、启动与代表性页面操作通过。
最低系统未确认不能据此承诺 API 19 起全机型可用。
发布状态本地组件包 3.0.0未上 ohpm;生产根目录未切换。

1. 添加本地依赖

组件尚未发布到 ohpm。示例工程通过 file: 依赖引用仓库内的组件包 (目录名仍为 meichuangtools):

oh-package.json5
{
  "dependencies": {
    "@mcui/mccharts": "file:../meichuangtools"
  }
}

2. 引入组件、控制器与类型

imports
import { McChartsV2, McChartsController } from '@mcui/mccharts';
import type { Options, ChartClick } from '@mcui/mccharts';

3. 放入已有的 option

只有 options 是必填项。传入标准 option;需要外部控制、导出或事件订阅时再传入 controller。

ChartPage.ets
import { McChartsV2, McChartsController } from '@mcui/mccharts';
import type { Options, ChartClick } from '@mcui/mccharts';

@Entry
@ComponentV2
struct ChartPage {
  private controller: McChartsController = new McChartsController();

  @Local option: Options = {
    animation: true,
    animationDuration: 800,
    textStyle: { fontFamily: 'HarmonyOS Sans', fontSize: 12 },
    tooltip: { trigger: 'axis', renderMode: 'richText' },
    grid: { left: 48, right: 24, top: 36, bottom: 38 },
    xAxis: { type: 'category', data: ['一月', '二月', '三月'] },
    yAxis: { type: 'value' },
    series: [{
      id: 'sales',
      type: 'line',
      smooth: true,
      symbolSize: 8,
      data: [120, 180, 150],
      areaStyle: { opacity: 0.16 }
    }]
  };

  build() {
    Column() {
      McChartsV2({
        options: this.option,
        controller: this.controller,
        active: true,
        enableDataZoom: false,
        onChartClick: (event: ChartClick) => {
          console.info(`${event.seriesType} · ${event.name} · ${event.value}`);
        }
      })
        .width('100%')
        .height(390)
        .backgroundColor('#FFFFFF')
        .borderRadius(12)
    }
    .padding(16)
    .width('100%')
    .height('100%')
    .backgroundColor('#F3F6FC')
  }
}
更新方式是按引用替换。

修改 this.option 需要赋一个新的对象引用;组件不会递归观察大数据数组。 需要命令式更新时使用 controller 的 setOption。

03 / PROPS

组件属性

McChartsV2 的完整属性表。类型、默认值与可选值均以当前 3.0.0 源码为准。

基础属性

属性类型 / 默认可选值行为与注意
options Options
必填
任意合法 option;至少包含 series、baseOption 或 graphic 声明式入口。按引用替换触发更新,不递归观察大数据数组。
controller McChartsController
默认新建
一个 controller 实例 可省略;省略后仍能渲染,但失去命令式 API、导出与事件订阅。一个 controller 只能绑定一张图。
resetKey string
''
任意字符串 变化时以 notMerge: true 提交。不保证入场动画重播;重播需要先 clear()。
active boolean
true
true | false 页面/前后台活跃控制;与组件可见性共同暂停帧时钟。静态图停帧。

渲染与交互属性

属性类型 / 默认可选值行为与注意
legacyType string
''
'' | 'line' | 'bar' 启用旧字段转换;标准字段优先。组件实例内固定,不能替换。
enableDataZoom boolean
false
true | false 开启 inside dataZoom 的单指平移/双指缩放;默认让位页面滚动。
enableBrush boolean
false
true | false brush/工具栏 dataZoom 激活后接收拖动。开启后图表区域会常驻 Pan,页面滚动要从图表外开始。
rasterText boolean
false
true | false 纹理文字快照,保留裁剪与原生绘制顺序。调用 getDataURL 导出时必须为 true。
showRenderStats boolean
false
true | false 显示“读取绘制统计”按钮;按需采样,不建立轮询计时器。

事件属性

属性类型 / 默认可选值行为与注意
eventNames string[]
[]
任意事件名数组,见事件与载荷 组件事件白名单;只有列出的原始事件才会通过 onChartEvent 输出。
onChartClick (event: ChartClick) => void 任意回调 / 省略 系列数据点击;载荷为简化后的展示字段,不是完整上游事件。
onMarkerClick (event: MarkerClick) => void 任意回调 / 省略 标注点击;dataIndex 是标注索引,不是 series.data 索引。
onChartEvent (event: ChartEvent) => void 任意回调 / 省略 输出 eventNames 中白名单事件的原始参数。

完整属性示例

McChartsV2 props
McChartsV2({
  options: this.option,
  controller: this.controller,
  resetKey: 'sales-v2',
  active: this.pageActive,
  legacyType: '',
  enableDataZoom: true,
  enableBrush: false,
  rasterText: true,
  showRenderStats: false,
  eventNames: ['brushselected', 'nativeexportrequest'],
  onChartClick: (event: ChartClick) => {
    console.info(event.seriesType, event.name, event.value);
  },
  onMarkerClick: (event: MarkerClick) => {
    console.info(event.componentType, event.dataIndex);
  },
  onChartEvent: (event: ChartEvent) => {
    console.info(event.eventName, event.params);
  }
})
  .width('100%')
  .height(390)
04 / TYPES

公开类型

@mcui/mccharts 对外导出常用类型;页面不再用 Object 兜底。

类型用途来源 / 别名
Options组件 options、controller.setOption 的配置类型Options(= LegacyChartOption)
ChartClick系列点击回调载荷ChartClick
MarkerClick标注点击回调载荷MarkerClick
ChartEventonChartEvent / onEvent 的事件对象事件类型的公开别名
ChartActioncontroller.dispatchAction 的动作对象动作类型的公开别名
ControllerOptionsMcChartsController 构造选项初始化类型的公开别名
DataURLOptionsgetDataURL 的导出选项导出选项类型的公开别名
SetOptionOptionssetOption 的 settings 选项setOption 选项类型的公开别名
类型用法
import { McChartsV2 } from '@mcui/mccharts';
import type { Options, ChartClick, ChartEvent } from '@mcui/mccharts';

@Local option: Options = {
  series: [{ type: 'line', data: [120, 180, 150] }]
};

McChartsV2({
  options: this.option,
  onChartClick: (event: ChartClick) => {
    console.info(event.seriesType, event.value);
  },
  onChartEvent: (event: ChartEvent) => {
    console.info(event.eventName);
  }
})

LegacyChartOption 等原名仍然保留;事件、动作与导出类型也保留旧名。 已有代码可以逐步迁移到公开别名。

05 / UPDATE

更新语义

声明式属性与命令式控制器共享同一套合并语义,但触发路径不同。

触发默认行为说明
替换 options 引用合并更新相同 id 的 series/data 保留上游过渡;不递归观察内部变更。
resetKey 变化notMerge: true替换模型并丢弃未执行命令;不保证入场动画重播。
active 变为 false暂停帧时钟不销毁模型;恢复后从活跃时间继续,不累加后台时间。
组件卸载解绑并保留快照重新挂载恢复最近成功配置;不续播动画中间帧。
显式 clear()清空模型丢弃未执行命令与延时任务;之后仍可再次 setOption。
controller setOption跟随 settings布尔值或 { notMerge, lazyUpdate, silent, replaceMerge }。
更新示例
// 声明式:赋新引用
this.option = {
  ...this.option,
  series: [{ id: 'sales', type: 'line', data: nextData }]
};

// 命令式:合并更新
this.controller.setOption({
  series: [{ id: 'sales', data: [132, 201, 168] }]
});

// 替换模型
this.controller.setOption(nextOption, { notMerge: true });

// 清空后重播入场
this.controller.clear();
this.controller.setOption(nextOption, true);
06 / OPTION

option 支持矩阵

标准 option 直接提交;以下为当前接入范围与关键取舍,不代表完整配置矩阵。

系列类型

series.type状态关键可选值 / 限制
line已覆盖smooth、step、stack、areaStyle、connectNulls;渐变面积需线性渐变。
bar已覆盖横向/竖向、正负堆叠、borderRadius、showBackground;large bar 跳过。
pie已覆盖radius、roseType、padAngle、borderRadius、外侧标签与引导线。
scatter已覆盖symbol、回调 symbolSize、clip、progressive;large 走专用路径。
radar已覆盖多边形/圆形网格、独立上下限、填充与标签。
gauge已覆盖指针/进度/多值、刻度、valueAnimation;模式切换建议 clear。
funnel已覆盖纵向/横向、排序、对齐、间隔、外侧标签。
candlestick已覆盖开高低收、涨跌配色、空心、dataZoom。
boxplot已覆盖五数概括、双组、离群点;dataset + transform 不作为在线可编辑预设。

高级系列页(关系图、桑基、矩形树图、地图、平行坐标等)有主机样例,但完整选项矩阵与设备验收未完成。

组件与可选值

组件常用可选值说明
titletext、subtext、left、top文本由 ArkUI 叠层渲染。
legendtop、left、data、selectedMode图例联动沿用引擎。
gridleft、right、top、bottom、containLabel像素与百分比均可;窄卡片注意标签宽度。
xAxis / yAxistype: 'category' | 'value' | 'time' | 'log'、min、max、inverse时间/对数轴按上游解析;复杂标签需验证。
tooltiptrigger: 'item' | 'axis' | 'none'、renderMode: 'richText'、formatterHTML 模式拒绝;Promise formatter 拒绝。
datasetsource、transform、fromDatasetIndex常用 transform 可用;dataset 模式下请验证标签与序列化。
dataZoomtype: 'inside' | 'slider'、filterMode: 'filter'、start、endinside 手势需 enableDataZoom;过滤/原始索引沿用上游。
toolboxfeature.magicType、restore、dataZoom、dataView、saveAsImagesaveAsImage 受原生快照与导出限制。
brushtoolbox、xAxisIndex、brushMode: 'single'、throttleType需要 enableBrush 接收拖动。
timelineaxisType、autoPlay、playInterval、databaseOption / options / media 已接入。
graphictype、shape、style、clipPath线性渐变、矩形/圆形裁剪、图片与阴影有限支持。
visualMapmin、max、pieces、inRange地理/热力样例覆盖;与地图注册配合。
geo / mapmap、roam、regions、itemStyle地图需要先注册;SVG 地图按上游规则。
calendar / matrix / polar对应高级示例有主机样例,设备验收未完成。
07 / EVENTS

事件与载荷

简化事件与原始事件分开;需要完整字段时用原始事件 API。

入口触发载荷 / 可选值
onChartClick / controller.on('click') 系列数据点击 { seriesIndex, dataIndex, name, value, seriesType, seriesId?, seriesName?, data?, valueRaw?, percent?, color? };value 为展示字符串。
onMarkerClick / onMarkerClick(fn) 标注点击 继承 ChartClick,并带 componentType: 'markPoint' | 'markLine' | 'markArea';索引是标注索引。
onChartEvent eventNames 白名单 { eventName: string, params: Object };原始参数。
onEvent(name, fn) 任意上游事件 完整原始 payload(数组、batch、selected 等)。

可用事件名

eventNames 或 onEvent 可使用下列事件名:

clickdblclickmousedownmousemovemouseup mouseovermouseoutglobaloutcontextmenu legendselectchangeddatazoombrushselected timelinechangedhighlightdownplayselectchanged nativeexportrequestnativedataviewrequest

组件侧的 onChartEvent 只接收 eventNames 中列出的名称; controller 的 onEvent 会自动登记对应事件。

08 / INPUT

手势

默认不争抢页面滚动;图表手势都需要显式开启。

属性可选值效果注意
enableDataZoomtrue | false单指平移、双指缩放 inside dataZoom默认关闭,页面正常滚动;开启后需要 option 含 inside dataZoom。
enableBrushtrue | falsebrush 框选、工具栏拖动默认关闭;开启后图表区域常驻 Pan,页面滚动从图表外开始。
Tap始终可用系列点击 / 标注点击通过 onChartClick / onMarkerClick 接收。
手势与事件
McChartsV2({
  options: this.option,
  controller: this.controller,
  enableDataZoom: true,
  enableBrush: true,
  eventNames: ['brushselected'],
  onChartClick: (event) => {
    console.info(event.seriesType, event.name, event.value);
  },
  onMarkerClick: (event) => {
    console.info('marker', event.dataIndex);
  },
  onChartEvent: (event) => {
    if (event.eventName === 'brushselected') { /* raw payload */ }
  }
})
09 / RENDER

渲染管线

不是 WebView,也不是应用层 Canvas;显示列表在这里被翻译成原生帧。

01

mccharts 3.0.0

模型、布局、动画与 dataZoom 过滤在 ArkTS 中运行;系统帧时钟提供活跃时间。

02

显示列表

zrender 图元转换为顶点、颜色、命令与文字运行;裁剪与渐变按用户坐标计算。

03

GLES 3.0

C++ 批量提交三角形;VBO 容量复用与脏区上传。单帧顶点预算 150 万。

04

ArkUI Text

真实字形由 ArkUI 叠层排版,位于全部几何之上;可选纹理文字快照保留裁剪顺序。

固定版本与预算

6.1.0底层引擎 / zrender
1.5M单帧顶点预算
1,000单帧文字运行上限
64每个线性渐变色标上限
16 MiBlarge 批次 CPU 缓存
603打包模块数
这些是约束与诊断阈值,不是性能承诺。

帧时间、FPS、功耗、热稳定、峰值内存与连续动画画质尚未完成设备验收。 单帧超过预算会给出诊断,而不是保证降级后仍与上游完全一致。

文字层

文字不烘焙进贴图,由 ArkUI Text 叠加在全部几何之上。这带来清晰的中文字形和无障碍描述, 也决定了层级取舍:任意文字/路径交错层级、文字描边、复杂非矩形裁剪、径向/文字渐变尚未完整实现。

10 / TOOLBOX

工具箱与导出

magicType、restore、dataZoom、dataView、saveAsImage 走同一套动作管线。

功能可选项说明
magicType['line', 'bar', 'stack'] 子集切换系列类型;上游过渡可用。
restore无重置模型;不保证入场动画重播。
dataZoom轴索引、方向与 inside dataZoom 手势相互独立。
dataViewreadOnly: true | false不生成 DOM;宿主自渲染表格,编辑后需显式 setOption。
saveAsImagetype: 'png'、pixelRatio: 1、excludeComponents: []原生 Surface 快照,包含工具栏,不按显示列表重渲染。
brushrect、polygon、clear、brushMode: 'single'配合 enableBrush;输入按帧合并。
导出约束是硬性的。
  • 仅 PNG;pixelRatio 必须为 1;excludeComponents 必须为空。
  • 组件必须设置 rasterText: true;快照包含工具栏,不排除组件。
  • 按当前设备像素生成,不按显示列表重新渲染;Base64 data URL 上限 16 MiB。
  • 只返回预览 data URL,不写相册、不分享、不落盘。
  • dataView 的 optionToContent / contentToOption 返回 NATIVE_DATAVIEW_DOM_UNSUPPORTED。

导出错误码

NATIVE_EXPORT_TYPE_UNSUPPORTED
NATIVE_EXPORT_PIXEL_RATIO_UNSUPPORTED
NATIVE_EXPORT_EXCLUDE_UNSUPPORTED
NATIVE_EXPORT_BACKGROUND_UNSUPPORTED
NATIVE_EXPORT_RASTER_TEXT_REQUIRED
NATIVE_EXPORT_SURFACE_UNAVAILABLE
11 / LIMITS

支持与限制

已完成的样例不等于全选项矩阵。以下边界建议在接入前逐条确认。

渲染

没有 Canvas / SVG fallback

拒绝应用层 Canvas/SVG renderer 与 WebView。未支持的图元会给出诊断,不会切换到浏览器渲染。

Tooltip

只支持 richText

HTML 模式明确拒绝;返回 Promise 的异步 formatter 也拒绝。同步与 ticket 异步 formatter 可用。

文字

覆盖在所有几何之上

无任意 z 序、文字描边不完整、复杂裁剪受限;文字度量与像素对齐尚未完成设备复测。

渐变

线性渐变完整

支持 fill/stroke/background、多色标与透明度,最大 64 色标;径向/文字渐变未完整实现。

大数据

large scatter 专用路径

统一 symbol/样式,无逐点 itemStyle、label、emphasis 或逐点动画;large bar 明确跳过。

成本

可见窗口不等于全量成本

dataZoom 过滤不消除原始数组解析、筛选、统计与布局成本;只显示 500 点不代表只处理 500 点。

硬限制速查

项目上限 / 说明
单帧顶点1,500,000
单帧文字1,000 个文字运行
线性渐变色标64 / 渐变
Controller 待执行命令256 条;超过抛错
CPU large 批次缓存16 MiB / 128 批,不含 JS 堆
VBO 容量64,000,000 B / 实例
面积路径100,000 展平点 / 100,000 交点或合并点
导出 data URL≤ 16 MiB(Base64)
12 / STATUS

验证状态

记录值为 2026-10-25;主机测试使用系统 / GPU / N-API 替身,不等同设备用例。

主机测试196 条宿主 + 814 条运行时 = 1,010 条通过。
PASS
构建与签名BUILD SUCCESSFUL;签名 HAP 已生成。
PASS
真机冒烟nova 12 Ultra API 24 安装、启动,Smoke: PASS。
SMOKE
页面操作工具栏切换、brush 7+7 选择、dataView 45→60、PNG 导出预览。
CHECKED
性能与画质FPS、帧时间、功耗、热稳定、峰值内存、连续动画与像素画质未验收。
OPEN
ArkTS 检查38 个文件,0 错误,4 警告;Lint filesChecked 为 0,不能视为通过。
PARTIAL
没有生产发布。

生产根目录尚未切换,没有版本发布或 ohpm 包;HAR 体积未记录。

13 / FAQ

常见问题

可以直接使用任意 option 吗?

大多数标准模型与配置可以提交,但原生后端只实现了有限图元与能力。 HTML tooltip、径向渐变、任意 z 序文字、large bar 等会被拒绝或给出诊断。 先对照“支持与限制”,再用真机样例页验证。

为什么文字看起来在所有图形上面?

文字由 ArkUI Text 叠层渲染,位于 GLES 几何之上。这是清晰中文字形与无障碍支持的代价。

PNG 导出为什么失败?

检查组件是否设置 rasterText: true,是否只传 PNG、 pixelRatio: 1 和空 excludeComponents,以及 Surface 是否仍然存活。

浏览器实验室的预览与真机是什么关系?

实验室使用同版本引擎、同源 option 工厂、HarmonyOS Sans 与 360 × 390 视口。 浏览器由 Canvas 执行显示列表,客户端由 GLES + ArkUI 执行;文字度量与个别原生绘制能力以真机为准。

什么时候可以用于生产?

目前没有这个结论。性能、功耗、画质、完整选项矩阵与最低系统支持都仍未完成验收。

14 / LICENSE

开源许可

mccharts 引擎包含 Apache-2.0 开源组件;完整许可证、NOTICE 与字体说明见独立许可页。

第三方组件与再分发声明

若重新分发引擎与字体,请保留 开源许可、许可证文件与 NOTICE。

15 / OTHER COMPONENTS

其他组件

每个组件有独立文档、属性和在线预览,不混在同一张属性表里。

旧 GPU 原型不在本组文档内。

McChartV2 / McChartController 是另一套 GPU 对照实现, 与 mccharts 的组件、控制器和渲染路径不同,不要混用。

继续看命令式控制?

McChartsController 负责更新、动作、事件与导出。

打开控制器文档