API Biểu đồ vòng cung

Các vòng đồng tâm, từ ngoài vào trong, mỗi vòng quét value / max của một vòng tròn đầy đủ trên rãnh nền - xem demo Biểu đồ vòng cung.

Import

Web Component

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

Vanilla JS

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

const chart = mountGaugeChart(el, props);

Props

Prop	Type	Default	Description
dataSet*	GaugeRingDatum[]	-	Rings, OUTER to INNER; each sweeps value/max of the circle over a track
title	string	-	Optional chart title rendered above the plot
max	number	100	Value corresponding to a full 360° sweep (default 100).
ringThickness	number	18	Ring stroke thickness in px (default 18).
ringGap	number	2	Gap between adjacent rings in px (default 2).
outerRadius	number	null	Outermost ring's outer edge radius in px; default fills the plot box.
startAngle	number	0	Arc start angle in degrees, 0 = 12 o'clock, positive clockwise (default 0).
roundedCaps	boolean	false	Round the arc ends (default false = square caps).
ringOpacity	number | number[]	1	Arc opacity per ring, outer→inner; a single number applies to every ring (default 1).
trackColor	string | string[]	"#00000014"	Track colour(s) behind the arcs, outer→inner; per-ring `trackColor` wins (default "#00000014").
trackOpacity	number | number[]	1	Track opacity per ring, outer→inner (default 1).
defaultActive	number | "inner" | "outer" | null	-	The ring active when nothing is hovered: a dataSet index, "inner"/"outer", or null for none (default "inner").
activeStyle	GaugeActiveStyle	{}	Emphasis applied to the active ring (default { opacity: 1 }).
showCenterLabel	boolean	true	Draw the built-in centre label: active ring's name + formatted value (default true). Turn off to render your own centre overlay (drive it via onHighlightItem).
centerContent	(ring: GaugeRingContext | null) => string	-	Custom centre HTML for the active ring (sanitized before insertion); wins over the default label+value markup. Receives null when no ring is active.
valueFormatter	(v: number) => string	-	Formats a ring value for the centre label and tooltips (default `${v}%`).
noValueLabel	string	-	Centre value text for an active ring with no data (default "n/a").
fontFamily	string	-	Font family for the title/centre label; sets the --michi-vz-font-family CSS var
isLoading	boolean	-	Show the loading overlay and skip the no-data check
isNodata	boolean | ((dataSet: GaugeRingDatum[] | null | undefined) => boolean)	-	No-data override: boolean, or a predicate on dataSet; default = empty dataSet (rings whose value is null still RENDER, as empty tracks).
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.
tooltipFormatter	(ring: GaugeRingContext) => string	-	Opt-in hover tooltip HTML for a ring (sanitized). Default: no tooltip - the centre label is the built-in readout.
onHighlightItem	(labels: string[]) => void	-	Called with the hovered ring's label (empty array on leave)

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	300	Chart width in pixels
height	number	300	Chart height in pixels
margin	Margin	{ top: p.title ? 36 : 8, right: 8, bottom: 8, left: 8 }	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, ...)

Events

Web component phát các CustomEvent nổi bọt sau (engine cung cấp tương tự qua các callback on* trong bảng trên):

Event	Detail	Fires when
michi-vz:highlight	string[]	hover highlight changes
michi-vz:colormapping	Record<string, string>	a color mapping is generated
michi-vz:dataprocessed	ChartContext	data is (re)processed
michi-vz:datawarning	DataWarning[]	input warnings are detected

getContext()

mountGaugeChart(el, props).getContext() trả về một GaugeChartContext độc lập trình kết xuất: thang max, các rings (label / value / fraction / index, từ ngoài vào trong), thống kê tóm tắt (số vòng, vòng lớn nhất), một bản tóm tắt ngôn ngữ tự nhiên xác định và một bảng a11y. Xem Ngữ cảnh LLM.

Source

Props được định kiểu GaugeChartProps trong @michi-vz/core.