Components/ECharts Family

ECharts Family

ECharts-backed charts: a themed host plus typed wrappers for common chart types.

VerifiedSince 0.6.0

Installation

echarts is an optional peer dependency: install it in the host application and the family lights up, leave it out and nothing else in Tuffex changes. It is never bundled — the components import it dynamically, so it lands in its own chunk the first time one of them mounts.

pnpm add echarts @talex-touch/tuffex
import { TxEChart, TxLineChart } from '@talex-touch/tuffex/charts'

Usage

Best Practices

  • Give the host a definite height. A zero-height container cannot paint.
  • Prefer a typed wrapper. For a sunburst, pass hierarchical data with type: 'sunburst' directly to TxEChart; its runtime registers that series. For other long-tail types, obtain the runtime through loadECharts() and register the corresponding ECharts module first.
  • Use aria-label: the label makes a canvas chart readable to assistive tech.
  • Pass data, not pixels: the wrappers map your data onto the option, so theme colours and axis chrome stay consistent.
  • Install echarts in the host application; a missing peer is reported in the container instead of failing silently.

API Reference

Every chart in the family accepts the shared props below plus its own data props, and every one forwards a raw option that is merged over the built option — objects merge deep, arrays are replaced whole. That covers series and dataZoom: a dataZoom list you pass stands in for the built-in zoom.

NameTypeDefaultDescription
optionEChartsOption—Merged over the built option: the per-chart customization hatch.
heightnumber | string320Chart height: px, or any CSS length.
theme'auto' | 'light' | 'dark''auto'auto follows the surrounding theme.
ariaLabelstring—Accessible name; adds role="img" to the host.
loadingbooleanfalseThemed loading mask until data arrives.
update'replace' | 'merge''replace'TxEChart only: replace swaps the series array so removed series stop being drawn; merge keeps ECharts' own merge semantics.
cooperativeWheelbooleantrueA plain wheel scrolls the page; false hands the wheel back to ECharts. On TxEChart and the zooming wrappers, see Pointer Input.

Per-chart props

ChartProps
TxLineChartseries (name, data, color?, area?, smooth?, stack?, dashed?), categories?, xAxisName?, yAxisName?, showLegend?, grid?, zoom?, cooperativeWheel?
TxBarChartseries (name, data, color?, stack?), categories?, xAxisName?, yAxisName?, showLegend?, grid?, stacked?, horizontal?, barWidth?, showLabel?, zoom?, cooperativeWheel?
TxPieChartdata (name, value, color?), donut?, roseType?, showLegend?, labelPosition?, centerLabel?, unit?
TxFunnelChartdata (name, value, color?), sort?, gap?, minSize?, maxSize?, labelPosition?, showLabel?, showLegend?, unit?
TxRadarChartindicators (name, max, min?), series (name, data, color?, area?), shape?, splitNumber?, showLegend?, showAxisName?
TxGaugeChartvalue, min?, max?, name?, unit?, precision?, progress?, segments?, color?
TxScatterChartseries (name, data, color?, symbolSize?), xAxisName?, yAxisName?, symbolSize?, showLegend?, grid?, xMin?, xMax?, yMin?, yMax?, zoom?, cooperativeWheel?
TxHeatmapChartvalues, rows, columns, xAxisName?, yAxisName?, visualMap?, min?, max?, showLabel?, cellLabel?, unit?, selectable?, selection? (v-model:selection), labels?
TxTreemapChartdata (name, value?, color?, children?), maxDepth?, showBreadcrumb?, showLabel?, unit?, roam?, cooperativeWheel?

The builders themselves are public too — buildBarChartOption, buildLineChartOption, and the rest return a plain EChartsOption. Use one when a chart has to mix mark types: build the options you want and hand the merged result to TxEChart.

Themed host

TxEChart owns the lifecycle: it resolves the chart tokens for the current theme, applies them, then paints your option over them. The theme sets stateAnimation.duration to 0, so hover emphasis and the dimming of the other series land on the frame the pointer arrives; pass stateAnimation in your option to bring back ECharts' 300ms transition. Sunburst is registered and accepts hierarchical data directly; other ECharts types not registered by the host require their corresponding modules first.

<script setup lang="ts">
import { TxEChart } from '@talex-touch/tuffex/charts'
import type { EChartsOption } from 'echarts'

const option: EChartsOption = {
  tooltip: { trigger: 'item' },
  series: [{
    type: 'sunburst',
    radius: ['20%', '90%'],
    data: [
      { name: '2.5.x', children: [{ name: '2.5.1-beta.2', value: 40 }, { name: '2.5.0', value: 35 }] },
      { name: '2.4.x', children: [{ name: '2.4.13', value: 25 }] },
    ],
  }],
}
</script>

<template>
  <TxEChart :option="option" :height="280" aria-label="Version families and exact versions" />
</template>

Charts

Line chart

TxLineChart draws one or more series over a category axis, with optional area fill, stacking and smooth curves. Multiple series share the axis; the tooltip triggers by axis so every series at the hovered category is listed. zoom (on by default) adds zoom and pan along the categories; Pointer Input has the gestures.

Typed wrapper

TxLineChart is the thin typed wrapper over the same host.

Loading demo...

Bar chart

TxBarChart draws grouped or stacked bars on a category axis, vertical by default. stacked gives every series that declares no stack of its own the shared id total, so stacked and independent series can share one chart; showLabel writes the value on each bar (to its right when horizontal). zoom (on by default) zooms and pans the categories the same way.

Grouped bars

Two series share the category axis; the legend toggles either one.

Loading demo...

Pie chart

Slices of one whole, optionally hollow. donut takes true for a 60% hole or a number for an exact inner-radius percent; centerLabel renders inside a donut only, and labelPosition moves the slice labels outside, inside or into the centre.

Donut

Five slices with the share called out in the hole.

Loading demo...

Funnel chart

Stage-by-stage conversion. sort reorders the stages (descending by default) and labelPosition: 'outside' maps onto ECharts' outer position, so stage names sit beside the funnel instead of inside it. Each label's share is measured against the first element of data, so pass the stages in the order you want them counted.

Signup funnel

Five stages; each label carries its share of the first one.

Loading demo...

Radar chart

Several entities measured on one set of axes. Every entry of indicators becomes a spoke, and each series supplies values positionally, so data[i] belongs to indicators[i]. shape switches the frame between polygon and circle, splitNumber sets the number of rings, and showAxisName: false drops the spoke labels when the surrounding copy already names them.

Capability comparison

Two builds scored on the same five spokes.

Loading demo...

Gauge chart

One reading on a dial — or a thin ring when progress is set. precision controls the decimals in the reading and unit is appended with no separator, so 72 with % renders as 72%. color tints the progress ring and the reading, never the dial, so the axis chrome stays themed.

Dial

A single P95 reading; add `progress` for the thin ring look.

Loading demo...

Scatter chart

Points on a numeric plane, one axis pair per series. symbolSize sets the mark size for the whole chart and a series-level value wins; the optional xMin / xMax / yMin / yMax pin the domain when several charts have to share one scale. zoom (on by default) zooms and pans both axes.

Latency vs throughput

Two clusters on one numeric plane.

Loading demo...

Heatmap chart

A matrix of intensities. Pass values row-major (values[row][column]) with rows and columns naming the two category axes. The builder hands both arrays to ECharts untouched, and ECharts plots the first category at the bottom — so rows[0] is the bottom band, not the top one. The declared visualMap takes the sequential token ramp unless you pass your own inRange.color.

Drag across the plot to select a block of cells. select reports a HeatmapSelection — rows and columns as inclusive index ranges, plus the cells inside — and null once it is cleared; v-model:selection holds the same value. The cells are a snapshot: new values under the same labels keep the block without a new select, while new rows or columns clear it. A drag never fires click; :selectable="false" turns the selection off.

From outside the chart, the exposed clearSelection() clears the block as a click would — announced, and emitted through select — while a value written through v-model:selection (null, or a block from heatmapSelection()) moves the box quietly. cellLabel sets the text showLabel prints in a cell. Instructions and announcements come from labels, merged over HEATMAP_DEFAULT_LABELS: in selected, {count} and {total} count cells, and {first} and {last} name the block's corners as labels.cell puts them ('{column} {row}', with {value} for the printed text).

Activity by hour

Five time buckets across the week; drag across the cells to select a block.

Loading demo...

Treemap chart

Part-to-whole for a hierarchy. Nodes nest through children, a node's color becomes its fill, and showBreadcrumb turns on ECharts' breadcrumb bar for drilling down. maxDepth renders only the first N levels and enables that drill-down; leave it out to draw the whole tree. Without children the same prop draws a flat treemap.

roam is on by default: a drag pans, ⌘ / Ctrl + wheel or a pinch zooms in from the fitted size, and a double-click lays the tiles out afresh. :roam="false" keeps the tiles still and gives touch swipes back to the page.

Nested areas

Two areas, each split into its own sections.

Loading demo...

Pointer Input

Line, bar, scatter and treemap zoom and pan; the heatmap selects. The page keeps its scroll: a plain wheel never zooms.

ChartInputEffect
Line, bar, scatter⌘ / Ctrl + wheel, pinchZooms around the pointer.
Line, bar, scatterDragPans once zoomed in.
Line, bar, scatterDouble-click the plotAnimates back to the full range.
Treemap⌘ / Ctrl + wheel, pinchZooms around the pointer, never below the fitted size.
TreemapDragPans the tiles.
TreemapDouble-clickLays the tiles out afresh.
HeatmapDrag across the plotSelects a block of whole cells and emits select.
HeatmapClick, EscapeClears the selection.

cooperativeWheel (default true) is what keeps a plain wheel scrolling the page. false gives the wheel back to ECharts, which zooms on every wheel turn over the plot and stops the page from scrolling.

A zoomed window stays through a new option, a theme change and redraw(). The exception is a dataZoom entry that sets its own start, end, startValue or endValue: that one opens on the window it names every time.

Compared with the native maps and Sankey:

  • Zoom moves in ECharts' fixed steps (1.1×, 1.2× or 1.4× per event) instead of following the gesture. There are no springs, no release glide and no rubber band: a pan stops where the pointer stops.
  • Resets animate over 350 ms, and jump under prefers-reduced-motion: reduce.
  • There is no keyboard zoom or pan. The heatmap is the only chart with a focus target: a tab stop while a selection exists, so Escape can clear it. Its labels carry the instructions and the announcements: {count} / {total} count cells, {first} / {last} name the block's corners.
  • On touch a pinch zooms. An unzoomed line, bar or scatter chart lets a swipe scroll the page, and once zoomed in a swipe pans. A treemap with roam always keeps the swipe, so leave it a margin of page to scroll from or set :roam="false". A selectable heatmap keeps every swipe too, since a swipe is how a touch selects: set :selectable="false" where the page should scroll through it.
  • A treemap pans without bounds, as ECharts does; double-click brings it back. Heatmap selections snap to whole cells.

Events

EventPayloadDescription
ready(instance: ECharts)The instance exists — imperative handle for anything the option cannot express.
click / dblclick(params: EChartEventParams)Pointer events on series and marks.
mouseover / mouseout(params: EChartEventParams)Hover on series and marks.
legendselectchanged(params: EChartEventParams)A legend entry was toggled.
datazoom(params: EChartEventParams)A dataZoom range changed, the built-in zoom included.
select(selection: HeatmapSelection | null)TxHeatmapChart only: a drag selected a block of cells, or the selection was cleared.
update:selection(selection: HeatmapSelection | null)TxHeatmapChart only: for v-model:selection; fires with select, never for a value the host wrote.

Technologies

  • Component source and option builders: packages/tuffex/packages/components/src/charts/src/echart/src/ (builders in options/).
  • Theme and pointer input: core/theme.ts resolves --tx-chart-* into canvas-ready colors; core/interaction.ts handles the wheel and brushing.
  • Adapted from Cloudflare kumo (https://github.com/cloudflare/kumo), © Cloudflare, Inc., MIT — EChart.tsx.
查看源码
packages/tuffex/packages/components/src/charts/src/echart/index.ts

Use cases

The native family (TxChart, TxTimeseriesChart, TxSankeyChart, TxChoroplethMap, TxSparkChart, TxAllocationBar) stays the default, with TxSparkChart on canvas, TxAllocationBar in the DOM and the rest in SVG: smaller, themeable through CSS tokens, and shaped for what the product actually renders. Reach for TxEChart and its typed wrappers when you need a chart type the native family does not have, or when you want ECharts' own option surface — dataZoom, visualMap, custom series, per-point styling.

Both families read the same colour tokens, so an ECharts chart dropped next to a native one matches it in either theme without a single styling prop.