Maps 地图

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 "@lark-ui/core";

按需导出

import { BubbleMap, ChoroplethMap, GlobeMap } from "@lark-ui/core/components/chart";

用法

import { BubbleMap, ChoroplethMap, type MapGeoJson } from "@lark-ui/core";
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"
/>

Lark 可用性区域

无需 WebGL 即可绘制地理标记。带斜线的中性色陆地、透明海洋、在地平线处淡出的标记以及密集的地理辅助线，都呼应了 Lark 营销主页上的地球样式，同时让蓝色位置保持醒目。这些示意位置取自主要网络枢纽城市，并使用 IATA 代码；拖动地球或将其聚焦后，可用方向键查看隐藏半球上的点位。

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

自定义工具提示

当默认的名称/数值工具提示不够用时，请提供 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

属性	类型	默认值	说明
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 原生的等距圆柱投影绘图。请使用稳定的引用（模块级或经过 memo 缓存）：每次渲染都创建新对象会重建视图，并重置已平移或缩放的地图。
showTooltip	`boolean`	-	显示工具提示。默认：`true`。
valueFormat	`(value: number) => string`	-	默认工具提示中数值的格式化方式。默认：`toLocaleString()`。
tooltipFormatter	`(row: T) => string`	-	自定义某一行的工具提示内容。返回由 ECharts 自带工具提示渲染的 HTML 字符串。谨慎使用：返回值会作为 HTML 注入。请对任何用户提供的字符串进行转义，以避免 XSS。
aspectRatio	`number \| string`	-	容器宽高比，写作 `width / height`（例如 `1.7` 或 `"16 / 9"`）。高度由渲染后的宽度推导，使地图铺满画框而不留黑边。默认为显示窗口的投影宽高比，使陆地刚好铺满边缘。也可传入 `height` 来固定像素高度。
height	`number`	-	固定的图表高度，单位为像素。设置后覆盖 `aspectRatio`。留空则按宽高比计算尺寸（默认行为），使地图填满容器。
className	`string`	-	-
isDarkMode	`boolean`	-	-

ChoroplethMap

属性	类型	默认值	说明
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`）。每一行会与 `nameProperty` 等于该值的 GeoJSON 要素关联。
value*	`MapAccessor<T, number>`	-	数值访问器——用于决定区域的填充色。
nameProperty	`string`	-	用于关联的 GeoJSON 要素属性。默认：`"name"`。真实数据通常用 ISO 代码属性来匹配会更可靠（例如 `"iso_a2"`）。
colorRange	`string[]`	-	顺序色阶（由低到高）。默认为 Lark 分级设色地图的蓝色系，已调校为与无数据填充色明显区分。颜色分布在整条连续渐变上。
noDataColor	`string`	-	没有匹配数据行的区域所使用的填充色。默认为中性的陆地灰色。
showLegend	`boolean`	-	显示 visualMap 颜色图例。默认：`false`。
showTooltip	`boolean`	-	显示工具提示。默认：`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 原生的等距圆柱投影绘图。请使用稳定的引用（模块级或经过 memo 缓存）：每次渲染都创建新对象会重建视图，并重置已平移或缩放的地图。
aspectRatio	`number \| string`	-	容器宽高比，写作 `width / height`（例如 `1.7` 或 `"16 / 9"`）。高度由渲染后的宽度推导，使地图铺满画框而不留黑边。默认为显示窗口的投影宽高比，使区域刚好铺满边缘。也可传入 `height` 来固定像素高度。
height	`number`	-	固定的图表高度，单位为像素。设置后覆盖 `aspectRatio`。留空则按宽高比计算尺寸（默认行为），使地图填满容器。
className	`string`	-	-
isDarkMode	`boolean`	-	-

GlobeMap

属性	类型	默认值	说明
landColor	`string`	-	斜线填充陆地的描边颜色。默认为 Lark 地图区域的中性色。
landHatchSpacing	`number`	-	陆地斜线之间的间距，单位为 view-box 像素。默认：`10`。
oceanColor	`string`	-	陆地和经纬网底层的填充色。默认为 Lark 基础表面色。
markers	`GlobeMapMarker[]`	-	绘制在陆地上方的地理点位。接近地平线的点位会淡出，背面的点位会被隐藏。
markerColor	`string`	-	标记的默认填充色。默认为 Lark 图表蓝色。
markerRadius	`number`	-	标记的默认半径，单位为 view-box 像素。默认：`7`。
defaultRotation	`number[]`	-	地球的初始旋转，格式为 `[longitude, latitude, roll]`。
autoRotate	`boolean`	-	让地球持续水平旋转。默认：`false`。
autoRotateSpeed	`number`	-	水平自动旋转速度，单位为度/秒。默认：`4`。
showGraticule	`boolean`	-	绘制经纬辅助线。默认：`false`。
showTooltip	`boolean`	-	显示 Lark 样式的标记工具提示。默认：`true`。
height	`number`	-	固定的组件高度。否则地球会采用正方形宽高比。
className	`string`	-	-
isDarkMode	`boolean`	-	-