@mcui/mccharts 3.0.0 尚未发布到 ohpm,生产根目录尚未切换。
API 可能调整;性能、功耗、连续动画与像素画质尚未完成设备验收。
旁边的实时预览可直接编辑选项并查看效果。
声明式图表组件
McChartsV2 是 mccharts 的推荐入口:传入 option,按引用替换更新;
需要命令式操作时再绑定 McChartsController。
旧入口 McLineChart / McBarChart 与命令式
McChartsController 各自有独立文档页;即使属性看起来相同,也按组件分别维护。
快速开始
当前以本地 HAR 组件的方式接入。工程编译 API 19,仅包含 arm64-v8a。
运行环境
| 环境 | 要求 / 状态 | 说明 |
|---|---|---|
| 开发工具 | DevEco Studio + DevEco CLI | 构建、签名、安装与页面级联调。 |
| 运行测试 | Node 24 | 运行时 JS 的构建与主机测试。 |
| 编译 API | API 19 | 仅 arm64-v8a。 |
| 真机验证 | nova 12 Ultra · API 24 | 安装、启动与代表性页面操作通过。 |
| 最低系统 | 未确认 | 不能据此承诺 API 19 起全机型可用。 |
| 发布状态 | 本地组件包 3.0.0 | 未上 ohpm;生产根目录未切换。 |
1. 添加本地依赖
组件尚未发布到 ohpm。示例工程通过 file: 依赖引用仓库内的组件包
(目录名仍为 meichuangtools):
{
"dependencies": {
"@mcui/mccharts": "file:../meichuangtools"
}
}
2. 引入组件、控制器与类型
import { McChartsV2, McChartsController } from '@mcui/mccharts';
import type { Options, ChartClick } from '@mcui/mccharts';
3. 放入已有的 option
只有 options 是必填项。传入标准 option;需要外部控制、导出或事件订阅时再传入
controller。
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。
组件属性
McChartsV2 的完整属性表。类型、默认值与可选值均以当前 3.0.0 源码为准。
基础属性
| 属性 | 类型 / 默认 | 可选值 | 行为与注意 |
|---|---|---|---|
options |
Options必填 |
任意合法 option;至少包含 series、baseOption 或 graphic |
声明式入口。按引用替换触发更新,不递归观察大数据数组。 |
controller |
McChartsController默认新建 |
一个 controller 实例 | 可省略;省略后仍能渲染,但失去命令式 API、导出与事件订阅。一个 controller 只能绑定一张图。 |
resetKey |
string'' |
任意字符串 | 变化时以 notMerge: true 提交。不保证入场动画重播;重播需要先 clear()。 |
active |
booleantrue |
true | false |
页面/前后台活跃控制;与组件可见性共同暂停帧时钟。静态图停帧。 |
渲染与交互属性
| 属性 | 类型 / 默认 | 可选值 | 行为与注意 |
|---|---|---|---|
legacyType |
string'' |
'' | 'line' | 'bar' |
启用旧字段转换;标准字段优先。组件实例内固定,不能替换。 |
enableDataZoom |
booleanfalse |
true | false |
开启 inside dataZoom 的单指平移/双指缩放;默认让位页面滚动。 |
enableBrush |
booleanfalse |
true | false |
brush/工具栏 dataZoom 激活后接收拖动。开启后图表区域会常驻 Pan,页面滚动要从图表外开始。 |
rasterText |
booleanfalse |
true | false |
纹理文字快照,保留裁剪与原生绘制顺序。调用 getDataURL 导出时必须为 true。 |
showRenderStats |
booleanfalse |
true | false |
显示“读取绘制统计”按钮;按需采样,不建立轮询计时器。 |
事件属性
| 属性 | 类型 / 默认 | 可选值 | 行为与注意 |
|---|---|---|---|
eventNames |
string[][] |
任意事件名数组,见事件与载荷 | 组件事件白名单;只有列出的原始事件才会通过 onChartEvent 输出。 |
onChartClick |
(event: ChartClick) => void |
任意回调 / 省略 | 系列数据点击;载荷为简化后的展示字段,不是完整上游事件。 |
onMarkerClick |
(event: MarkerClick) => void |
任意回调 / 省略 | 标注点击;dataIndex 是标注索引,不是 series.data 索引。 |
onChartEvent |
(event: ChartEvent) => void |
任意回调 / 省略 | 输出 eventNames 中白名单事件的原始参数。 |
完整属性示例
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)
公开类型
@mcui/mccharts 对外导出常用类型;页面不再用 Object 兜底。
| 类型 | 用途 | 来源 / 别名 |
|---|---|---|
Options | 组件 options、controller.setOption 的配置类型 | Options(= LegacyChartOption) |
ChartClick | 系列点击回调载荷 | ChartClick |
MarkerClick | 标注点击回调载荷 | MarkerClick |
ChartEvent | onChartEvent / onEvent 的事件对象 | 事件类型的公开别名 |
ChartAction | controller.dispatchAction 的动作对象 | 动作类型的公开别名 |
ControllerOptions | McChartsController 构造选项 | 初始化类型的公开别名 |
DataURLOptions | getDataURL 的导出选项 | 导出选项类型的公开别名 |
SetOptionOptions | setOption 的 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 等原名仍然保留;事件、动作与导出类型也保留旧名。
已有代码可以逐步迁移到公开别名。
更新语义
声明式属性与命令式控制器共享同一套合并语义,但触发路径不同。
| 触发 | 默认行为 | 说明 |
|---|---|---|
替换 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);
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 不作为在线可编辑预设。 |
高级系列页(关系图、桑基、矩形树图、地图、平行坐标等)有主机样例,但完整选项矩阵与设备验收未完成。
组件与可选值
| 组件 | 常用可选值 | 说明 |
|---|---|---|
title | text、subtext、left、top | 文本由 ArkUI 叠层渲染。 |
legend | top、left、data、selectedMode | 图例联动沿用引擎。 |
grid | left、right、top、bottom、containLabel | 像素与百分比均可;窄卡片注意标签宽度。 |
xAxis / yAxis | type: 'category' | 'value' | 'time' | 'log'、min、max、inverse | 时间/对数轴按上游解析;复杂标签需验证。 |
tooltip | trigger: 'item' | 'axis' | 'none'、renderMode: 'richText'、formatter | HTML 模式拒绝;Promise formatter 拒绝。 |
dataset | source、transform、fromDatasetIndex | 常用 transform 可用;dataset 模式下请验证标签与序列化。 |
dataZoom | type: 'inside' | 'slider'、filterMode: 'filter'、start、end | inside 手势需 enableDataZoom;过滤/原始索引沿用上游。 |
toolbox | feature.magicType、restore、dataZoom、dataView、saveAsImage | saveAsImage 受原生快照与导出限制。 |
brush | toolbox、xAxisIndex、brushMode: 'single'、throttleType | 需要 enableBrush 接收拖动。 |
timeline | axisType、autoPlay、playInterval、data | baseOption / options / media 已接入。 |
graphic | type、shape、style、clipPath | 线性渐变、矩形/圆形裁剪、图片与阴影有限支持。 |
visualMap | min、max、pieces、inRange | 地理/热力样例覆盖;与地图注册配合。 |
geo / map | map、roam、regions、itemStyle | 地图需要先注册;SVG 地图按上游规则。 |
calendar / matrix / polar | 对应高级示例 | 有主机样例,设备验收未完成。 |
事件与载荷
简化事件与原始事件分开;需要完整字段时用原始事件 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 可使用下列事件名:
组件侧的 onChartEvent 只接收 eventNames 中列出的名称;
controller 的 onEvent 会自动登记对应事件。
手势
默认不争抢页面滚动;图表手势都需要显式开启。
| 属性 | 可选值 | 效果 | 注意 |
|---|---|---|---|
enableDataZoom | true | false | 单指平移、双指缩放 inside dataZoom | 默认关闭,页面正常滚动;开启后需要 option 含 inside dataZoom。 |
enableBrush | true | false | brush 框选、工具栏拖动 | 默认关闭;开启后图表区域常驻 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 */ }
}
})
渲染管线
不是 WebView,也不是应用层 Canvas;显示列表在这里被翻译成原生帧。
mccharts 3.0.0
模型、布局、动画与 dataZoom 过滤在 ArkTS 中运行;系统帧时钟提供活跃时间。
显示列表
zrender 图元转换为顶点、颜色、命令与文字运行;裁剪与渐变按用户坐标计算。
GLES 3.0
C++ 批量提交三角形;VBO 容量复用与脏区上传。单帧顶点预算 150 万。
ArkUI Text
真实字形由 ArkUI 叠层排版,位于全部几何之上;可选纹理文字快照保留裁剪顺序。
固定版本与预算
帧时间、FPS、功耗、热稳定、峰值内存与连续动画画质尚未完成设备验收。 单帧超过预算会给出诊断,而不是保证降级后仍与上游完全一致。
文字层
文字不烘焙进贴图,由 ArkUI Text 叠加在全部几何之上。这带来清晰的中文字形和无障碍描述, 也决定了层级取舍:任意文字/路径交错层级、文字描边、复杂非矩形裁剪、径向/文字渐变尚未完整实现。
工具箱与导出
magicType、restore、dataZoom、dataView、saveAsImage 走同一套动作管线。
| 功能 | 可选项 | 说明 |
|---|---|---|
magicType | ['line', 'bar', 'stack'] 子集 | 切换系列类型;上游过渡可用。 |
restore | 无 | 重置模型;不保证入场动画重播。 |
dataZoom | 轴索引、方向 | 与 inside dataZoom 手势相互独立。 |
dataView | readOnly: true | false | 不生成 DOM;宿主自渲染表格,编辑后需显式 setOption。 |
saveAsImage | type: 'png'、pixelRatio: 1、excludeComponents: [] | 原生 Surface 快照,包含工具栏,不按显示列表重渲染。 |
brush | rect、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
支持与限制
已完成的样例不等于全选项矩阵。以下边界建议在接入前逐条确认。
没有 Canvas / SVG fallback
拒绝应用层 Canvas/SVG renderer 与 WebView。未支持的图元会给出诊断,不会切换到浏览器渲染。
只支持 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) |
验证状态
记录值为 2026-10-25;主机测试使用系统 / GPU / N-API 替身,不等同设备用例。
生产根目录尚未切换,没有版本发布或 ohpm 包;HAR 体积未记录。
常见问题
可以直接使用任意 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 执行;文字度量与个别原生绘制能力以真机为准。
什么时候可以用于生产?
目前没有这个结论。性能、功耗、画质、完整选项矩阵与最低系统支持都仍未完成验收。
开源许可
mccharts 引擎包含 Apache-2.0 开源组件;完整许可证、NOTICE 与字体说明见独立许可页。
若重新分发引擎与字体,请保留 开源许可、许可证文件与 NOTICE。
其他组件
每个组件有独立文档、属性和在线预览,不混在同一张属性表里。
McLineChart
固定折线类型,保留旧调用方式;属性、事件与示例单独列出。
打开组件文档 → 旧入口 · 柱状McBarChart
固定柱状类型,属性与 McLineChart 相同但默认类型和行为分开说明。
打开组件文档 → 命令式控制McChartsController
setOption、dispatchAction、appendData、事件订阅与原生快照导出。
打开控制器文档 →
McChartV2 / McChartController 是另一套 GPU 对照实现,
与 mccharts 的组件、控制器和渲染路径不同,不要混用。
McChartsController 负责更新、动作、事件与导出。