地图 - 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`	-	由使用者导入的 ECharts 核心实例（传入以支持 tree-shaking）。需要 `MapChart`、`ScatterChart`、`TooltipComponent` 以及通过 `echarts.use([...])` 注册的渲染器。
geoJson*	`MapGeoJson`	-	用于陆地底图的 GeoJSON `FeatureCollection`。
mapName	`string`	-	可选稳定的 ECharts 地图注册名称。当同一 GeoJSON 在多次挂载间被解析为新的对象实例，并且应复用同一个全局 ECharts 注册时，请设置此项。
data*	`T[]`	-	原始数据行。坐标/值/名称通过以下访问器读取。
lng*	`MapAccessor<T, number>`	-	经度访问器（`T` 的键或 `(row) => number`）。
lat*	`MapAccessor<T, number>`	-	纬度访问器（`T` 的键或 `(row) => number`）。
value*	`MapAccessor<T, number>`	-	值访问器 — 驱动气泡大小。
name	`MapAccessor<T, string>`	-	可选名称访问器 — 由默认工具提示使用。
minRadius	`number`	-	最小气泡半径，单位为 px。默认值：`6`。
maxRadius	`number`	-	气泡最大半径（px）。默认值：`26`。
bubbleSize	`(value: number) => number`	-	显式气泡半径 `(value) => px`。覆盖默认的 `minRadius`/`maxRadius` 缩放。
bubbleColor	`MapStyle<T, string>`	-	气泡填充颜色 — 常量或 `(row) => color`。默认使用图表蓝色。
bubbleBorderColor	`MapStyle<T, string>`	-	气泡边框颜色 — 常量或 `(row) => color`。默认值：`transparent`。
bubbleBorderWidth	`MapStyle<T, number>`	-	气泡边框宽度 — 常量或 `(row) => px`。默认值：`0`。
center	`[number, number]`	-	地图中心，格式为 `[longitude, latitude]`。默认自动适应。
zoom	`number`	-	缩放级别 — 乘以自动适配比例。默认值：`1.25`。
roam	`boolean`	-	启用拖拽平移和滚轮缩放。默认值：`false`。
projection	`MapProjection \| null`	-	地理投影。默认使用纬度限制的墨卡托投影（扁平的 2D 网页地图外观）。可传入其他 d3-geo 投影来覆盖默认，或传入 `null` 使用 ECharts 原始的等距圆柱投影。请使用稳定引用（模块级或记忆化）：每次渲染时的新对象都会重建视图并重置已漫游/缩放的地图。
showTooltip	`boolean`	-	显示 tooltip。默认值：`true`。
valueFormat	`(value: number) => string`	-	格式化默认工具提示的值。默认值：`toLocaleString()`。
tooltipFormatter	`(row: T) => string`	-	覆盖一行的工具提示内容。返回由 ECharts 自身工具提示渲染的 HTML 字符串。请谨慎使用：返回值会作为 HTML 注入。请对任何用户提供的字符串进行转义，以避免 XSS。
aspectRatio	`number \| string`	-	容器宽高比，格式为 `宽 / 高`（例如 `1.7` 或 `"16 / 9"`）。高度根据渲染宽度自动得出，使地图填满框架且无黑边。默认值为显示窗口的投影宽高比，使地图边缘对齐。传入 `height` 可改为固定像素高度。
height	`number`	-	以像素为单位的固定图表高度。设置后覆盖 `aspectRatio`。留空则按宽高比（默认值）调整大小，使地图填充容器。
className	`string`	-	-
isDarkMode	`boolean`	-	-

ChoroplethMap

Prop	Type	Default	Description
echarts*	`typeof echarts`	-	由使用者导入的 ECharts 核心实例（传入以支持 tree-shaking）。需要 `MapChart`、`VisualMapComponent`、`TooltipComponent` 以及通过 `echarts.use([...])` 注册的渲染器。
geoJson*	`MapGeoJson`	-	按值着色区域的 GeoJSON `FeatureCollection`。
mapName	`string`	-	可选稳定的 ECharts 地图注册名称。当同一 GeoJSON 在多次挂载间被解析为新的对象实例，并且应复用同一个全局 ECharts 注册时，请设置此项。
data*	`T[]`	-	原始数据行。区域键和值通过以下访问器读取。
name*	`MapAccessor<T, string>`	-	区域键访问器（类型为 `T` 的键或 `(row) => string`）。每行连接到 GeoJSON 要素，其 `nameProperty` 等于此值。
value*	`MapAccessor<T, number>`	-	值访问器 — 驱动区域的填充颜色。
nameProperty	`string`	-	用于连接的 GeoJSON 要素属性。默认值：`"name"`。现实世界的数据通常基于 ISO 代码属性（例如 `"iso_a2"`）匹配更可靠。
colorRange	`string[]`	-	顺序色带（低 → 高）。默认为 Kumo 分级统计图蓝色系，经调校以区别于无数据填充色。分布在连续渐变上。
noDataColor	`string`	-	没有匹配数据行的区域的填充。默认值为中性土地灰色。
showLegend	`boolean`	-	显示 visualMap 颜色图例。默认值：`false`。
showTooltip	`boolean`	-	显示 tooltip。默认值：`true`。
valueFormat	`(value: number) => string`	-	格式化默认工具提示的值。默认值：`toLocaleString()`。
tooltipFormatter	`(row: T) => string`	-	覆盖一行的工具提示内容。返回由 ECharts 自身工具提示渲染的 HTML 字符串。请谨慎使用：返回值会作为 HTML 注入。请对任何用户提供的字符串进行转义，以避免 XSS。
center	`[number, number]`	-	地图中心，格式为 `[longitude, latitude]`。默认自动适应。
zoom	`number`	-	缩放级别 — 乘以自动适配比例。默认值：`1.25`。
roam	`boolean`	-	启用拖拽平移和滚轮缩放。默认值：`false`。
projection	`MapProjection \| null`	-	地理投影。默认使用纬度限制的墨卡托投影（扁平的 2D 网页地图外观）。可传入其他 d3-geo 投影来覆盖默认，或传入 `null` 使用 ECharts 原始的等距圆柱投影。请使用稳定引用（模块级或记忆化）：每次渲染时的新对象都会重建视图并重置已漫游/缩放的地图。
aspectRatio	`number \| string`	-	容器宽高比，格式为 `宽 / 高`（例如 `1.7` 或 `"16 / 9"`）。高度根据渲染宽度自动得出，使地图填满框架且无黑边。默认值为显示窗口的投影宽高比，使区域边缘对齐。传入 `height` 可改为固定像素高度。
height	`number`	-	以像素为单位的固定图表高度。设置后覆盖 `aspectRatio`。留空则按宽高比（默认值）调整大小，使地图填充容器。
className	`string`	-	-
isDarkMode	`boolean`	-	-

GlobeMap

Prop	Type	Default	Description
landColor	`string`	-	阴影陆地的描边颜色。默认为中性的 Kumo 地图区域颜色。
landHatchSpacing	`number`	-	陆地阴影线之间的间距，单位为视图框像素。默认值：`10`。
oceanColor	`string`	-	陆地和经纬网后面的填充。默认值：Kumo 基础表面。
markers	`GlobeMapMarker[]`	-	绘制在陆地上方的地理位置点。点在水平线处淡出，背面的点被隐藏。
markerColor	`string`	-	默认标记填充颜色。默认为 Kumo 图表蓝色。
markerRadius	`number`	-	视图框中默认标记半径（像素）。默认值：`7`。
defaultRotation	`number[]`	-	初始地球旋转为 `[longitude, latitude, roll]`。
autoRotate	`boolean`	-	持续水平旋转地球。默认值：`false`。
autoRotateSpeed	`number`	-	水平自动旋转速度（度/秒）。默认值：`4`。
showGraticule	`boolean`	-	绘制经纬度引导线。默认值：`false`。
showTooltip	`boolean`	-	显示 Kumo 风格的标记 tooltip。默认值：`true`。
height	`number`	-	固定组件高度。否则地球仪将使用正方形宽高比。
className	`string`	-	-
isDarkMode	`boolean`	-	-