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

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

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

const chart = mountBubbleChart(el, props);

import { BubbleChart } from "@michi-vz/react/bubble-chart";

import { BubbleChart } from "@michi-vz/vue/bubble-chart";

import { bubbleChart } from "@michi-vz/svelte/bubble-chart";

import { bindChart, applyBubbleChartProps } from "@michi-vz/angular/bubble-chart";
// needs CUSTOM_ELEMENTS_SCHEMA on the component that hosts <michi-vz-bubble-chart>

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.
`draggable`	`boolean`	`false`	Let the viewer drag a bubble (default false). While held, the bubble follows the pointer and the collision force pushes its neighbours out of the way; on release the cluster's gravity pulls everything back and the simulation cools in place (svg marks move, canvas/webgpu repaint). The settled layout is not changed: the next data or size update packs the cluster afresh. A drag never counts as a click (`onBubbleClick` does not fire).
`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)
`onBubbleClick`	`(bubble: BubbleContext, event: MouseEvent) => void`	-	Called when a bubble is clicked (svg marks and the canvas/webgpu hit-test alike), with the same bubble context the tooltip formatter receives and the mouse event. The click still pins the tooltip as before; use this to navigate or select from the bubble itself instead of a link inside the pinned tooltip.
`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); 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
`michi-vz:bubbleclick`	`BubbleContext`	khi nhấp vào một bong bóng (callback `onBubbleClick`)

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.

API Biểu đồ bong bóng ​

Nhập ​

Thuộc tính ​

Sự kiện ​

getContext() ​

Nguồn ​