API Biểu đồ vùng

Xem phần nào trong một tổng đang tăng thực sự là động lực chính - các thuộc tính (props) và sự kiện bên dưới, hoặc xem demo Biểu đồ vùng để thấy nó hoạt động.

Nhập

Web Component

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

Vanilla JS

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

const chart = mountAreaChart(el, props);

Thuộc tính

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.
series*	AreaDataRow[]	-	Array of rows, each carrying an x (`date`) plus one numeric value per stacked key
keys*	string[]	-	Category keys to stack (bottom-to-top); disabledItems removes from the stack.
title	string	-	Optional chart title rendered above the plot
xAxisDataType	"date_annual" | "date_monthly" | "number"	"number"	How x values are parsed and formatted: yearly dates, monthly dates, or plain numbers
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]	-	Fix the y-axis range as [min, max] instead of deriving it from the data
forcePercentageScale	boolean	false	Fix the y-axis to [0,100] regardless of data (display only; data not normalized).
stackOffset	"none" | "expand"	"none"	Stacking normalization, named after d3-shape's own `stackOffsetExpand`. `"none"` (default) stacks absolute values, unchanged. `"expand"` NORMALIZES each x-slice so its band heights sum to 1 (a true 100%-stacked chart, unlike the display-only `forcePercentageScale`): the y domain becomes [0,1] and y-axis ticks render as percentages unless an explicit `yAxisFormat` is given. A slice whose keys are all zero/null renders as an empty (zero-height) band rather than `NaN`.
ticks	number	10	Approximate number of axis ticks to generate
tickValues	Array<number | Date>	-	Explicit tick values, overriding the generated ones
fillPeriodTicks	boolean	-	Draw a tick for EVERY period across the axis range (every month/year), not just the periods present in the data. Periods with no value render faded and show `noDataTickTooltip` on hover. Opt-in; default false.
noDataTickTooltip	(date: number) => string	-	Tooltip content (plain text or sanitized HTML) for a faded no-data tick; receives the tick's epoch-ms value. Used only with `fillPeriodTicks`. Default: a localized "Data not available".
noDataTickColor	string	-	Colour for faded no-data tick labels; sets the `--michi-vz-tick-nodata` CSS var on the host. Used only with `fillPeriodTicks`.
curve	"curveBumpX" | "curveLinear" | "curveMonotoneX"	-	Line interpolation: curveLinear, curveMonotoneX, or curveBumpX
tooltipFormatter	( row: AreaDataRow, series: AreaDataRow[], key: string, ) => 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: AreaDataRow[] | 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.
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: 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, ...)

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

mountAreaChart(el, props).getContext() trả về AreaChartContext độ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à AreaChartProps trong @michi-vz/core.