API Bản đồ phân cấp màu

Một bản đồ phân cấp màu thế giới/khu vực: GeoJSON của riêng bạn, được tô màu theo thang màu ngưỡng hoặc một bản đồ danh mục rõ ràng - xem demo Bản đồ phân cấp màu.

Nhập

Web Component

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

Vanilla JS

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

const chart = mountChoroplethMapChart(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`.
geography*	GeoJSON.FeatureCollection | GeoFeatureItem[]	-	The world/region geography to draw. A full GeoJSON FeatureCollection (its per-feature `id`/`properties.name` are read automatically) or a pre-normalized flat array. Core bundles NO topology data - import your own (e.g. a `world-atlas` TopoJSON converted via `topojson-client`, or a hand-curated GeoJSON) and pass it here.
dataSet*	ChoroplethDataItem[]	-	Choropleth values/colours, joined against `geography` (see `joinBy`).
title	string	-	Optional chart title rendered above the map
projection	GeoProjectionName	-	d3-geo / d3-geo-projection projection to use (default "geoRobinson", the legacy sdg-trade MapChoropleth default). `geoAlbersUsa` is a fixed composite projection - it ignores `rotate`/`center`/`parallels`.
projectionConfig	GeoProjectionConfig	-	Fine-tunes the chosen projection. Omitted fields fall back to the legacy MapChoropleth defaults (rotate [-18, 0], center [0, 10], base scale derived from width) rather than `projection.fitSize` - this matches the legacy chart's visual result exactly; pass your own values to frame a different geography extent (e.g. a single-region subset).
colorScale	{ domain: number[]; range: string[] }	-	Continuous choropleth encoding: a resolved hex `range` keyed to a numeric `domain`, built into a d3 `scaleThreshold`. Pass already-resolved colours (NOT a d3-scale-chromatic scheme name - core stays free of that dependency); generate the range yourself (e.g. via `d3-scale-chromatic` in your app) if you want a named scheme. Loses to `colorsMapping`.
noDataColor	string	DEFAULT_NO_DATA_COLOR	Fill for features with no matching `dataSet` row (default `#d2d7dd`).
joinBy	"id" | "name"	"id"	How `dataSet` rows join `geography` features: "id" (default) matches `ChoroplethDataItem.id` against `GeoFeatureItem.id` / GeoJSON `Feature.id` (stable codes such as ISO-A3), while "name" matches `label` against `GeoFeatureItem.name` / `properties.name` for data keyed by display name.
strokeColor	string	DEFAULT_STROKE_COLOR	Country border colour (legacy default: `#F4F7FC`, `colors.WHITE_SMOKE`)
strokeWidth	number	1	Country border width in px (default 1)
tooltipFormatter	(d: ChoroplethDataItem | { id: string; name?: string }) => string	-	Formats the tooltip for a hovered region. Matched rows receive the full `ChoroplethDataItem`; regions with no matching row receive the fallback `{ id, name }` shape (mirrors the legacy chart's "N/A" tooltip).
isLoading	boolean	-	Loading overlay (stale regions hidden while true)
isNodata	boolean | ((dataSet: ChoroplethDataItem[] | 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
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	520	Chart height in pixels
margin	Margin	{ top: 40, right: 10, bottom: 10, left: 10 }	Inner margins (top/right/bottom/left, in px) reserved for axes, titles, and labels
colorsMapping	Record<string, string>	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
colors	string[]	-	Categorical palette for series/labels without an explicit colour or colorsMapping entry
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 (id dataSet không khớp, feature thiếu id, hình học không hợp lệ)

getContext()

mountChoroplethMapChart(el, props).getContext() trả về ChoroplethMapChartContext độc lập với renderer: stats.featureCount / matchedCount / unmatchedCount / valueDomain / min / max, một mảng regions[] (một hàng cho mỗi feature: id, label, value?, color, matched), tên projection đã phân giải, 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 a11yTable liệt kê mỗi khu vực + giá trị + cờ khớp. Xem ngữ cảnh LLM.

Nguồn

Các thuộc tính (props) được định kiểu là ChoroplethMapChartProps trong @michi-vz/core.