Charts 图表
图表家族:原生 SVG 与按需加载的 ECharts
安装
图表家族与主包同源,走独立子路径 @talex-touch/tuffex/charts,API 面对标 Cloudflare kumo 的 Charts 族,但原生图表的渲染层是 Vue 直出的 SVG,不依赖 echarts,也不依赖任何整图表框架,数学只用可摇树的 d3 微模块(d3-scale / d3-shape / d3-sankey / d3-geo)。本族没覆盖的图表类型、以及想直接用 ECharts 配置面时,用 ECharts 图表家族:它读同一套颜色 token,以可选 echarts peer 的形式提供。
pnpm add @talex-touch/tuffex
import { TxTimeseriesChart } from '@talex-touch/tuffex/charts'
import '@talex-touch/tuffex/charts/style.css'
用法
图表沿用 ECharts 的默认时序:首绘入场 1000ms cubicInOut,数据更新几何形变 500ms cubicInOut;单个序列超过 2000 个点时跳过动画、直接渲染终态。折线/面积的首绘是例外——按 ECharts 折线序列的默认值走 linear,从左到右裁剪揭示。悬停高亮不照搬 ECharts 的 300ms cubicOut:其余序列变淡、换色这类变化在指针到达的那一帧完成,这是 TuffEx 的悬停规则;只有几何上的强调(扇区外移、地图气泡放大)仍按 300ms cubicOut 过渡。
最佳实践
- 常见指标场景优先使用专用图表封装(
TxTimeseriesChart、TxBubbleMap、TxChoroplethMap、TxSankeyChart、TxSparkChart或TxEChart),避免过早从零手拼基础序列原语。 - 样式取色统一通过
--tx-chart-*CSS 变量跟随宿主自适应主题,切忌硬编码固定十六进制颜色或手动维护暗色判断分支。 - 单张图表序列数量建议控制在 3–7 条以内以保持良好可读性,并始终为每条序列提供明确图例或完整 Tooltip 说明。
API 参考
ChartLegendItem Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
variant | 'small' | 'large' | 'small' | 单行,或可并排进仪表指标带的堆叠大数值。 |
name | string | — | 序列名。loading 时可省略。 |
color | string | — | 色点颜色,接受任意 CSS 颜色(含 var())。 |
value | string | — | 已格式化的数值文本。 |
unit | string | — | 数值后的单位(仅 large)。 |
inactive | boolean | false | 半透明表示被反选。 |
loading | boolean | false | 渲染骨架占位(aria-hidden,不可聚焦)。 |
可用图表
| 组件 | 板块 | 说明 |
|---|---|---|
TxTimeseriesChart | Timeseries | 时序折线/堆叠柱,标记、阈值、缩放与刷选、tooltip 全家桶。 |
TxLearningCurve | LearningCurve | 训练曲线:多种子均值与区间、EMA 平滑、缩放与实时增长。 |
TxBubbleMap / TxChoroplethMap | Maps | GeoJSON 地图:气泡与分级填色。 |
TxSankeyChart | Sankey | 桑基流向图。 |
TxChart + 系列原语 | Custom Chart | 组合式逃生舱:折线/面积/柱/散点/环形自由拼装。 |
TxMonoChart | MonoChart | 30 种单色图表变体与活动日历。 |
TxDitherChart | DitherChart | 抖动质感的展示型图表,文档归在动效套件。 |
TxEChart + 九个预设 | ECharts | 其余图表类型;挂载时按需加载可选 peer echarts。 |
ChartPalette / CSS 变量 | Colors | 分类、语义、顺序、地图色板,明暗自动。 |
图例
TxChartLegendItem 提供两种图例项版式:small 单行(多序列图例),large 堆叠大数值——多个 large 并排即组成仪表卡的指标带。loading 渲染骨架占位;挂了 click 监听时它会渲染成原生 button,回车/空格开箱可用。
图例项
small 单行 / 加载态
点击第一项切换第二项的 inactive 态。
仪表指标带
四个 large 图例项并排就是仪表卡的指标带:上方是色点加名称,下方是数值与单位,列与列之间用发丝线分隔,整条指标带铺满卡片宽度。它下面可以接任意图表——这里是四序列 TxTimeseriesChart,悬停即可读出同一时间戳上的四个百分位。
仪表卡中的 large 指标行
把鼠标移到图表上:tooltip 会列出该时间戳下全部百分位。
与 kumo 的差异
- 没有
echarts实例 prop——渲染层自研,调用方不需要也不能传 echarts。 - 没有
isDarkModeprop——取色全部走--tx-chart-*CSS 变量,跟随宿主.dark/[data-theme='dark']自动切换。 - 所有 HTML 字符串 formatter 一律改为插槽(VNode),不存在 XSS 转义面。
概述
- 这些默认值抄自 kumo 锁定的
echarts ^6.0.0(src/model/globalDefault.ts,折线序列与 tooltip 另有各自的默认值)。 - 本包没有 ECharts 运行时,于是把它们固化成导出常量:
ENTER_DURATION(1000)、UPDATE_DURATION(500)、STATE_DURATION(300)、ANIMATION_THRESHOLD(2000)。 - 宿主声明
prefers-reduced-motion: reduce时所有动画直接落到终帧,CSS 过渡也整体包在@media (prefers-reduced-motion: no-preference)内。 - 各图表自己的入场与交互形态写在对应的图表页(Timeseries、Maps、Sankey、Custom Chart),这里不重复。