桑基图 - 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`	-	The ECharts core instance imported by the consumer. Passed in rather than imported directly so the consumer controls which ECharts modules are bundled (tree-shaking).
nodes*	`SankeyNodeData[]`	-	Array of nodes in the Sankey diagram
links*	`SankeyLinkData[]`	-	Array of links connecting nodes by index
height	`number`	-	Height of the chart in pixels
showNodeValues	`boolean`	-	Show node values above labels (default: true if any node has a value)
nodeLabelLayout	`"stacked" \| "inline"`	-	Layout for node labels when showNodeValues is true. - 'stacked': value on top, name below (default) - 'inline': "value name" on a single line (better for small nodes)
formatValue	`(value: number) => string`	-	Format function for node values (default: toLocaleString)
tooltipFormatter	`(params: SankeyTooltipParams) => string`	-	Custom tooltip formatter. Return HTML string or empty string to hide tooltip.
nodeWidth	`number`	-	-
nodePadding	`number`	-	-
showTooltip	`boolean`	-	-
defaultNodeColor	`string`	-	-
left	`number \| string`	-	Left padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'.
right	`number \| string`	-	Right padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'.
linkColor	`"gradient" \| "gray"`	-	Link fill style: 'gradient' blends source to target colors, 'gray' uses flat gray
linkOpacity	`number`	-	-
className	`string`	-	-
isDarkMode	`boolean`	-	-