API Biểu đồ khoảng cách

Thể hiện khoảng cách giữa hai con số và để cây cột truyền tải trọng điểm - xem demo Biểu đồ khoảng cách.

Nhập

Web Component

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

Vanilla JS

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

const chart = mountGapChart(el, props);

Thuộc tính

Prop	Type	Default	Description
dataSet*	GapDataItem[]	-	Array of rows, one horizontal value1->value2 gap bar per item
title	string	-	Optional chart title rendered above the plot
colorMode	"label" | "shape"	"label"	Whether marks are colored per row label ("label", default) or per role/shape via shapeColorsMapping ("shape")
shapeColorsMapping	ShapeMapping	-	When colorMode is "shape", the colors for the value1, value2, and gap parts
shapesLabelsMapping	ShapeMapping	-	Optional display labels for the value1/value2/gap roles (e.g. legend captions)
filter	Filter	-	Top-N / sort filter applied to the data before rendering
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`. The user's `filter` still applies within each period.
shapeValue1	"circle" | "square" | "triangle"	"circle"	Marker shape for the value1 endpoint: "circle" (default), "square", or "triangle"
shapeValue2	"circle" | "square" | "triangle"	"circle"	Marker shape for the value2 endpoint: "circle" (default), "square", or "triangle"
xAxisDataType	"date_annual" | "date_monthly" | "number"	"number"	How x values are parsed and formatted: yearly dates, monthly dates, or plain numbers
xAxisDomain	[number, number]	-	Fix the value-axis range as [min, max] instead of the derived zero-baseline domain (e.g. zoom a life-expectancy story into its 35-90 band)
interactiveRowLabels	boolean	false	Make the row labels interactive: hovering or focusing a label draws a leader line to its row's marks, highlights the row, and shows its tooltip; clicking pins the tooltip. Labels become keyboard-focusable. Default false.
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
ticks	number	5	Approximate number of axis ticks to generate
tickValues	Array<number | Date>	-	Explicit tick values, overriding the generated ones
enableExplicitTickValues	boolean	-	When false, ignore `tickValues` for tick placement and GapChart's mark-scale domain, letting the chart use its data-derived domain and generated ticks.
tickHtmlWidth	number	100	Width in px of the HTML y-axis label box, which ellipsizes longer labels (default 100)
squareRadius	number	2	Corner radius in px for square markers (default 2)
showZeroLineForXAxis	boolean	false	Draw a solid vertical line at x=0 on the value axis (diverging charts). Default false.
maxBarHeight	number	-	Cap each row's thickness (px). When few rows would otherwise balloon the bandwidth (a scaleBand stretched over the full plot height), the band range shrinks to yield exactly this thickness and is centred in the plot (symmetric whitespace), so a 1-2 row chart reads tidily instead of a single row floating mid-plot. No-op for dense charts whose natural bandwidth is already below the cap. Mirrors ComparableBarChart's `maxBarHeight`.
showLegend	boolean	-	Whether to render a legend
legendAlign	"left" | "center" | "right"	-	Horizontal alignment of the legend: "left", "center", or "right"
tooltipFormatter	(d: GapDataItem) => 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: GapDataItem[] | 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	(item: GapDataItem | null) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	1000	Chart width in pixels
height	number	500	Chart height in pixels
margin	Margin	{ top: 50, right: 150, bottom: 100, left: 150 }	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()

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