McBarChart 组件文档 · 莓创图表 mccharts

固定入口组件，不是 McChartsV2 的别名。

McBarChart 保留旧的组件名和 options 写法，内部接入 mccharts 引擎。它与 McChartsV2 的属性集合不同，更新方式也不同；新项目优先使用 McChartsV2。

01 / COMPONENT

McBarChart

固定柱状入口。适合已经使用旧调用方式的页面；组件接收旧 options，由 mccharts 引擎完成渲染。

bar默认系列类型

Objectoptions 默认 {}

V1旧组件声明方式

可选controller / 手势 / 事件

02 / GET STARTED

快速开始

传入柱状数据即可；需要外部更新、点击、导出或 dataZoom 时再绑定 McChartsController。

McBarChart.ets

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

@Entry
@ComponentV2
struct TrendPage {
  private controller: McChartsController = new McChartsController();
  private option: Options = {
    textStyle: { fontFamily: 'HarmonyOS Sans', fontSize: 12 },
    grid: { left: 46, right: 22, top: 34, bottom: 34 },
    xAxis: {
      type: 'category',
      data: ['一月', '二月', '三月', '四月', '五月', '六月']
    },
    yAxis: { type: 'value', min: 0, max: 80 },
    series: [{
      id: 'trend',
      data: [42, 58, 35, 66, 49, 72],
      barMaxWidth: 24,
      itemStyle: { borderRadius: [6, 6, 0, 0] }
    }]
  };

  build() {
    McBarChart({
      options: this.option,
      controller: this.controller,
      active: true,
      enableDataZoom: false,
      rasterText: false
    })
      .width('100%')
      .height(390)
  }
}

options 在初次挂载时读取。

后续数据更新请使用 controller.setOption(...)；不要直接原地修改 series.data 数组并期待组件自动刷新。

03 / PROPS

组件属性

McBarChart 的完整属性。它与 McLineChart 属性集合相同，但默认类型和示例不同，因此各自独立成页。

属性	类型 / 默认	可选值	行为与注意
`options`	`Options` `{}`	任意合法旧/标准 option；未写 `series.type` 时按 bar 处理	默认空对象。初次挂载读取；后续更新走 controller。
`controller`	`McChartsController` 默认新建	一个 controller 实例	可省略；需要 setOption、事件、导出时传入。一个实例只绑定一张图。
`active`	`boolean` `true`	`true \| false`	组件活跃状态；与页面可见性共同暂停帧时钟。
`enableDataZoom`	`boolean` `false`	`true \| false`	开启 inside dataZoom 的单指平移/双指缩放；需 option 含 dataZoom。
`rasterText`	`boolean` `false`	`true \| false`	纹理文字快照；调用 `getDataURL` 导出时必须为 true。
`eventNames`	`string[]` `[]`	`click`、`datazoom`、`brushselected` 等	原始事件白名单，仅传给 `onChartEvent`。
`onChartClick`	`(event: ChartClick) => void`	回调 / 省略	系列数据点击；`value` 为展示字符串。
`onMarkerClick`	`(event: MarkerClick) => void`	回调 / 省略	标注点击；`dataIndex` 是标注索引。
`onChartEvent`	`(event: { eventName, params }) => void`	回调 / 省略	只接收 `eventNames` 中列出的原始事件。
`options.cWidth`	`number \| string` `'100%'`	有限正数 / 百分比字符串	旧字段，作为组件宽度；外层布局仍可覆盖。
`options.cHeight`	`number \| string` `'100%'`	有限正数 / 百分比字符串	旧字段，作为组件高度。

固定入口不提供 resetKey、legacyType、enableBrush 或 showRenderStats；这些是 McChartsV2 的属性。

04 / OPTION

options 映射

旧字段会映射为引擎配置；标准字段优先，组件默认系列类型为 bar。

字段	可选值 / 默认	说明
`series.type`	未写时按 `bar`	组件以柱状为默认；不要用它切换成 line，折线请使用 McLineChart。
`series.barWidth` / `barMaxWidth`	`number \| string`	柱宽与最大柱宽；窄卡片建议使用 barMaxWidth。
`series.stack`	任意堆叠组名	同组序列堆叠；正负值分别堆叠。
`series.itemStyle.borderRadius`	`number \| [lt, rt, rb, lb]`	圆角柱；与背景、堆叠组合时注意裁剪。
`series.showBackground`	`true \| false`	柱背景；颜色与透明度由 backgroundStyle 控制。
`dataZoom`	`inside` / `slider`	inside 手势需要 `enableDataZoom: true`。
`cWidth` / `cHeight`	`number \| string`	旧尺寸字段；标准 option 其余配置直接提交。

05 / DIFFERENCE

与 McChartsV2 的对照

能力	McBarChart	McChartsV2
声明方式	旧 `@Component` 入口	`@ComponentV2` 入口
默认类型	固定 bar	标准 option，多系列类型
`options` 更新	初次挂载读取，后续走 controller	替换引用即可更新
`resetKey`	不支持	支持
`legacyType`	不需要（类型固定）	支持旧字段转换
`enableBrush`	不支持	支持
`showRenderStats`	不支持	支持
事件	支持点击 / 标注 / 原始事件	同样支持

06 / EVENTS

事件

固定入口与 McChartsV2 共用事件载荷；区别只是属性名和组件声明方式。

入口	用途	载荷
`onChartClick`	柱状数据点 / 系列点击	`{ seriesIndex, dataIndex, name, value, seriesType, ... }`
`onMarkerClick`	markPoint / markLine / markArea 点击	ChartClick + `componentType`
`onChartEvent`	白名单原始事件	`{ eventName, params }`；需配合 `eventNames`

事件与手势

McBarChart({
  options: this.option,
  controller: this.controller,
  enableDataZoom: true,
  eventNames: ['datazoom'],
  onChartClick: (event) => {
    console.info(event.seriesType, event.name, event.value);
  },
  onChartEvent: ({ eventName, params }) => {
    if (eventName === 'datazoom') { /* ... */ }
  }
})
  .width('100%')
  .height(390)

07 / INPUT

手势

旧柱状入口只提供 dataZoom 手势，没有 brush 开关。

属性	可选值	效果
`enableDataZoom`	`true \| false`	单指平移、双指缩放；需要 option 含 inside dataZoom。
Tap	始终可用	数据点点击与标注点击。

08 / LIMITS

限制与导出

渲染引擎的硬限制与 McChartsV2 相同，详细预算和错误码见公共文档。

没有 enableBrush；需要框选时使用 McChartsV2 或工具箱动作。
导出必须是 PNG、pixelRatio: 1、空 excludeComponents，并要求 rasterText: true。
后续更新必须通过 controller；旧组件不会递归观察 options 内部数组。
文字由 ArkUI 叠层渲染，位于几何之上；复杂的文字/路径交错层级不支持。

完整的渲染预算、渐变、large 数据与导出错误码： McChartsV2 支持与限制。

09 / FAQ

常见问题

McBarChart 和 McChartsV2 可以混用吗？

不要在同一张图里混用两套组件或控制器。新项目使用 McChartsV2；旧页面可以单独保留 McBarChart。

为什么改了 options 没更新？

固定入口只在初次挂载时读取 options。请调用 controller.setOption(...)，或改用 McChartsV2 后替换 options 引用。

可以传入折线数据吗？

这个组件的默认类型是柱状。需要折线请使用 McLineChart，两者属性集合一样但类型和默认示例不同。

需要标准多系列组件？

McChartsV2 支持完整属性、resetKey、brush 与在线编辑。

查看 McChartsV2