桑基图 - Kumo

<SankeyChart nodes={nodes} links={links} height={300} />

安装

SankeyChart 需要 echarts 作为 peer dependency。

npm install echarts

桶式导出

import { SankeyChart } from "@cloudflare/kumo";

细粒度导入

import { SankeyChart } from "@cloudflare/kumo/components/chart";

用法

import { SankeyChart, ChartPalette } from "@cloudflare/kumo";
import * as echarts from "echarts/core";
import { SankeyChart as SankeyChartType } from "echarts/charts";
import { TooltipComponent } from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";

// Register required ECharts modules
echarts.use([SankeyChartType, TooltipComponent, CanvasRenderer]);

const nodes = [
  { name: "Users", value: 103600, color: ChartPalette.categorical(0) },
  { name: "Devices", value: 50800, color: ChartPalette.categorical(1) },
  { name: "Apps", value: 122600, color: ChartPalette.categorical(2) },
  { name: "Tunnels", value: 31800, color: ChartPalette.categorical(3) },
];

const links = [
  { source: 0, target: 2, value: 80000 },
  { source: 0, target: 3, value: 23600 },
  { source: 1, target: 2, value: 42600 },
  { source: 1, target: 3, value: 8200 },
];

export default function Example() {
  return <SankeyChart echarts={echarts} nodes={nodes} links={links} height={300} />;
}

示例

基础桑基图

展示源节点与目标节点之间流量的简单桑基图。

<SankeyChart nodes={nodes} links={links} height={300} />

多级流量

桑基图可以展示经过中间节点的多级流量。

<SankeyChart nodes={nodes} links={links} height={350} nodeWidth={20} nodePadding={15} />

全宽布局

使用 left 和 right 控制桑基图在其容器内的水平内边距。将两者都设为 0 可去掉默认的 5% 内边距，铺满整个宽度。

<SankeyChart
  nodes={nodes}
  links={links}
  height={350}
  left={0}
  right={0}
/>

使用 tooltipFormatter 可完全控制 tooltip 内容。

import { SankeyChart, type SankeyTooltipParams } from "@cloudflare/kumo";

const customTooltip = (params: SankeyTooltipParams) => {
  if (params.type === "node" && params.node) {
    return "<strong>" + params.name + "</strong>";
  }
  if (params.type === "link" && params.link) {
    return params.link.source + " → " + params.link.target;
  }
  return "";
};

<SankeyChart 
  nodes={nodes} 
  links={links} 
  tooltipFormatter={customTooltip} 
/>

交互

使用 onNodeClick 与 onLinkClick 处理交互。

<SankeyChart 
  nodes={nodes} 
  links={links} 
  onNodeClick={(node) => console.log(node)}
  onLinkClick={(link) => console.log(link)}
/>

下钻筛选

点击源节点可筛选图表，只显示与其相连的部分。再次点击或使用重置按钮可恢复完整视图。

Click a node to filter

const [selectedSource, setSelectedSource] = useState<string | null>(null);

const handleNodeClick = (node: { name: string }) => {
  if (sourceNames.includes(node.name)) {
    setSelectedSource(prev => prev === node.name ? null : node.name);
  }
};

<SankeyChart
  nodes={filteredNodes}
  links={filteredLinks}
  onNodeClick={handleNodeClick}
/>

内联标签布局

使用 nodeLabelLayout="inline" 可将节点数值与名称显示在同一行。这能避免小节点上的标签重叠，而默认的堆叠布局会导致文字相互碰撞。

<SankeyChart
  echarts={echarts}
  nodes={nodes}
  links={links}
  height={300}
  nodeLabelLayout="inline"
/>

API 参考

Prop	Type	Default	Description
echarts*	`typeof echarts`	-	由使用者导入的 ECharts 核心实例。采用传入而非直接导入的方式，以便使用者控制打包哪些 ECharts 模块（tree-shaking）。
nodes*	`SankeyNodeData[]`	-	桑基图中的节点数组。
links*	`SankeyLinkData[]`	-	按索引连接节点的链接数组。
height	`number`	-	图表高度（像素）
showNodeValues	`boolean`	-	在标签上方显示节点值（默认值：如果任一节点有值则为 true）
nodeLabelLayout	`"stacked" \| "inline"`	-	当 `showNodeValues` 为 true 时节点标签的布局。 - 'stacked'：值在上，名称在下（默认） - 'inline'："值名称" 在同一行（更适合小节点）
formatValue	`(value: number) => string`	-	节点值的格式化函数（默认：toLocaleString）
tooltipFormatter	`(params: SankeyTooltipParams) => string`	-	自定义工具提示格式化函数。返回 HTML 字符串或空字符串以隐藏工具提示。
nodeWidth	`number`	-	-
nodePadding	`number`	-	-
showTooltip	`boolean`	-	-
defaultNodeColor	`string`	-	-
left	`number \| string`	-	Sankey 布局在图表容器内的左内边距。接受数字（像素）或百分比字符串。ECharts 默认值：'5%'。
right	`number \| string`	-	图表容器内 Sankey 布局的右内边距。接受数字（px）或百分比字符串。ECharts 默认值：'5%'。
linkColor	`"gradient" \| "gray"`	-	链接填充样式：'gradient' 混合源到目标的颜色，'gray' 使用纯灰色
linkOpacity	`number`	-	-
className	`string`	-	-
isDarkMode	`boolean`	-	-