API Biểu đồ cột so sánh
Hai giá trị cho mỗi nhãn, giá trị gốc (based) so với giá trị so sánh (compared), giúp thấy ngay sự thay đổi trước/sau chỉ trong một cái nhìn - xem demo Biểu đồ cột so sánh.
Nhập
ts
import "@michi-vz/wc/comparable-horizontal-bar-chart";
// <michi-vz-comparable-horizontal-bar-chart> is now definedts
import { mountComparableHorizontalBarChart } from "@michi-vz/core";
const chart = mountComparableHorizontalBarChart(el, props);Thuộc tính
| 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* | ComparableBarDataPoint[] | - | Array of horizontal-bar rows; each renders two overlaid sub-bars (valueBased behind, valueCompared in front) for one label |
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 |
xAxisDomain | [number, number] | - | Fix the x-axis range instead of deriving it from the data |
ticks | number | 5 | Approximate number of axis ticks to generate |
tickHtmlWidth | number | 100 | Width in px reserved for each y-axis (label) tick's HTML (default 100) |
colorsBasedMapping | Record<string, string> | - | Optional label -> colour map for the value-based sub-bar ONLY (falls back to the row colour). Pair an opaque light tint here with valueBasedOpacity 1 to make before vs after unmistakable in both themes (legacy michi-vz parity). |
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. |
valueBasedOpacity | number | 0.45 | Fill opacity of the two sub-bars (historical look: 0.45 / 0.9). |
valueComparedOpacity | number | 0.9 | Fill opacity of the front valueCompared sub-bar (default 0.9) |
xAxisPredefinedDomain | number[] | - | Legacy alias for xAxisDomain (consumers pass [min,max]); wins over xAxisDomain when length===2 |
patternsMapping | Record<string, string> | - | Per-label image source (data-URI, e.g. createHatchPattern) used to FILL the value-based sub-bar - the canvas tiles it via ctx.createPattern, an SVG renderer via <pattern>/<image> |
showZeroLineForXAxis | boolean | false | Draw a solid vertical line at x=0 on the value axis (diverging charts) |
showGrid | boolean | false | Draw vertical gridlines on the value axis (default false, legacy parity) |
hideTickLabels | boolean | false | Hide the y-axis category labels (consumers control them via the legend column) |
minBarWidth | number | 5 | Floor for a sub-bar's pixel width so near-zero values stay visible (default 5) |
padding | { top: number; right: number; bottom: number; left: number } | ZERO_PADDING | Extra plot-area inset (px); padding.left opens a left column for the y-axis label chips without moving the labels themselves (which stay anchored to margin.left) |
horizontalTickPosition | { x: number; y: number } | - | Offset (px) applied to the y-axis category labels so they align with the legend column |
maxBarHeight | number | - | Cap each bar's thickness (px). When few rows would otherwise balloon the bandwidth, the band range shrinks to yield exactly this thickness and is centred in the plot. No-op for dense charts whose natural bandwidth is already below the cap. |
symmetricXDomain | boolean | - | Force a symmetric x-domain [-M, M], M = max(|min|, |max|) of the data, so 0 sits centred and the negative/positive sides mirror (e.g. ± growth %). Wins over xAxisDomain / xAxisPredefinedDomain. |
layout | "overlay" | "grouped" | "overlay" | How the two sub-bars (valueBased, valueCompared) share a row's band. "overlay" (default): both draw at the full band thickness, one in front of the other - today's behaviour, byte-identical when this prop is omitted. "grouped": the band splits in half - valueBased occupies the top half, valueCompared the bottom half, with no overlap (legacy sdg-trade BarchartHorizontal look). Everything else (scales, colours, patternsMapping, tooltips, maxBarHeight, symmetricXDomain) is identical between modes. |
deltaIndicator | DeltaIndicatorConfig | - | Row-level change indicator (arrow + formatted diff label) comparing valueCompared to valueBased. Omitted, or `{ show: false }`, is a provable no-op (zero geometry, zero `.mv-delta` DOM). See DeltaIndicatorConfig JSDoc for the full decision-logic contract. |
isLoading | boolean | - | Loading overlay (stale bars hidden while true) |
isNodata | | boolean | ((dataSet: ComparableBarDataPoint[] | null | undefined) => boolean) | - | No-data predicate/flag; default = empty dataSet |
noDataLabel | string | - | Text for the built-in no-data overlay |
suppressDefaultOverlay | boolean | - | Set by a framework wrapper passing its own overlay node - suppresses the default overlay |
filter | { limit: number; criteria: "valueBased" | "valueCompared"; sortingDir: "asc" | "desc"; } | - | Keep only the top-N labels ranked by the chosen field: limit caps the count, criteria selects "valueBased" or "valueCompared", sortingDir picks highest (desc) or lowest (asc) |
tooltipFormatter | ( d: ComparableBarDataPoint, dataSet?: ComparableBarDataPoint[], type?: "based" | "compared", ) => string | - | Returns custom tooltip HTML for a hovered datum (sanitized before it is inserted). `type` is the hovered sub-bar ("based" | "compared"); `dataSet` is all rows. |
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: 120 } | 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()
mountComparableHorizontalBarChart(el, props).getContext() trả về ComparableBarChartContext độ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à ComparableBarChartProps trong @michi-vz/core.