This article is based on @mcui/mccharts 3.0.0: a native HarmonyOS chart component that drops into an ArkUI page, reuses the Apache ECharts 6.1.0 option model, and renders through native GLES without a WebView. It is available on OHPM (ohpm install @mcui/mccharts@3.0.0).
A chart can look like one rectangular widget on the screen, but several parts have to agree before that picture appears. The page supplies data and space. The chart runtime turns an option into a scene. A native drawing surface presents geometry, while text and gestures need their own connection to HarmonyOS.
This is the path used by @mcui/mccharts 3.0.0. We'll start with a small line chart, then follow it through the component rather than treating “native” as a magic performance claim.
The screenshot is from the component demo. The code below uses a separate, smaller set of sample values.
Start with an ArkUI page
import { McChartsV2 } from '@mcui/mccharts';
import type { Options } from '@mcui/mccharts';
function makeOption(last: number): Options {
return {
animation: false,
tooltip: { trigger: 'axis', renderMode: 'richText' },
grid: { left: 48, right: 24, top: 30, bottom: 40 },
xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
yAxis: { type: 'value', name: 'Orders', min: 0 },
series: [{
id: 'orders', name: 'Orders', type: 'line',
data: [12, 18, last]
}]
};
}
@Entry
@ComponentV2
struct NativeOrdersPage {
@Local private option: Options = makeOption(15);
build() {
Column({ space: 12 }) {
McChartsV2({ options: this.option }).width('100%').height(320)
Button('Update Wednesday').onClick(() => {
this.option = makeOption(21);
})
}.width('100%').padding(16)
}
}
The page owns the data and gives the chart a height. The option describes an axis and a series; it is not a list of ArkUI Column children to draw. On update, the page assigns a new option object. The stable series ID identifies the same logical series across updates.
What happens after the component appears?
The component connects a session to its option, text measurement, callbacks and controller. The native host is created with an XComponent; this excerpt is from the component source:
XComponent({ id: this.session.id, type: XComponentType.TEXTURE, libraryname: 'mcchart',
controller: this.xComponentController })
.width('100%').height('100%').onLoad(() => this.session.onLoad())
The component also reports layout changes to the session:
.onAreaChange((_old: Area, area: Area) => this.session.resize(Number(area.width), Number(area.height)))
Those events answer different questions: is the native host loaded, and how much space did the layout give it? The session does not need the page to guess which happens first. Its runtime creation guard checks attachment, controller binding, loading, option and positive dimensions:
if (!this.attached || this.controllerBindingFailed || !this.loaded || this.runtime || this.options === undefined || this.width <= 0 || this.height <= 0) { return; }
That guard is useful when a chart is blank. A correct series cannot fix a parent layout that supplies zero height. Check the dependency and native library too, then reduce the option to a small axis-and-series example before adding complexity back.
A frame contains more than the line
The runtime maintains the chart model, computes layout and animation, and produces frame data. The session's presentation path includes:
const frame = this.runtime.tick(this.elapsedMs);
if (frame.revision !== this.revision || (this.rasterizer?.needsPresent() ?? false)) {
let rasterDiagnostics: string[] = [];
if (this.rasterText && this.rasterizer) { rasterDiagnostics = this.rasterizer.present(frame); }
else { nativeChart.setScene(this.id, frame.vertices, frame.commands, 0, 0); }
This is an excerpt; the full method also handles diagnostics, frame delivery and errors. The normal native path sends geometry and draw commands to the native renderer. Text measurement and presentation are also needed for axis labels and tooltips. In the default path, the component includes a NativeTextLayer; with rasterText enabled, it also creates a raster host for the corresponding text rendering path.
The distinction matters for export. A Surface snapshot does not automatically include a separate ArkUI text overlay. The current native export path requires rasterText: true and returns a PNG data URL asynchronously through the controller. Saving an image file or opening the system share sheet is application work after that result.
Updates and touches cross the host boundary too
The component watches its option and reset key:
@Monitor('options', 'resetKey')
onOptions(): void {
const notMerge = this.appliedResetKey !== this.resetKey;
if (this.session.updateOption(this.options, notMerge)) { this.appliedResetKey = this.resetKey; }
this.interactionActive = this.session.isChartInteractionActive();
}
Assigning a new option gets a change to this boundary. Ordinary updates merge; changing resetKey requests a non-merged model. They are different choices, and neither automatically fixes stale business data or an old network response.
Touches originate in ArkUI gestures and are passed into the chart session for hit testing. A series click and a marker click have different callbacks. For a marker, dataIndex identifies the marker entry; do not use it as an index into the series data. For inside data zoom, configure the dataZoom option and enable the component gesture; then test it inside the actual scrolling page.
What “without a WebView” does and does not tell you
It means this component's chart host does not embed a WebView to display the chart. It does not mean every browser option or effect is available. In particular, an HTML tooltip needs a browser DOM; use the supported rich-text path on the native host. Text layering, clipping, shadows, image export and gesture arbitration all need checking on the target device.
It also says nothing by itself about a measured frame rate or a maximum safe data count. Record the device, data volume, update frequency and user action when comparing performance. A browser playground is useful for checking an option, but its Canvas output and timing are not a substitute for native device results.
For a production integration, verify the actual HAR version and ABI, mount a chart with non-zero size, update it, tap the data, leave and return, and test any required gestures or export. Following those steps makes it much easier to locate the failing layer when the screen is blank or the data appears stale.