API Biểu đồ cột dọc so sánh
Hai giá trị cho mỗi danh mục, giá trị gốc (based) so với giá trị so sánh (compared), dưới dạng các cột chồng lên nhau ở toàn bộ bề rộng với một mũi tên biến động tùy chọn phía trên mỗi cặp - xem demo Biểu đồ cột dọc so sánh.
Nhập
ts
import "@michi-vz/wc/comparable-vertical-bar-chart";
// <michi-vz-comparable-vertical-bar-chart> is now definedts
import { mountComparableVerticalBarChart } from "@michi-vz/core";
const chart = mountComparableVerticalBarChart(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 column categories; each renders two overlaid sub-bars (valueBased behind, valueCompared in front), full column bandwidth, diverging from y=0 |
title | string | - | Optional chart title rendered above the plot |
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 for the crispest before/after contrast (legacy michi-vz parity). |
xAxisFormat | (d: string) => string | - | Formats a category (x tick) label |
yAxisFormat | (d: number | string) => string | - | Formats a y tick value into its display label |
yAxisDomain | [number, number] | - | Fix the y-axis (value) range instead of deriving it from the data |
symmetricYDomain | boolean | - | Force a symmetric y-domain [-M, M], M = max(|min|, |max|) of the data, so 0 sits centred and the negative/positive sides mirror. Wins over yAxisDomain. |
ticks | number | 5 | Approximate number of y-axis (value) ticks |
xAxisLabelPadding | number | - | Min gap (px) a column label needs before it tilts -45° (chooseAxisMode). Default 8. |
xAxisMode | "auto" | "horizontal" | - | "auto" (default) tilts crowded column labels -45°, else thins; "horizontal" keeps them flat (thinning instead), so no rotated-label bottom margin is reserved. |
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, the SVG renderer via a real `<pattern>`/`<image>` def (same contract as ComparableHorizontalBarChart). |
valueBasedOpacity | number | 0.45 | Fill opacity of the rear valueBased sub-bar (historical look: 0.45) |
valueComparedOpacity | number | 0.9 | Fill opacity of the front valueCompared sub-bar (default 0.9) |
showZeroLineForYAxis | boolean | false | Draw a solid horizontal line at y=0 on the value axis (diverging charts) |
showGrid | boolean | false | Draw horizontal gridlines on the value axis (default false, legacy parity) |
hideTickLabels | boolean | false | Hide the x-axis category labels |
minBarHeight | number | 5 | Floor for a sub-bar's pixel height so near-zero values stay visible (default 5) |
maxBarWidth | number | - | Cap each column's thickness (px). When few categories 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. |
deltaIndicator | DeltaIndicatorConfig | - | Row-level change indicator (arrow + formatted diff label) comparing valueCompared to valueBased, drawn above each column pair. Omitted, or `{ show: false }`, is a provable no-op (zero geometry, zero `.mv-delta` DOM). Unlike ComparableHorizontalBarChart, THIS chart's context DOES reflect the indicator (per-series direction/color/label) - 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: 100, 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()
mountComparableVerticalBarChart(el, props).getContext() trả về ComparableVerticalBarChartContext độ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). Khác với ComparableHorizontalBarChart, ngữ cảnh này phản ánh deltaIndicator khi được kích hoạt: series[].deltaDirection / deltaColor / deltaLabel, và stats.grew / stats.shrank / stats.unchanged / stats.improved / stats.worsened. Xem ngữ cảnh LLM.
Nguồn
Các thuộc tính (props) được định kiểu là ComparableVerticalBarChartProps trong @michi-vz/core.