API Biểu đồ bong bóng
Các vòng tròn được nhóm theo lực hút (gravity-clustered), có kích thước theo giá trị, mỗi vòng tròn có thể tùy chọn được chia thành một lõi đã đạt được (realized core) và một vành chưa khai thác (untapped ring) - xem demo Biểu đồ bong bóng.
Nhập
ts
import "@michi-vz/wc/bubble-chart";
// <michi-vz-bubble-chart> is now definedts
import { mountBubbleChart } from "@michi-vz/core";
const chart = mountBubbleChart(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* | BubbleDataItem[] | - | Array of bubbles; each value sets the circle area (bubbles are gravity-packed into a cluster) |
title | string | - | Optional chart title rendered above the plot |
gravity | number | 0.09 | Strength of the pull toward the centre in [0,1] (default 0.09) - higher = tighter cluster ("suck together"). |
chargeStrength | number | 0 | Many-body charge: negative repels, positive attracts (default 0). |
padding | number | 2 | Gap between packed circles in px (default 2). |
fillRatio | number | 0.62 | Fraction of the plot area the bubbles should fill, in (0,1] (default 0.62). |
layoutMode | "sync" | "async" | "sync" | How the force layout settles: "sync" (default; identical layout every render, blocks until settled) or "async" (the SAME deterministic settle, run in ~12ms slices so thousands of bubbles never freeze the page; the loading overlay shows while it runs). |
settleTicks | number | 400 | Force-simulation ticks to settle (default 400); fewer = faster but looser. |
splitLabels | [string, string] | ["Realized", "Untapped"] | Names of the two split parts (default ["Realized","Untapped"]). |
splitOpacity | number | 0.35 | Apparent colour strength of the untapped veil in [0,1] (default 0.35); rendered as solid colour under a white veil so it reads as a lighter tint of the same hue on any background. |
showSplit | boolean | - | Render the realized/untapped split. Defaults to auto-on when any item has `partial`. |
showLegend | boolean | false | Render a 2-swatch split legend (uses splitLabels). |
showLabels | boolean | true | Draw the label inside each bubble when it is large enough (default true). |
filter | { limit: number; sortingDir: "asc" | "desc" } | - | Keep only the top-N bubbles by value. |
valueFormatter | (n: number) => string | - | Formats a numeric value for labels and tooltips |
tooltipFormatter | (bubble: BubbleContext) => string | - | Returns custom tooltip HTML for a hovered datum/mark (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 | 700 | Chart width in pixels |
height | number | 500 | Chart height in pixels |
margin | Margin | { top: 36, right: 8, bottom: 8, left: 8 } | 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()
mountBubbleChart(el, props).getContext() trả về BubbleChartContext độc lập với renderer: mảng phẳng bubbles (value / partial / remainder / percent), splitLabels, các số liệu thống kê tổng hợp (số lượng bong bóng, tổng, tổng theo từng phần, bong bóng lớn nhất, phần dư lớn nhất), một bản tóm tắt bằng ngôn ngữ tự nhiên có tính xác định và 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à BubbleChartProps trong @michi-vz/core.