The examples in this article use @mcui/mccharts 3.0.0, a native chart component for ArkUI on HarmonyOS. It reuses the Apache ECharts 6.1.0 option model, draws through a native GLES path, and needs no WebView. The package is published on OHPM: ohpm install @mcui/mccharts@3.0.0.
A chart option that works in a browser often looks portable: categories, series and colors are all plain data. The trouble begins around the option. A web page may use a DOM element for sizing, HTML inside a tooltip, mouse hover, a download link and a chart instance that lives as long as the page.
On HarmonyOS, first carry over the data meaning and chart model. Then reconnect layout, touch, updates and export to the native host. Here's a small sales chart to make the steps concrete.
1. Confirm the package and make a small page
Check the consuming module's oh-package.json5, lock file and actual HAR before copying code. The component version in a developer's source checkout is not necessarily the version installed in the application.
import { McChartsV2, McChartsController } from '@mcui/mccharts';
import type { ChartClick, Options } from '@mcui/mccharts';
@Entry
@ComponentV2
struct MigratedSalesPage {
private controller: McChartsController = new McChartsController();
@Local private selected: string = 'Tap a point';
@Local private option: Options = {
animation: false,
tooltip: { trigger: 'item', renderMode: 'richText' },
grid: { left: 48, right: 24, top: 35, bottom: 40 },
xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
yAxis: { type: 'value', name: 'Orders', min: 0 },
dataZoom: [{ type: 'inside', start: 0, end: 100 }],
series: [{ id: 'orders', name: 'Orders', type: 'line', data: [12, 18, 15] }]
};
build() {
Column({ space: 12 }) {
McChartsV2({
options: this.option,
controller: this.controller,
enableDataZoom: true,
onChartClick: (event: ChartClick) => {
this.selected = `${event.name}: ${event.value}`;
}
}).width('100%').height(320)
Text(this.selected).width('100%')
}.width('100%').padding(16)
}
}
This page gives the chart a definite height and uses an ArkUI text element for the selected value. The value in ChartClick is a display string. For calculations or navigation, look up the original business record using a mapping that matches the current series input.
2. Replace the browser host, not just the function name
The web version may find a DOM node and initialize a chart inside it. The native version places McChartsV2 in the ArkUI layout. Its implementation creates an XComponent and reports area changes to the chart session:
.onAreaChange((_old: Area, area: Area) => this.session.resize(Number(area.width), Number(area.height)))
If the chart is inside Scroll, a conditional branch or a resizable window, verify the space actually provided by the parent. A valid option can still produce a blank area when the host has no usable size. Also check native library loading and ABI before assuming the series is wrong.
3. Move HTML tooltip content into an appropriate native UI
The example uses renderMode: 'richText'. The current native runtime explicitly rejects HTML tooltip mode:
if (tooltip?.renderMode === 'html') {
throw new Error('NATIVE_TOOLTIP_HTML_UNSUPPORTED: use renderMode richText or auto');
}
Changing renderMode alone is not enough if the formatter still returns <div> elements and buttons. Simple text can be formatted synchronously; a panel with a button, image or fetched details belongs in an ArkUI component driven by a chart event and business state. Do not return a Promise from a formatter and assume it will become a native detail panel.
4. Rebuild interaction for touch
Inside zoom requires both a dataZoom model in Options and the component's enableDataZoom: true. That still leaves an application decision: if the chart is inside a vertical Scroll, which gesture should move the chart and which should scroll the page? Test inside and outside the plot on the target device.
For a data click, verify the series and data index before using a business mapping. If the application sorts or filters records before building the series, replace the mapping with the same sorted or filtered batch. Marker clicks use onMarkerClick; their index refers to marker data, not the series data array.
5. Choose an update owner
The V2 component watches options and resetKey. A page can create a new Options reference when its state changes, or use a stable controller to submit a patch. Keep a single source of business truth: if the controller changes the chart but a later page update sends an old option, the old data can overwrite the new data.
With a controller, a patch for an existing series can look like this:
const patch: Options = {
series: [{ id: 'orders', data: [14, 20, 16] }]
};
const applied: boolean = this.controller.setOption(patch);
This fragment belongs in a method of a page that owns a McChartsController and has an orders series. false can mean commands are pending; do not spin in a retry loop. Ordinary merging can retain a series omitted from a patch. If a series must be removed, consider replaceMerge: ['series']; if the entire model must be replaced, use an appropriate non-merge update or change resetKey.
6. Treat export as a separate feature
Browser Canvas export and native Surface capture are not interchangeable. The current mccharts V2 export path requires rasterText: true, a mounted chart and a usable surface. The controller's getDataURL() returns a Promise containing PNG data; the app handles saving or sharing afterward.
Before migration is complete, compare the actual image against the requirement: are axis labels, units and the title present? Is the requested output only the chart or the whole page with filters and a table? A successful return value is not the same as a completed photo-album save.
A checklist for the final review
- The real package version, ABI and public imports match the target project.
- The chart receives non-zero layout space and displays the intended data and units.
- Web-only DOM, HTML tooltip and mouse assumptions have a native replacement.
- New data reaches the component through the chosen update owner; stale responses cannot replace a newer selection.
- Click and marker mappings refer to the same input batch shown by the chart.
- Zoom and page scrolling are checked together on the target device.
- Export, page return and background behavior are tested when the product requires them.
Keep the original data and a small set of expected user actions next to the migration. The goal is not a byte-for-byte copy of a browser screenshot; it is a correct chart that behaves naturally in the HarmonyOS page.