组件/Custom Chart 自定义图表

Custom Chart 自定义图表

组合式逃生舱:拼装折线、面积、柱、散点与环形

Verified自 0.1.0

用法

kumo 的逃生舱是把原始 echarts options 透传给低层 Chart;这一职责在这里由 ECharts 图表家族 承担(TxEChart 加类型化封装),本页则是组合逃生舱:TxChart 建立坐标系(测量容器、推导比例尺、分配色板),轴/网格/系列作为子组件挂进它的默认插槽。系列统一 accessor 取数(key 或 (d, i) => v),不给 color 时按挂载顺序取分类色。x/y 值域缺省由所有系列的数据并集推导,xDomain/yDomain 可显式覆盖。

柱线复合

band 轴 + 柱 + 折线

同一坐标系里柱状与折线共存;band 值映射到带中心。

Loading demo...

环形图

TxArcSeries

无轴模式:TxChart 只当尺寸容器,弧形系列自己布局。

Loading demo...

自定义提示框

overlay 插槽 + TxChartTooltip

follow='x' 时提示框垂直位置固定,只横向跟随。

Loading demo...

自定义图层不会自动动画:首绘用 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

属性名类型默认值说明
heightnumber350像素高;设 aspectRatio 时忽略。
aspectRationumber | string—容器宽高比。
widthnumber容器实测显式宽度(SSR/测试用)。
paddingnumber | Partial<ChartPadding>24留给轴与标签的内边距。
xType'linear' | 'log' | 'time' | 'band''linear'x 比例尺类型;log 轴不画 x ≤ 0 的数据。
xDomain / yDomain数组自动并集显式值域。
yNicebooleantruey 值域取整。
ariaDescriptionstring—无障碍名称,缺省用 labels.chart;图表不可聚焦时以 role="img" 朗读。
interactivebooleantrue悬停、按住拖动与方向键读数;false 只留一张静态图,不可聚焦也不读数。
announce(x: string | number) => string按 x 轴刻度格式化键盘读到某个 x 值时播报的文本。
labelsPartial<ChartLabels>英文无障碍名称与按键说明:chart、instructions,会缩放的图表改读 zoomInstructions。

系列 Props(共同)

属性名类型说明
dataT[]数据行。
x / ykeyof T | (d, i) => vaccessor。
colorstring缺省按挂载顺序取分类色。

系列专有 Props

属性名类型默认值说明
curve'linear' | 'monotone' | 'natural' | 'step''linear'TxLineSeries、TxAreaSeries 的曲线插值。
strokeWidthnumber2TxLineSeries、TxAreaSeries 的线宽(像素);面积图设为 0 时隐藏顶线。
showSymbolbooleanfalseTxLineSeries:在每个数据点画圆点。
dashedbooleanfalseTxLineSeries:虚线描边,适合不完整数据。
enter'clip' | 'draw''clip'TxLineSeries 首绘方式:clip 从左到右擦开,draw 沿线描出;虚线始终按 clip。
gradientbooleantrueTxAreaSeries:纵向渐变填充。
fillOpacitynumber0.2TxAreaSeries 在 gradient 关闭时的填充不透明度;TxScatterSeries 的点默认 0.9。
stackstring—TxBarSeries:同一键的序列堆叠,无键的并排。
barWidthnumber—TxBarSeries:显式柱宽(像素),默认由比例尺推导。
radiusnumber0TxBarSeries:柱的圆角半径。
rnumber | accessor3TxScatterSeries:点半径(像素),常量或按数据取值。
valueaccessor—TxArcSeries:决定扇区角度的取值器。
nameaccessor—TxArcSeries:可选名称取值器,出现在扇区事件中。
coloraccessor分类色TxArcSeries:逐扇区颜色。
innerRadiusnumber0.6TxArcSeries:内径占外径的比例,0 为饼图。
padAnglenumber0.015TxArcSeries:扇区之间的角度间隙(弧度)。
cornerRadiusnumber2TxArcSeries:扇区圆角(像素)。
announce(slice) => stringname: valueTxArcSeries:键盘读数的播报文案。

TxArcSeries 的事件:slice-click 点击扇区;slice-hover 指针进入扇区时发出扇区数据,离开弧形时为 null。无轴弧形没有坐标系可读,#overlay 里的 <TxChartTooltip> 靠它取数。弧形按住拖动时像转盘一样按角度逐片读数,松手不触发 slice-click;聚焦后 ← / → 逐片读数、Home / End 跳到首尾、Escape 清除。

TxChartTooltip Props

属性名类型默认值说明
openboolean | 'auto''auto''auto' 指针在图内即显示;布尔为受控。
follow'both' | 'x''both'x 固定垂直位置。
offsetnumber12指针与提示框间距。
fixedYnumber0follow 为 x 时的顶部位置(像素)。
footerstring—行列表下方追加的一行文本(对应 kumo 的 tooltipFooter)。
boundary'clipping-ancestors' | Element | Element[]'clipping-ancestors'碰撞边界(对应 ECharts confine):默认沿裁剪祖先与视口求交后翻转。
title / rows / hiddenCount——默认内容;插槽整体替换。
moreLabel(count: number) => string+N morehiddenCount 折叠行的页脚文案。

提示框的节奏同样对齐 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 暴露读取比例尺。