McChartsController 文档 · 莓创图表 mccharts

01 / CONTROLLER

命令式控制

声明式组件负责首帧和引用更新；controller 负责 setOption、动作、事件、坐标查询与原生快照导出。

1 : 1controller 与图表绑定

256挂载前命令队列上限

PromisegetDataURL 返回

可选组件不传 controller 也能渲染

02 / GET STARTED

快速开始

先创建 controller，再传给组件；挂载前的命令会按顺序排队。

Controller.ets

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

@Entry
@ComponentV2
struct ChartPage {
  private controller: McChartsController = new McChartsController();
  @Local option: Options = {
    series: [{ id: 'sales', data: [120, 180, 150] }]
  };

  aboutToAppear(): void {
    this.controller.setOption(this.option);
  }

  build() {
    McChartsV2({
      options: this.option,
      controller: this.controller
    })
      .width('100%')
      .height(390)
  }
}

一个 controller 只能绑定一张图。

重复绑定会抛错；组件卸载后 controller 可以重新绑定到新组件。挂载前最多排队 256 条命令，超过上限会抛错。

03 / CONTROLLER

控制器 API

McChartsController 是命令式入口。挂载前有界排队，挂载后按顺序执行；失败不会静默丢弃。

方法	参数 / 可选值	返回	说明
`setOption(option, settings?)`	`option: Options` `settings?: boolean \| { notMerge?, replaceMerge?, lazyUpdate?, silent? }`	`boolean`	合并或替换模型。`true` / `{ notMerge: true }` 丢弃未执行旧命令。
`getOption()`	无	`Options`	真实合并配置，保留 formatter；未就绪或失败时抛错。
`dispatchAction(action)`	`{ type: string, ... }`	`boolean`	支持 dataZoom、showTip/hideTip、highlight/downplay、legend 等动作。
`clear()`	无	`boolean`	清空图表并丢弃未执行命令与延时任务；之后仍可 setOption。
`appendData(options)`	`{ seriesIndex: number, data: Array \| TypedArray }`	`boolean`	增量追加 scatter / lines；不自动扩展坐标轴；拒绝 dataset/timeline。
`resize(width, height)`	有限正数	`void`	图表坐标尺寸；组件布局通常自动调用。
`getDataURL(options?)`	`{ type?: 'png', pixelRatio?: 1, backgroundColor?: string, excludeComponents?: [] }`	`Promise<string>`	原生 Surface 快照；要求挂载、`rasterText: true`、存活 Surface。
`on('click', fn)` / `off`	回调 / 省略	`void`	仅系列点击；`value` 为展示字符串。
`onEvent(name, fn)` / `offEvent`	`name: string`，回调	`void`	原始上游 payload，不缩减。
`onMarkerClick(fn)` / `offMarkerClick`	回调 / 省略	`void`	标注点击；索引独立于 series.data。
`convertToPixel` / `convertFromPixel`	`finder` + 坐标	坐标 / `undefined`	坐标查询；需挂载并处理完命令。
`containPixel`	`finder` + `[x, y]`	`boolean`	命中测试；像素为图表单位。
`getWidth` / `getHeight`	无	`number`	读取图表尺寸。
`setGroup` / `getGroup`	`group: string`	`string`	connect 分组。
`getInitOptions`	无	`ControllerOptions`	读取构造时传入的初始化选项。
`dispose()` / `isDisposed()`	无	`void` / `boolean`	永久释放；重复调用无副作用。

构造选项

字段	类型 / 默认	可选值	说明
`theme`	`string \| Object`	已注册主题名 / 主题对象	初始化主题；需先注册。
`locale`	`string \| Object`	已注册语言名 / 语言对象	初始化语言。
`foregroundScope`	`string` · `'default'`	任意 scope 名称	前后台暂停的作用域标识。

getDataURL 选项

字段	可选值	说明
`type`	`'png'`	仅 PNG；其他值拒绝。
`pixelRatio`	`1`	必须为 1；不做显示列表重渲染。
`backgroundColor`	`#RGB` / `#RRGGBB` / `#RRGGBBAA` / `white` / `black` / `transparent` / `none`	快照背景合成。
`excludeComponents`	`[]`	必须为空；快照包含工具栏。

队列、返回值与生命周期

一个 controller 只能绑定一张图；重复挂载会抛错。
挂载前最多排队 256 条命令；超过上限抛错。入队后不要修改配置/回调对象。
返回 true 表示已应用；false 表示等待布局或仍在失败队列，不是丢弃。
普通合并不静默丢弃失败命令；恢复用 setOption(valid, true) 或 clear()。
监听器异常被隔离并写入日志，不停止引擎。
卸载只解除绑定并保存最近成功配置；重挂载恢复 series/formatter/图例/dataZoom 状态，不续播动画中间帧。
controller 与 legacyType 在组件实例内固定；更换需要重建组件。

命令、事件与导出

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

// 命令式动作
this.controller.dispatchAction({
  type: 'highlight',
  seriesIndex: 0,
  dataIndex: 2
});

// 简化点击
this.controller.on('click', event => {
  console.info(event.seriesType, event.name, event.value);
});

// 原始事件
this.controller.onEvent('brushselected', params => { /* ... */ });

// 原生快照（组件需 rasterText: true）
const png = await this.controller.getDataURL({
  type: 'png',
  pixelRatio: 1,
  excludeComponents: []
});

04 / EVENTS

事件 API

controller 可以订阅简化点击或原始 payload；组件侧的 @Event 是另一种入口。

方法	触发 / 可选值	载荷
`on('click', fn)`	系列点击；`off('click', fn)` 取消	简化 ChartClick：`seriesType`、`name`、`value` 等
`onEvent(name, fn)`	`click`、`datazoom`、`brushselected` 等	原始对象；数组、batch、selected 不缩减
`onMarkerClick(fn)`	标注点击；`offMarkerClick(fn)` 取消	ChartClick + `componentType: 'markPoint' \| 'markLine' \| 'markArea'`

事件

this.controller.on('click', event => {
  console.info(event.seriesType, event.name, event.value);
});

this.controller.onEvent('brushselected', params => {
  console.info(params.batch);
});

this.controller.onMarkerClick(event => {
  console.info(event.componentType, event.dataIndex);
});

05 / LIMITS

限制

项目	规则
绑定	一个 controller 只能绑定一张图；重复绑定抛错。
命令队列	挂载前最多 256 条；超过抛错。返回 false 不表示丢弃，而是等待布局或仍在失败队列。
导出	PNG、`pixelRatio: 1`、空 `excludeComponents`；组件必须 `rasterText: true`。
事件	监听器异常被隔离并写日志，不停止引擎。
生命周期	卸载保存最近成功配置；重挂载恢复模型，但不续播动画中间帧。

引擎级预算与错误码见 McChartsV2 支持与限制。

06 / FAQ

常见问题

不传 controller 会怎样？

组件仍会渲染，但无法使用 setOption、dispatchAction、事件订阅、坐标查询与 getDataURL。

setOption 返回 false 是失败吗？

不是。false 表示命令已入队但尚未执行，常见于挂载前或布局尚未完成；失败命令会保留而非静默丢弃。

可以多个图表共用一个 controller 吗？

不可以。一个 controller 只能绑定一张图；多个图表需要多个实例。