Custom Chart 自定义图表
组合式逃生舱:拼装折线、面积、柱、散点与环形
用法
kumo 的逃生舱是把原始 echarts options 透传给低层 Chart;这一职责在这里由 ECharts 图表家族 承担(TxEChart 加类型化封装),本页则是组合逃生舱:TxChart 建立坐标系(测量容器、推导比例尺、分配色板),轴/网格/系列作为子组件挂进它的默认插槽。系列统一 accessor 取数(key 或 (d, i) => v),不给 color 时按挂载顺序取分类色。x/y 值域缺省由所有系列的数据并集推导,xDomain/yDomain 可显式覆盖。
柱线复合
band 轴 + 柱 + 折线
同一坐标系里柱状与折线共存;band 值映射到带中心。
环形图
TxArcSeries
无轴模式:TxChart 只当尺寸容器,弧形系列自己布局。
自定义提示框
overlay 插槽 + TxChartTooltip
follow='x' 时提示框垂直位置固定,只横向跟随。
自定义图层不会自动动画:首绘用 useEnterProgress(),数据更新用 useTweenedNumbers(),时长与阈值沿用导出常量,减弱动效下直接落到终帧。
<script setup lang="ts">
import { ANIMATION_THRESHOLD, ENTER_DURATION, easings, useChartContext, useEnterProgress } from '@talex-touch/tuffex/charts'
import { computed } from 'vue'
const props = defineProps<{ pointCount: number }>()
const ctx = useChartContext('MyLayer')
const plot = computed(() => ctx.plot.value)
// 0 → 1 的入场进度;超阈值或 reduced-motion 时直接停在 1
const enter = useEnterProgress({
duration: ENTER_DURATION,
easing: easings.linear,
enabled: () => props.pointCount <= ANIMATION_THRESHOLD,
})
const enterWidth = computed(() => plot.value.width * enter.value)
</script>
<template>
<defs>
<clipPath id="my-layer-enter">
<rect :x="plot.x" :y="plot.y" :width="enterWidth" :height="plot.height" />
</clipPath>
</defs>
<g :clip-path="'url(#my-layer-enter)'">
<slot />
</g>
</template>
API 参考
Chart Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
height | number | 350 | 像素高;设 aspectRatio 时忽略。 |
aspectRatio | number | string | — | 容器宽高比。 |
width | number | 容器实测 | 显式宽度(SSR/测试用)。 |
padding | number | Partial<ChartPadding> | 24 | 留给轴与标签的内边距。 |
xType | 'linear' | 'log' | 'time' | 'band' | 'linear' | x 比例尺类型;log 轴不画 x ≤ 0 的数据。 |
xDomain / yDomain | 数组 | 自动并集 | 显式值域。 |
yNice | boolean | true | y 值域取整。 |
ariaDescription | string | — | 无障碍名称,缺省用 labels.chart;图表不可聚焦时以 role="img" 朗读。 |
interactive | boolean | true | 悬停、按住拖动与方向键读数;false 只留一张静态图,不可聚焦也不读数。 |
announce | (x: string | number) => string | 按 x 轴刻度格式化 | 键盘读到某个 x 值时播报的文本。 |
labels | Partial<ChartLabels> | 英文 | 无障碍名称与按键说明:chart、instructions,会缩放的图表改读 zoomInstructions。 |
系列 Props(共同)
| 属性名 | 类型 | 说明 |
|---|---|---|
data | T[] | 数据行。 |
x / y | keyof T | (d, i) => v | accessor。 |
color | string | 缺省按挂载顺序取分类色。 |
系列专有 Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
curve | 'linear' | 'monotone' | 'natural' | 'step' | 'linear' | TxLineSeries、TxAreaSeries 的曲线插值。 |
strokeWidth | number | 2 | TxLineSeries、TxAreaSeries 的线宽(像素);面积图设为 0 时隐藏顶线。 |
showSymbol | boolean | false | TxLineSeries:在每个数据点画圆点。 |
dashed | boolean | false | TxLineSeries:虚线描边,适合不完整数据。 |
enter | 'clip' | 'draw' | 'clip' | TxLineSeries 首绘方式:clip 从左到右擦开,draw 沿线描出;虚线始终按 clip。 |
gradient | boolean | true | TxAreaSeries:纵向渐变填充。 |
fillOpacity | number | 0.2 | TxAreaSeries 在 gradient 关闭时的填充不透明度;TxScatterSeries 的点默认 0.9。 |
stack | string | — | TxBarSeries:同一键的序列堆叠,无键的并排。 |
barWidth | number | — | TxBarSeries:显式柱宽(像素),默认由比例尺推导。 |
radius | number | 0 | TxBarSeries:柱的圆角半径。 |
r | number | accessor | 3 | TxScatterSeries:点半径(像素),常量或按数据取值。 |
value | accessor | — | TxArcSeries:决定扇区角度的取值器。 |
name | accessor | — | TxArcSeries:可选名称取值器,出现在扇区事件中。 |
color | accessor | 分类色 | TxArcSeries:逐扇区颜色。 |
innerRadius | number | 0.6 | TxArcSeries:内径占外径的比例,0 为饼图。 |
padAngle | number | 0.015 | TxArcSeries:扇区之间的角度间隙(弧度)。 |
cornerRadius | number | 2 | TxArcSeries:扇区圆角(像素)。 |
announce | (slice) => string | name: value | TxArcSeries:键盘读数的播报文案。 |
TxArcSeries 的事件:slice-click 点击扇区;slice-hover 指针进入扇区时发出扇区数据,离开弧形时为 null。无轴弧形没有坐标系可读,#overlay 里的 <TxChartTooltip> 靠它取数。弧形按住拖动时像转盘一样按角度逐片读数,松手不触发 slice-click;聚焦后 ← / → 逐片读数、Home / End 跳到首尾、Escape 清除。
TxChartTooltip Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
open | boolean | 'auto' | 'auto' | 'auto' 指针在图内即显示;布尔为受控。 |
follow | 'both' | 'x' | 'both' | x 固定垂直位置。 |
offset | number | 12 | 指针与提示框间距。 |
fixedY | number | 0 | follow 为 x 时的顶部位置(像素)。 |
footer | string | — | 行列表下方追加的一行文本(对应 kumo 的 tooltipFooter)。 |
boundary | 'clipping-ancestors' | Element | Element[] | 'clipping-ancestors' | 碰撞边界(对应 ECharts confine):默认沿裁剪祖先与视口求交后翻转。 |
title / rows / hiddenCount | — | — | 默认内容;插槽整体替换。 |
moreLabel | (count: number) => string | +N more | hiddenCount 折叠行的页脚文案。 |
提示框的节奏同样对齐 ECharts:hideDelay 100ms 之后才开始 200ms 淡出并移除 DOM,指针短暂划出图表不会闪断;位移交给 transform: translate3d() 的 400ms 过渡由浏览器补间;指针追踪按 50ms 节流(首次与最后一次各补一次采样)。
读数
TxChart 自带读数,自定义图层只需读 pointer:
- 鼠标悬停把读数放在指针处;按住拖动(鼠标、触屏、触控笔)超过 4px 后持续读数,拖出绘图区时停在边缘。拖动松手产生的点击会被吞掉,不会落到图表或外层元素上。
- 触屏单指按下即读数;图表设了
touch-action: pan-y,纵向滑动仍滚动页面。 - 聚焦图表后 ← / → 按 x 逐个数据点读数,Home / End 跳到首尾,Escape 清除;读数写进礼貌的 live region,
announce可改文案。 useChartContext().pointer的x/y是容器像素坐标,inside表示正在显示读数,pressed表示正在按住拖动,source为'keyboard'时读数来自按键:落在数据点的 x、绘图区垂直居中,没有指针高度。nearestXStop(px)返回离某个像素最近的数据 x,十字线据此吸附到数据上;registerKeyLayer({ key, clear })注册的按键层先于逐点读数收到按键,返回true即已处理,TxArcSeries的逐片读数就是这样接入的。
组合规则
- 系列/轴/网格必须是
<TxChart>的子孙——它们通过注入的图表上下文拿比例尺,游离使用会抛错。 - 多个
TxBarSeries:无stack并排分道,同stack键堆叠;y 值域自动覆盖堆叠总量。 TxArcSeries不依赖坐标系,可与无轴TxChart单独使用。#overlay插槽是 SVG 之上的 DOM 层(pointer-events: none),放提示框与标注。- 深度定制可
useChartContext()自写图层,或从TxChart实例的context暴露读取比例尺。