---
title: "Custom Chart 自定义图表"
description: "组合式逃生舱：拼装折线、面积、柱、散点与环形"
category: Charts
status: beta
since: 0.1.0
tags: [chart, custom, composable, primitives]
syncStatus: reviewed
verified: true
---

## 用法

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

### 柱线复合

:::TuffDemoWrapper{demo="CustomChartComposedDemo" code-lang="vue" title="band 轴 + 柱 + 折线" description="同一坐标系里柱状与折线共存；band 值映射到带中心。"}
---
code: |
  <template>
    <TxChart x-type="band" :height="280" :padding="{ top: 24, right: 24, bottom: 36, left: 56 }">
      <TxChartGrid y />
      <TxAxis position="bottom" />
      <TxAxis position="left" :format="(v) => `${v}k`" />
      <TxBarSeries :data="rows" x="month" y="revenue" :radius="3" />
      <TxLineSeries :data="rows" x="month" y="growth" curve="monotone" show-symbol />
    </TxChart>
  </template>
---
:::

### 环形图

:::TuffDemoWrapper{demo="CustomChartDonutDemo" code-lang="vue" title="TxArcSeries" description="无轴模式：TxChart 只当尺寸容器，弧形系列自己布局。"}
---
code: |
  <template>
    <TxChart :height="260" :padding="8">
      <TxArcSeries :data="data" value="count" name="label" :inner-radius="0.65" @slice-click="onSlice" />
    </TxChart>
  </template>
---
:::

### 自定义提示框

:::TuffDemoWrapper{demo="CustomChartTooltipDemo" code-lang="vue" title="overlay 插槽 + TxChartTooltip" description="follow='x' 时提示框垂直位置固定，只横向跟随。"}
---
code: |
  <template>
    <TxChart :height="260">
      <TxScatterSeries :data="points" x="x" y="y" :r="(d) => d.size" />
      <template #overlay>
        <TxChartTooltip follow="x" :fixed-y="8">
          <template #default="{ pointerX }">
            <span>cursor at {{ Math.round(pointerX) }}px</span>
          </template>
        </TxChartTooltip>
      </template>
    </TxChart>
  </template>
---
:::

自定义图层不会自动动画：首绘用 `useEnterProgress()`，数据更新用 `useTweenedNumbers()`，时长与阈值沿用导出常量，减弱动效下直接落到终帧。

```vue
<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` 暴露读取比例尺。
