API Sankey

Các luồng giữa các nút được bố trí theo cột, với độ dày dải tỷ lệ với giá trị luồng (xây dựng trên d3-sankey) - xem bản demo Sankey.

Import

import "@michi-vz/wc/sankey-chart";
// <michi-vz-sankey-chart> is now defined

import { mountSankeyChart } from "@michi-vz/core";

const chart = mountSankeyChart(el, props);

import { SankeyChart } from "@michi-vz/react/sankey-chart";

import { SankeyChart } from "@michi-vz/vue/sankey-chart";

import { sankeyChart } from "@michi-vz/svelte/sankey-chart";

import { bindChart, applySankeyChartProps } from "@michi-vz/angular/sankey-chart";
// needs CUSTOM_ELEMENTS_SCHEMA on the component that hosts <michi-vz-sankey-chart>

Props

Prop	Type	Default	Description
`timeline`	`boolean \| TimelinePeriodConfig`	-	Opt-in "play through years": snapshots one period at a time over the period tags in the data, with a headless controller (`chart.timeline()`) plus the built-in play button + scrubber. Values tween between periods unless `interpolate: false`. Off by default; wins over `progressiveDraw` when both are set.
`progressiveDraw`	`boolean \| ProgressiveDrawConfig`	-	Opt-in reveal animation: wipes the marks in left to right on mount (a clip reveal; axes and titles stay put). `true` uses defaults (1200 ms, easeInOutCubic); a config tunes durationMs, easing, autoplay, and replayOnUpdate (`tipLabel` is LineChart-only and ignored here). Off by default; respects prefers-reduced-motion (renders fully drawn instantly) and `replay()` re-runs it.
`nodes`*	`SankeyNodeItem[]`	-	Flow nodes; each needs a unique id that links reference
`links`*	`SankeyLinkItem[]`	-	Directed flows between nodes (source -> target); band thickness is proportional to value
`title`	`string`	-	Optional chart title rendered above the plot
`nodeWidth`	`number`	`18`	Node rect width in px (default 18).
`nodePadding`	`number`	`12`	Vertical gap between nodes in a column in px (default 12).
`nodeRadius`	`number`	`2`	Corner radius of the node rects in px (default 2; 0 = square corners). Clamped to half the node's shorter side.
`linkRadius`	`number`	`2`	Corner radius (px) of the filled flow ribbons where they meet the nodes (default 2; 0 = sharp corners). Clamped to half the band's thickness.
`linkColorMode`	`"source" \| "target"`	`"source"`	Colour links by their "source" (default) or "target" node.
`linkOpacity`	`number`	`0.45`	Link opacity in [0,1] (default 0.45).
`showLabels`	`boolean`	`true`	Draw node labels (default true).
`hoverHighlight`	`boolean`	`false`	Built-in hover emphasis, default false: hovering a NODE keeps it, every flow into or out of it and the nodes at those flows' other ends at full strength, hovering a FLOW keeps only that flow and its two end nodes, and everything else dims to the `highlightItems` levels (flows at linkOpacity x 0.25, nodes at 0.25). Applied in place (svg updates opacity on the existing marks and fades per `enableTransitions`; canvas/webgpu repaint), so hovering never re-renders the chart and consumers need not mirror `onHighlightItem` into `highlightItems`. While hovering it wins over `highlightItems`; leaving restores that state. A pinned (clicked) tooltip keeps its emphasis until unpinned. `onHighlightItem` fires exactly as without it.
`nodeSort`	`"auto" \| "input"`	`"auto"`	Vertical order of the nodes inside a column (default "auto"): "auto" lets d3-sankey arrange them to reduce crossings, "input" keeps the order of the `nodes` array (and the order of `links` for the bands leaving a node), so a "Rest of ..." or "Others" node stays where you listed it, typically last.
`minLinkValue`	`number`	-	Floor for the band thickness, in value units (default none): a link whose value is below it is LAID OUT as if it had this value, so a trickle next to a big flow still has a band wide enough to hover. Only the geometry changes; the tooltip, `valueFormatter`, the context and the totals keep the real values. Pick it from your data, e.g. 15% of the largest link.
`isLoading`	`boolean`	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
`isNodata`	`boolean \| ((dataSet: SankeyNodeItem[] \| null \| undefined) => boolean)`	-	No-data override: boolean, or a predicate on nodes; default = empty nodes.
`noDataLabel`	`string`	-	Text for the vanilla default no-data overlay (ignored when suppressed).
`suppressDefaultOverlay`	`boolean`	-	A framework wrapper sets this to render its OWN loading/no-data node instead.
`valueFormatter`	`(n: number) => string`	-	Formats a numeric value for labels and tooltips
`tooltipFormatter`	`(mark: SankeyNodeContext \| SankeyLinkContext) => string`	-	Returns custom tooltip HTML for a hovered datum/mark (sanitized before it is inserted)
`onNodeClick`	`(node: SankeyNodeContext, event: MouseEvent) => void`	-	Called when a node is clicked (svg marks and the canvas/webgpu hit-test alike), with the same node context the tooltip formatter receives and the mouse event. The click still pins the tooltip as before; use this to navigate or select from the mark itself instead of a link inside the pinned tooltip.
`onLinkClick`	`(link: SankeyLinkContext, event: MouseEvent) => void`	-	Called when a flow band is clicked, with its link context and the mouse event (same pinning behaviour as `onNodeClick`).
`onHighlightItem`	`(labels: string[]) => void`	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
`width`	`number`	`800`	Chart width in pixels
`height`	`number`	`500`	Chart height in pixels
`margin`	`Margin`	`{ top: 36, right: 12, bottom: 12, left: 12 }`	Inner margins (top/right/bottom/left, in px); default 8 (36 top with a title)
`colors`	`string[]`	-	Categorical palette for rings without an explicit colour or colorsMapping entry
`colorsMapping`	`Record<string, string>`	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
`highlightItems`	`string[]`	-	Labels to emphasise (active styling); others keep their base opacity
`disabledItems`	`string[]`	-	Labels to hide entirely (ring + track removed; remaining rings keep their radii order)
`renderer`	`"svg" \| "canvas" \| "webgpu"`	`"svg"`	Render as inline SVG (default) or to a canvas / WebGPU layer; getContext() is identical either way
`locale`	`string`	-	BCP-47 locale used for number formatting
`skipColorMappingDispatch`	`boolean`	`false`	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so arc colours come from your CSS via the data-label-safe contract
`enableTransitions`	`boolean`	`true`	Animate opacity/arc changes with CSS transitions (SVG renderer; default true)
`onColorMappingGenerated`	`(mapping: Record<string, string>) => void`	-	Called with the resolved label -> colour map after the chart assigns colours
`onChartDataProcessed`	`(context: ChartContext) => void`	-	Called with the renderer-agnostic ChartContext whenever the data is (re)processed
`onDataWarning`	`(warnings: DataWarning[]) => void`	-	Called with any non-fatal data warnings (out-of-range values, duplicate labels, ...)

Dữ liệu là hai mảng

Khác với các biểu đồ khác, Sankey nhận nodes ({ id, label?, color? }[]) và links ({ source, target, value }[]) thay vì một dataSet duy nhất.

Events

Web component phát ra các CustomEvent nổi bọt (bubbling) sau đây (engine cũng cung cấp tương đương qua các callback on* trong bảng ở trên):

Event	Detail	Kích hoạt khi
`michi-vz:highlight`	`string[]`	khi trạng thái tô sáng hover thay đổi (id của nút, hoặc source + target của một liên kết)
`michi-vz:colormapping`	`Record<string, string>`	khi một color mapping được tạo ra
`michi-vz:dataprocessed`	`ChartContext`	khi dữ liệu được xử lý (lại)
`michi-vz:datawarning`	`DataWarning[]`	khi phát hiện cảnh báo về dữ liệu đầu vào (ví dụ một liên kết trỏ đến một nút không xác định)
`michi-vz:nodeclick`	`SankeyNodeContext`	khi nhấp vào một nút (callback `onNodeClick`)
`michi-vz:linkclick`	`SankeyLinkContext`	khi nhấp vào một dải dòng chảy (callback `onLinkClick`)

getContext()

mountSankeyChart(el, props).getContext() trả về một SankeyChartContext không phụ thuộc bộ dựng: các nodes (id / label / color / value / độ sâu cột), các links (source / target / value / color), số liệu thống kê tóm tắt (số lượng nút & liên kết, số lượng cột, tổng luồng, liên kết lớn nhất, nút bận rộn nhất), một bản tóm tắt ngôn ngữ tự nhiên có tính xác định, và một bảng a11y liệt kê các luồng. Xem ngữ cảnh LLM.

Source

Các prop được định kiểu là SankeyChartProps trong @michi-vz/core.

API Sankey ​

Import ​

Props ​

Events ​

getContext() ​

Source ​