---
title: "SankeyChart 桑基图"
description: "d3-sankey 流向图，渐变连线与节点拖动"
category: Charts
status: beta
since: 0.1.0
tags: [chart, sankey, flow, d3-sankey]
syncStatus: reviewed
verified: true
---

## 用法

`nodes` 是节点数组，`links` 用**节点下标**连接（`source`/`target` 是 `nodes` 的索引）。节点色优先级：`node.color` > `defaultNodeColor` > 分类色板按下标轮转。连线默认按来源色→目标色渐变，`link-color="gray"` 换成整齐的灰。任一节点带 `value` 时值标签自动开启（`showNodeValues` 可强制开关）。

### 流量分发

:::TuffDemoWrapper{demo="SankeyChartBasicDemo" code-lang="vue" title="渐变连线 + tooltip" description="悬停可见 value 与 tooltipData 行；拖动节点可移动它，带 isDrillable 的连线是 pointer 光标。"}
---
code: |
  <script setup lang="ts">
  const nodes = [
    { name: 'Organic', value: 5200 },
    { name: 'Referral', value: 2100 },
    { name: 'Ads', value: 1400 },
    { name: 'Landing', value: 8700, tooltipData: { Sessions: 8700, 'Bounce rate': '34%' } },
    { name: 'Signup', value: 2600, isDrillable: true, childCount: 4 },
    { name: 'Docs', value: 3100 },
    { name: 'Bounce', value: 3000 },
  ]
  const links = [
    { source: 0, target: 3, value: 5200 },
    { source: 1, target: 3, value: 2100 },
    { source: 2, target: 3, value: 1400 },
    { source: 3, target: 4, value: 2600, isDrillable: true },
    { source: 3, target: 5, value: 3100 },
    { source: 3, target: 6, value: 3000 },
  ]
  </script>

  <template>
    <TxSankeyChart :nodes="nodes" :links="links" @node-click="onNode" @link-click="onLink" />
  </template>
---
:::

### 行内标签与灰连线

:::TuffDemoWrapper{demo="SankeyChartLabelsDemo" code-lang="vue" title="inline 标签 + gray 连线" description="小节点用行内「值 名称」排布更紧凑。"}
---
code: |
  <template>
    <TxSankeyChart
      :nodes="nodes"
      :links="links"
      node-label-layout="inline"
      link-color="gray"
      :format-value="(v) => `${(v / 1000).toFixed(1)}k`"
    />
  </template>
---
:::

## API 参考

### SankeyChart Props

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `nodes` | `SankeyNodeData[]` | — | `{ name, color?, value?, tooltipData?, isDrillable?, childCount? }`。 |
| `links` | `SankeyLinkData[]` | — | `{ source, target, value, isDrillable? }`，下标引用节点。 |
| `height` | `number` | `400` | 像素高度。 |
| `width` | `number` | 容器实测 | 显式宽度（SSR/测试用）。 |
| `nodeWidth` | `number` | `8` | 节点条宽。 |
| `nodePadding` | `number` | `10` | 同列节点垂直间距。 |
| `showNodeValues` | `boolean \| 'auto'` | `'auto'` | `'auto'` 在任一节点有 `value` 时开启。 |
| `nodeLabelLayout` | `'stacked' \| 'inline'` | `'stacked'` | 值在名称上方 / 同行。 |
| `formatValue` | `(v: number) => string` | `toLocaleString` | 值格式化。 |
| `showTooltip` | `boolean` | `true` | 悬停提示框。 |
| `defaultNodeColor` | `string` | — | 分类色板前的兜底色。 |
| `left` | `number \| string` | `'5%'` | 左侧布局留白（px 或百分比）。 |
| `right` | `number \| string` | `'5%'` | 右侧布局留白（px 或百分比）。 |
| `linkColor` | `'gradient' \| 'gray'` | `'gradient'` | 连线填充模式。 |
| `linkOpacity` | `number` | `0.5` | 渐变连线不透明度。 |
| `labels` | `Partial<SankeyLabels>` | 英文 | `{ instructions, value, items }`：`instructions` 在每个节点名称之后朗读；`value` 是提示框里数值行的名称，`items` 是可下钻节点的条目数。 |

### SankeyChart Events

| 事件名 | 回调参数 | 说明 |
|------|------|------|
| `node-click` | `(node: SankeyNodeData)` | 点击节点，回传原始数据。 |
| `link-click` | `(link: SankeyLinkData)` | 点击连线，回传原始数据。 |

### SankeyChart Slots

| 插槽名 | 作用域参数 | 说明 |
|------|------|------|
| `tooltip` | `{ params: SankeyTooltipParams }` | 整体替换提示框内容；`params.type` 为 `'node' \| 'link'`。 |

## 拖动节点

节点只做垂直移动，仍留在自己的列里，连线实时重排。

| 输入 | 效果 |
|------|------|
| 拖动节点 | 从抓取点起 1:1 跟随指针，限制在图表高度之内。超过 4 px 后不会触发 `node-click`。 |
| 松手 | 节点留在放下的位置。 |
| 拖动中按 `Escape` | 取消；节点弹回拾起时的位置。 |
| 双击空白背景 | 所有节点弹回计算出的布局。 |
| 聚焦节点时 `Alt` + `↑` / `↓` | 移动 8 px。 |
| 聚焦节点时 `Enter` / `Space` | 选中（`node-click`）。 |

节点可聚焦（`role="button"`，以节点名命名），名称之后朗读 `labels.instructions`，它合并到 `SANKEY_DEFAULT_LABELS` 之上。从节点开始的触摸拖动移动节点而不是滚动页面；从连线或背景开始的触摸仍然滚动。`nodes`（名称、数值）、`links`（端点、数值）或 `height` 的内容变化会回到计算出的布局并丢弃所有移动；内容相同的新数组会保留它们。`prefers-reduced-motion: reduce` 下弹簧直接落到终点；被拖动的节点仍跟随指针。

## 容错

环形连接会让 d3-sankey 抛错——组件捕获后渲染空态并在控制台给出 dev 警告，不会拖垮宿主页面。

## 悬停高亮

悬停节点或连线时，只有邻接元素保持原样：节点、连线与标签里不相邻的部分一起降到 10% 不透明度，对应 ECharts 的 `emphasis.focus: 'adjacency'`（blur 取 `fromState.opacity * 0.1`），在指针到达的那一帧切换，不走 ECharts 的 300ms `cubicOut`（TuffEx 的悬停规则）。节点的邻域是它自己、所有与它相连的连线和这些连线另一端的节点；连线的邻域是它自己、两端节点以及触及任一端点的所有连线。

桑基图在数据变化时**没有几何动画**，这一点与 kumo 一致而非缺失：ECharts 的 `SankeyView` 既没有 `initProps` 也没有 `updateProps`，所以 d3-sankey 布局变化时节点与连线直接落到新位置，不做补间。只有拖动自带的弹簧（Escape、复位）会运动。`prefers-reduced-motion: reduce` 下 300ms 过渡被去掉，高亮瞬时切换。

## 与 kumo 的差异

- `tooltipFormatter`（HTML 字符串 + 手工 XSS 转义）→ `tooltip` 插槽（VNode）。
- kumo 的节点是固定的；这里的节点可以拖动、用 `Alt` + 方向键微调并复位。
- kumo 遇环形输入直接抛错；这里降级为空渲染 + dev 警告。
