API Biểu đồ cột kép (Tornado)
Các cột phân kỳ từ một đường trung tâm, dùng khi bạn cần thể hiện bên nào thắng và thắng bao nhiêu - xem demo Biểu đồ cột kép (Tornado).
Nhập
ts
import "@michi-vz/wc/dual-horizontal-bar-chart";
// <michi-vz-dual-horizontal-bar-chart> is now definedts
import { mountDualHorizontalBarChart } from "@michi-vz/core";
const chart = mountDualHorizontalBarChart(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* | DualBarDataPoint[] | - | Array of diverging (tornado) rows; each row draws value1 as a bar extending right and value2 as a bar extending left from a shared center |
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 | - | Approximate number of axis ticks to generate |
tickHtmlWidth | number | 100 | Width in px reserved for each y-axis (label) tick's HTML (default 100) |
yAxisPosition | "center" | "left" | "center" | Where the row labels sit: "center" (default, legacy: on the shared centre line, over the left-extending bars) or "left" (in the left margin, clear of the plot - the classic population-pyramid look). |
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. |
value1Opacity | number | 0.9 | value1 (right) / value2 (left) fill opacities. |
value2Opacity | number | 0.55 | Fill opacity of the left-extending value2 bar (default 0.55) |
filter | { limit: number; criteria: "value1" | "value2"; sortingDir: "asc" | "desc"; } | - | Keep only the top-N labels ranked by the chosen field: limit caps the count, criteria selects "value1" or "value2", sortingDir picks highest (desc) or lowest (asc) |
tooltipFormatter | (d: DualBarDataPoint) => 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 | 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); 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, ...) |
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()
mountDualHorizontalBarChart(el, props).getContext() trả về DualBarChartContext độ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à DualBarChartProps trong @michi-vz/core.