API Biểu đồ quả tạ

Nối các đoạn (segment) trên mỗi hàng để thấy chính xác phần đóng góp của từng bước vào tổng nằm ở đâu - các thuộc tính, sự kiện và engine bên dưới; xem nó chuyển động trong demo Biểu đồ quả tạ.

Nhập

Web ComponentVanilla JS

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

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

const chart = mountBarBellChart(el, props);

Thuộc tính

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.
`dataSet`*	`BarBellDataRow[]`	-	Array of rows (one per date/y-band); within each row the keys are laid out cumulatively along x as thin bars capped by end-cap circles
`keys`*	`string[]`	-	Ordered segment keys to draw per row; their values accumulate left-to-right and each gets a colored bar plus end-cap circle
`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 cumulative value (x) axis; overrides the auto domain of [0, max cumulative row total]
`ticks`	`number`	`5`	Approximate number of axis ticks to generate
`tickHtmlWidth`	`number`	`80`	Width in px reserved for each y-axis (date) tick's HTML (default 80)
`xAxisPosition`	`"top" \| "bottom"`	`"top"`	Where the cumulative value axis renders its tick labels: "top" (default, legacy header look) or "bottom" (clears room under the title)
`tooltipFormatter`	`( row: BarBellDataRow, key: string, value: number, ) => string`	-	Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted)
`isLoading`	`boolean`	-	Show the loading overlay and skip the no-data check (legacy michi-vz parity).
`isNodata`	`\| boolean \| ((dataSet: BarBellDataRow[] \| null \| undefined) => boolean)`	-	No-data override: boolean, or a predicate on the data; default = empty data.
`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.
`dodgeOverlappingCaps`	`boolean`	-	Spread overlapping end-caps vertically, centred on the row line (default ON, legacy parity); pass false to keep them stacked.
`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: 50, left: 100 }`	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, ...)

Sự kiện

Web component phát ra (dispatch) các CustomEvent nổi bọt (bubbling) sau đây (engine cũng phơi bày các sự kiện tương tự thông qua các callback on* trong bảng ở trên):

Sự kiện	Chi tiết	Kích hoạt khi
`michi-vz:highlight`	`string[]`	trạng thái nổi bật lúc di chuột thay đổi
`michi-vz:colormapping`	`Record<string, string>`	một ánh xạ màu được tạo ra
`michi-vz:dataprocessed`	`ChartContext`	dữ liệu được xử lý (lại)
`michi-vz:datawarning`	`DataWarning[]`	phát hiện cảnh báo đầu vào

getContext()

mountBarBellChart(el, props).getContext() trả về BarBellChartContext độc lập với renderer (số liệu thống kê có cấu trúc + một bản tóm tắt bằng ngôn ngữ tự nhiên có tính xác định + một bảng hỗ trợ khả năng tiếp cận a11y). Xem ngữ cảnh LLM.

Nguồn

Các thuộc tính (props) được định kiểu là BarBellChartProps trong @michi-vz/core.

API Biểu đồ quả tạ ​

Nhập ​

Thuộc tính ​

Sự kiện ​

getContext() ​

Nguồn ​