API Biểu đồ dải

Theo dõi một thành phần tự sắp xếp lại thứ hạng theo thời gian, từng danh mục được nối liền một lúc. Xem bản demo Biểu đồ dải.

Import

Web Component

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

Vanilla JS

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

const chart = mountRibbonChart(el, props);

Props

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years" (cumulative): the marks draw UP TO the active period and extend as the timeline steps; `interpolate` sweeps smoothly between years, `false` jump-cuts. Headless controller via `chart.timeline()` plus the built-in play button + scrubber. 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.
series*	RibbonDataRow[]	-	Array of rows (one per date) whose keys stack into a column; same-key segments are linked across adjacent dates by ribbon trapezoids
keys*	string[]	-	Ordered segment keys to stack within each column (bottom-to-top) and to connect with ribbons between columns
title	string	-	Optional chart title rendered above the plot
xAxisFormat	(d: number | string) => string	-	Formats an x tick value into its display label
yAxisFormat	(d: number | string) => string	-	Formats a y tick value into its display label
yAxisDomain	[number, number]	-	Explicit [min, max] for the value (y) axis; overrides the auto domain from the stacked column totals
columnWidth	number	30	column width in px (default 30).
ticks	number	5	Approximate number of axis ticks to generate
tooltipFormatter	(row: RibbonDataRow, key: string, value: number) => string	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
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	900	Chart width in pixels
height	number	480	Chart height in pixels
margin	Margin	{ top: 50, right: 50, bottom: 60, left: 60 }	Inner margins (top/right/bottom/left, in px) reserved for axes, titles, and labels
colors	string[]	-	Categorical palette for series/labels 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; all other marks dim
disabledItems	string[]	-	Labels to hide and exclude from scales/stacks
renderer	"svg" | "canvas" | "webgpu"	"svg"	Render as inline SVG (default) or to a canvas (faster for large datasets); getContext() is identical either way
locale	string	-	BCP-47 locale used for number and date formatting
skipColorMappingDispatch	boolean	false	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so mark colours come from your CSS via the data-label-safe contract
enableTransitions	boolean	true	Animate updates with CSS transitions (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 (duplicate labels, non-finite values, non-monotonic dates, ...)

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
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

getContext()

mountRibbonChart(el, props).getContext() trả về một RibbonChartContext không phụ thuộc bộ dựng (số liệu thống kê có cấu trúc + một bản tóm tắt ngôn ngữ tự nhiên có tính xác định + một bảng a11y). Xem ngữ cảnh LLM.

Source

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