ECharts 图表家族

安装

echarts 是可选 peer 依赖：宿主装了它，这一族就点亮；不装，Tuffex 其它部分毫无变化。它永远不会被打进主包——组件在挂载时动态引入，因此第一次渲染才单独出一块 chunk。

pnpm add echarts @talex-touch/tuffex

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

用法

最佳实践

• 给宿主一个确定的高度。高度为 0 的容器画不出任何东西。
• 优先用类型化封装；旭日图可直接给 TxEChart 传 type: 'sunburst' 的分层 data，运行时已注册该类型。其它长尾类型须先通过 loadECharts() 取得运行时并注册对应的 ECharts 模块。
• 传 aria-label：它让 canvas 图表对辅助技术可读。
• 传数据而不是像素：封装负责把数据映射成 option，主题色与坐标轴质感才能保持一致。
• 在宿主应用里安装 echarts；缺少 peer 时容器内会给出提示，而不是静默空白。

API 参考

这一族每张图都接受下列公共 props，外加各自的data props，并且都转发一份原始 option 覆盖在生成的 option 之上——series 数组整体替换，其余键深度合并。

update 只存在于 TxEChart：'replace'（默认）整体替换series数组，被移除的series立即停止绘制；'merge' 保留 ECharts 自身的合并语义。

Per-chart props

构造器本身也是公开 API——buildBarChartOption、buildLineChartOption 等都返回一份普通 EChartsOption。需要在一张图里混用图形类型时，用它们先各自生成再合并，然后把结果交给 TxEChart。

主题化宿主

TxEChart 负责整个生命周期：解析当前主题的图表 token、应用主题、再把你的 option 画上去。旭日图已注册，可直接传入分层数据；未内置注册的其它 ECharts 类型需要先注册对应模块。

<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="版本系列与具体版本分布" />
</template>

图表

折线图

TxLineChart 在类目轴上绘制一条或多条series，可选面积填充、堆叠与平滑曲线。多条series共用同一坐标轴；tooltip 按轴触发，所以悬停类目下的每条series都会列出。

柱状图

TxBarChart 在类目轴上绘制分组或堆叠柱，默认纵向。stacked 会给未自带 stack 的每条series都挂上共享 id total，于是堆叠与独立series可以共存于一张图；showLabel 把数值写在柱上（horizontal 时写在右侧）。

饼图

整体的切片，可选择中空。donut 传 true 用 60% 内径，传数字则精确指定内径百分比；centerLabel 只在环形图里渲染，labelPosition 把切片标签放到外侧、内侧或中心。

漏斗图

逐级转化。sort 重排阶段（默认 descending）；labelPosition: 'outside' 映射到 ECharts 的 outer 位置，于是阶段名落在漏斗旁边而不是内部。每个标签的转化率以 data 的第一个元素为基数，所以请按希望被统计的顺序传入阶段。

雷达图

在同一组坐标轴上比较多个对象。indicators 的每一项是一根轴，每条series按位置给数值：data[i] 对应 indicators[i]。shape 在 polygon 与 circle 之间切换外框，splitNumber 设置环数，showAxisName: false 在周边文案已点明时去掉轴名。

仪表盘

一个读数画在表盘上；传 progress 则变成细圆环。precision 控制读数位数，unit 直接拼接且不加分隔符（72 加 % 显示为 72%）。color 只染进度环与读数、不染表盘，所以刻度质感仍由主题决定。

散点图

数值平面上的点，每条series一对坐标轴。symbolSize 设置整图点径，series 级的值优先；需要多张图共用同一量纲时，用 xMin / xMax / yMin / yMax 固定值域。

热力图

强度矩阵。values 按行主序传入（values[row][column]），rows 与 columns 命名两个类目轴。构造器把这两个数组原样交给 ECharts，而 ECharts 把第一个类目画在底部——所以 rows[0] 是最下面那一行。声明的 visualMap 默认读顺序色板的 token 渐变，除非你自己传 inRange.color。

矩形树图

面向层级的占比图。节点通过 children 嵌套，节点的 color 就是它的填充色，showBreadcrumb 打开 ECharts 的面包屑下钻条；maxDepth 只画前 N 层并开启该下钻，不传则整棵树一次画完。不传 children 时同一个 prop 画出扁平矩形树。

Events

技术实现

• 组件源码：packages/tuffex/packages/components/src/charts/src/echart/src/。
• option 构造器：packages/tuffex/packages/components/src/charts/src/echart/src/options/。
• 主题与 token：packages/tuffex/packages/components/src/charts/src/echart/src/core/theme.ts。
• 改编自 Cloudflare kumo (https://github.com/cloudflare/kumo)，© Cloudflare, Inc.，MIT —— EChart.tsx。

使用场景

原生 SVG 家族（TxChart、TxTimeseriesChart、TxSankeyChart、TxChoroplethMap、TxSparkChart、TxAllocationBar）仍是默认选择：体积更小、走 CSS token 主题化、形状贴合产品真实要画的东西。当你需要原生家族没有的图表类型，或者想直接用 ECharts 自己的配置面——dataZoom、visualMap、自定义 series、逐点样式——就用 TxEChart 及其类型化封装。

两族读同一套颜色 token，所以把 ECharts 图放在原生图旁边，两种主题下都自动对齐，一个样式 prop 都不用传。