API Biểu đồ tròn / Vành khuyên
Các lát được chia theo tỷ phần trong tổng thể, với chế độ vành khuyên chỉ cách một prop (innerRadiusRatio) - xem bản demo Biểu đồ tròn / Vành khuyên.
Import
ts
import "@michi-vz/wc/pie-chart";
// <michi-vz-pie-chart> is now definedts
import { mountPieChart } from "@michi-vz/core";
const chart = mountPieChart(el, props);Props
| Prop | Type | Default | Description |
|---|---|---|---|
timeline | boolean | TimelinePeriodConfig | - | Opt-in "play through years": snapshots one period at a time over the distinct per-row `date` values, with a headless controller (`chart.timeline()`) plus an optional built-in play button + scrubber. Off by default; requires rows with `date`. Values tween between periods unless `interpolate: false`. |
dataSet* | PieDataItem[] | - | Array of slices; each value becomes a wedge sized by its share of the total |
title | string | - | Optional chart title rendered above the plot |
innerRadiusRatio | number | 0 | 0 = full pie (default); (0,1) = donut hole as a fraction of the outer radius. |
padAngle | number | 0 | Gap between slices in radians (default 0). |
cornerRadius | number | 0 | Corner radius on the arcs in px (default 0). |
sortByValue | boolean | true | Sort slices by value descending (default true); false keeps data order. |
showLabels | boolean | true | Draw the % label inside each slice when it is large enough (default true). |
showLegend | boolean | false | Render a swatch+label legend below the chart (default false). |
filter | { limit: number; sortingDir: "asc" | "desc" } | - | Keep only the top-N slices by value. |
valueFormatter | (n: number) => string | - | Formats a numeric value for labels and tooltips |
tooltipFormatter | (slice: PieSliceContext) => 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 | 600 | Chart width in pixels |
height | number | 420 | Chart height in pixels |
margin | Margin | { top: 36, 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 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()
mountPieChart(el, props).getContext() trả về một PieChartContext không phụ thuộc bộ dựng: mode ("pie" hoặc "donut"), innerRadiusRatio, các slices (label / value / share / góc bắt đầu & kết thúc), số liệu thống kê tóm tắt (số lượng lát, tổng, lát lớn nhất), một bản tóm tắt ngôn ngữ tự nhiên có tính xác định, và một bảng a11y. Xem ngữ cảnh LLM.
Source
Các prop được định kiểu là PieChartProps trong @michi-vz/core.