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

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

import { BarBellChart } from "@michi-vz/react/bar-bell-chart";

import { BarBellChart } from "@michi-vz/vue/bar-bell-chart";

import { barBellChart } from "@michi-vz/svelte/bar-bell-chart";

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

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); 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, ...)

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 ​