地图 - Kumo

const cloudflareLocations = [
  { city: "San Francisco", iata: "SFO", lat: 37.77, lon: -122.42 },
  { city: "London", iata: "LHR", lat: 51.51, lon: -0.13 },
  { city: "Singapore", iata: "SIN", lat: 1.35, lon: 103.82 },
  // ...more locations
];

<BubbleMap
  echarts={echarts}
  geoJson={geoJson}
  data={cloudflareLocations}
  lng="lon"
  lat="lat"
  name="city"
  value={() => 1}
  bubbleColor="#F6821F"
  minRadius={8}
  maxRadius={8}
  tooltipFormatter={(row) =>
    "<strong>" + row.city + "</strong> " + row.iata
  }
/>

安装

BubbleMap 与 ChoroplethMap 需要 echarts 作为 peer dependency。GlobeMap 会将内置的 Natural Earth 陆地掩膜直接渲染为 SVG，不使用 WebGL，也不需要 ECharts。平面地图使用方需要自行提供 GeoJSON；地图组件不会获取地图数据，也不使用地图瓦片。

npm install echarts

桶式导出

import { BubbleMap, ChoroplethMap, GlobeMap } from "@cloudflare/kumo";

细粒度导入

import { BubbleMap, ChoroplethMap, GlobeMap } from "@cloudflare/kumo/components/chart";

用法

import { BubbleMap, ChoroplethMap, type MapGeoJson } from "@cloudflare/kumo";
import * as echarts from "echarts/core";
import { MapChart, ScatterChart } from "echarts/charts";
import { TooltipComponent, VisualMapComponent } from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";

echarts.use([
  MapChart,
  ScatterChart,
  TooltipComponent,
  VisualMapComponent,
  CanvasRenderer,
]);

// Load GeoJSON in your app and pass it to map components.
const geoJson = world as MapGeoJson;

const colos = [
  { iata: "SFO", city: "San Francisco", lat: 37.77, lon: -122.42, requests: 1200 },
  { iata: "LHR", city: "London", lat: 51.5, lon: -0.12, requests: 1500 },
];

const countries = [
  { country: "United States of America", requests: 4200 },
  { country: "Germany", requests: 3100 },
];

export default function Example() {
  return (
    <>
      <BubbleMap
        echarts={echarts}
        geoJson={geoJson}
        data={colos}
        lng="lon"
        lat="lat"
        name="city"
        value="requests"
      />

      <ChoroplethMap
        echarts={echarts}
        geoJson={geoJson}
        data={countries}
        name="country"
        value="requests"
      />
    </>
  );
}

示例

气泡地图

按经纬度绘制原始数据行。value 访问器控制气泡的比例大小。

<BubbleMap
  echarts={echarts}
  geoJson={geoJson}
  data={colos}
  lng="lon"
  lat="lat"
  name="city"
  value="requests"
  minRadius={8}
/>

等值区域图

按数值为区域着色。数据行通过 name 与 GeoJSON 要素关联（与该要素的 nameProperty 匹配，默认 "name"）。

<ChoroplethMap
  echarts={echarts}
  geoJson={geoJson}
  data={countries}
  name="country"
  value="requests"
/>

Cloudflare 可用位置

在不使用 WebGL 的情况下绘制地理标记。斜纹的陆地、透明的海洋、随地平线淡出的标记和密集的地理辅助线，呼应了 Cloudflare 营销主页上的地球样式，同时让蓝色位置保持醒目。这些示意位置使用主要网络城市与 IATA 代号；拖动地球，或聚焦后用方向键，可查看隐藏半球上的点位。

<GlobeMap
  markers={cloudflareAvailabilityLocations}
  landColor="var(--text-color-kumo-inactive)"
  landHatchSpacing={8}
  oceanColor="transparent"
  showGraticule
  markerColor="var(--color-kumo-brand)"
  markerRadius={8}
  autoRotate
/>

当默认的名称/数值 tooltip 不够用时，可提供 tooltipFormatter。格式化函数返回由 ECharts 渲染的 HTML，因此请对用户提供的值进行转义。

<BubbleMap
  echarts={echarts}
  geoJson={geoJson}
  data={colos}
  lng="lon"
  lat="lat"
  name="city"
  value="requests"
  tooltipFormatter={(row) =>
    "<strong>" + row.city + "</strong><br />" + row.requests.toLocaleString()
  }
/>

API 参考

BubbleMap

Prop	Type	Default	Description
echarts*	`typeof echarts`	-	The ECharts core instance imported by the consumer (passed in for tree-shaking). Requires `MapChart`, `ScatterChart`, `TooltipComponent`, and a renderer registered via `echarts.use([...])`.
geoJson*	`MapGeoJson`	-	GeoJSON `FeatureCollection` for the land base.
mapName	`string`	-	Optional stable ECharts map registry name. Set this when the same GeoJSON is parsed into new object instances across mounts and should reuse one global ECharts registration.
data*	`T[]`	-	Raw data rows. Coordinates/value/name are read via the accessors below.
lng*	`MapAccessor<T, number>`	-	Longitude accessor (key of `T` or `(row) => number`).
lat*	`MapAccessor<T, number>`	-	Latitude accessor (key of `T` or `(row) => number`).
value*	`MapAccessor<T, number>`	-	Value accessor — drives bubble size.
name	`MapAccessor<T, string>`	-	Optional name accessor — used by the default tooltip.
minRadius	`number`	-	Smallest bubble radius in px. Default: `6`.
maxRadius	`number`	-	Largest bubble radius in px. Default: `26`.
bubbleSize	`(value: number) => number`	-	Explicit bubble radius `(value) => px`. Overrides the default `minRadius`/`maxRadius` scaling.
bubbleColor	`MapStyle<T, string>`	-	Bubble fill colour — constant or `(row) => color`. Defaults to the chart blue.
bubbleBorderColor	`MapStyle<T, string>`	-	Bubble border colour — constant or `(row) => color`. Default: `transparent`.
bubbleBorderWidth	`MapStyle<T, number>`	-	Bubble border width — constant or `(row) => px`. Default: `0`.
center	`[number, number]`	-	Map center as `[longitude, latitude]`. Defaults to auto-fit.
zoom	`number`	-	Zoom level — multiplies the auto-fit scale. Default: `1.25`.
roam	`boolean`	-	Enable drag-to-pan and scroll-to-zoom. Default: `false`.
projection	`MapProjection \| null`	-	Geographic projection. Defaults to a latitude-clamped Mercator (flat 2D web-map look). Pass another d3-geo projection to override, or `null` for ECharts' raw equirectangular plotting. Use a stable reference (module-level or memoised): a new object each render rebuilds the view and resets a roamed/zoomed map.
showTooltip	`boolean`	-	Show the tooltip. Default: `true`.
valueFormat	`(value: number) => string`	-	Format the value for the default tooltip. Default: `toLocaleString()`.
tooltipFormatter	`(row: T) => string`	-	Override the tooltip content for a row. Returns an HTML string rendered by ECharts' own tooltip. USE WITH CAUTION: the return value is injected as HTML. Escape any user-provided strings to avoid XSS.
aspectRatio	`number \| string`	-	Container aspect ratio as `width / height` (e.g. `1.7` or `"16 / 9"`). The height derives from the rendered width so the map fills the frame with no letterboxing. Defaults to the projected aspect of the displayed window, so the land fits edge-to-edge. Pass `height` to fix a pixel height instead.
height	`number`	-	Fixed chart height in pixels. Overrides `aspectRatio` when set. Leave unset to size by aspect ratio (the default) so the map fills the container.
className	`string`	-	-
isDarkMode	`boolean`	-	-

ChoroplethMap

Prop	Type	Default	Description
echarts*	`typeof echarts`	-	The ECharts core instance imported by the consumer (passed in for tree-shaking). Requires `MapChart`, `VisualMapComponent`, `TooltipComponent`, and a renderer registered via `echarts.use([...])`.
geoJson*	`MapGeoJson`	-	GeoJSON `FeatureCollection` whose regions are shaded by value.
mapName	`string`	-	Optional stable ECharts map registry name. Set this when the same GeoJSON is parsed into new object instances across mounts and should reuse one global ECharts registration.
data*	`T[]`	-	Raw data rows. The region key and value are read via the accessors below.
name*	`MapAccessor<T, string>`	-	Region-key accessor (key of `T` or `(row) => string`). Each row is joined to a GeoJSON feature whose `nameProperty` equals this value.
value*	`MapAccessor<T, number>`	-	Value accessor — drives the region's fill colour.
nameProperty	`string`	-	GeoJSON feature property to join on. Default: `"name"`. Real-world data is often more reliably matched on an ISO-code property (e.g. `"iso_a2"`).
colorRange	`string[]`	-	Sequential colour ramp (low → high). Defaults to the Kumo choropleth blues, tuned to stay distinct from the no-data fill. Distributed across the continuous gradient.
noDataColor	`string`	-	Fill for regions with no matching data row. Defaults to the neutral land grey.
showLegend	`boolean`	-	Show the visualMap colour legend. Default: `false`.
showTooltip	`boolean`	-	Show the tooltip. Default: `true`.
valueFormat	`(value: number) => string`	-	Format the value for the default tooltip. Default: `toLocaleString()`.
tooltipFormatter	`(row: T) => string`	-	Override the tooltip content for a row. Returns an HTML string rendered by ECharts' own tooltip. USE WITH CAUTION: the return value is injected as HTML. Escape any user-provided strings to avoid XSS.
center	`[number, number]`	-	Map center as `[longitude, latitude]`. Defaults to auto-fit.
zoom	`number`	-	Zoom level — multiplies the auto-fit scale. Default: `1.25`.
roam	`boolean`	-	Enable drag-to-pan and scroll-to-zoom. Default: `false`.
projection	`MapProjection \| null`	-	Geographic projection. Defaults to a latitude-clamped Mercator (flat 2D web-map look). Pass another d3-geo projection to override, or `null` for ECharts' raw equirectangular plotting. Use a stable reference (module-level or memoised): a new object each render rebuilds the view and resets a roamed/zoomed map.
aspectRatio	`number \| string`	-	Container aspect ratio as `width / height` (e.g. `1.7` or `"16 / 9"`). The height derives from the rendered width so the map fills the frame with no letterboxing. Defaults to the projected aspect of the displayed window, so the regions fit edge-to-edge. Pass `height` to fix a pixel height instead.
height	`number`	-	Fixed chart height in pixels. Overrides `aspectRatio` when set. Leave unset to size by aspect ratio (the default) so the map fills the container.
className	`string`	-	-
isDarkMode	`boolean`	-	-

GlobeMap

Prop	Type	Default	Description
landColor	`string`	-	Stroke color for the hatched land. Defaults to the neutral Kumo map area color.
landHatchSpacing	`number`	-	Spacing between land hatch lines in view-box pixels. Default: `10`.
oceanColor	`string`	-	Fill behind the land and graticule. Default: the Kumo base surface.
markers	`GlobeMapMarker[]`	-	Geographic points drawn above the land. Points fade at the horizon and back-facing points are hidden.
markerColor	`string`	-	Default marker fill. Defaults to the Kumo chart blue.
markerRadius	`number`	-	Default marker radius in view-box pixels. Default: `7`.
defaultRotation	`number[]`	-	Initial globe rotation as `[longitude, latitude, roll]`.
autoRotate	`boolean`	-	Continuously rotate the globe horizontally. Default: `false`.
autoRotateSpeed	`number`	-	Horizontal auto-rotation speed in degrees per second. Default: `4`.
showGraticule	`boolean`	-	Draw latitude and longitude guides. Default: `false`.
showTooltip	`boolean`	-	Show the Kumo-styled marker tooltip. Default: `true`.
height	`number`	-	Fixed component height. Otherwise the globe uses a square aspect ratio.
className	`string`	-	-
isDarkMode	`boolean`	-	-