API Biểu đồ cột chồng dọc

Cho thấy mỗi danh mục được cấu thành từ những gì, từng phân đoạn một, với các phần bị thiếu được gắn cờ cảnh báo thay vì bị bỏ qua - xem bản demo Biểu đồ cột chồng dọc.

Import

Web Component

import "@michi-vz/wc/vertical-stack-bar-chart";
// <michi-vz-vertical-stack-bar-chart> is now defined

Vanilla JS

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

const chart = mountVerticalStackBarChart(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.
dataSet*	VerticalStackBarDataSet[]	-	Array of grouped series; each entry contributes its own bar slot per date and stacks its segment keys vertically
keys	string[]	-	Explicit stack order; present keys first (in this order), natural keys appended.
keysOrder	"topToBottom" | "bottomToTop"	"topToBottom"	Where keys[0] sits in the stack: "topToBottom" (default) puts keys[0] at the top, "bottomToTop" anchors keys[0] at the bottom
title	string	-	Optional chart title rendered above the plot
xAxisLabelPadding	number	-	Min gap (px) a horizontal x-axis label needs before it tilts -45°. Raise it to give crowded date labels more breathing room (they rotate sooner instead of sitting flush). Default 8 (legacy parity).
xAxisMode	"auto" | "horizontal"	-	"auto" (default) tilts crowded date labels -45°; "horizontal" keeps them flat (thinning instead), so no rotated-label bottom margin is reserved.
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
xAxisDomain	string[]	-	Explicit ordered list of date band categories; overrides the auto-collected, sorted set of dates from the data
yAxisDomain	[number, number]	-	Fix the y-axis range as [min, max] instead of deriving it from the data
minBarWidth	number	5	Minimum width in px for each bar slot, floored when bands get narrow (default 5)
minBarHeight	number	15	Minimum height in px for a non-zero segment so thin values stay visible (default 15)
minBarHeightZero	number	0	Height in px drawn for an explicit zero-value segment (default 0, i.e. nothing)
missingDataMarker	{ height: number }	-	Opt-in thin stub on the zero line for explicitly-missing (null/NaN) owned keys.
filter	{ limit: number; sortingDir: "asc" | "desc"; date?: string }	-	Keep only the top-N dates ranked by grand total across all series and keys: limit caps the count, sortingDir picks highest (desc) or lowest (asc), optional date is the reference date; chronological order is preserved in output
isLoading	boolean	-	Show the loading overlay and skip the no-data check.
isNodata	| boolean | ((dataSet: VerticalStackBarDataSet[] | null | undefined) => boolean)	-	No-data override: boolean or predicate; default = empty / all-empty-series.
noDataLabel	string	-	Text for the vanilla default no-data overlay.
suppressDefaultOverlay	boolean	-	A framework wrapper sets this to render its OWN loading/no-data node.
fontFamily	string	-	Font family for axis/label text (SVG + canvas) via --michi-vz-font-family.
yTicks	number	-	Number of y-axis ticks (default 10).
showGridLines	boolean	-	Draw horizontal dashed y grid lines (default true).
highlightZeroLine	boolean	-	Emphasise the y=0 line with a solid stroke (default true).
tooltipFormatter	(d: StackTooltipData) => 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
onLegendDataChange	(legendData: StackLegendItem[]) => void	-	Called with the computed legend items (label, color, order, disabled, dataLabelSafe) whenever the legend changes

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: 100, 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()

mountVerticalStackBarChart(el, props).getContext() trả về một VerticalStackBarChartContext 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à VerticalStackBarChartProps trong @michi-vz/core.