@armctory/3dmap

ECharts 3D 立体阴影地图组件与配置生成器。

开箱即用的 React 3D 立体地图组件，内置 ECharts geo 底图、外轮廓发光、伪 3D 挤出阴影效果。同时提供独立的 3D 阴影 series 生成器与 GeoJSON 工具函数，适用于自定义 ECharts option 的场景。

安装

# npm
npm install @armctory/3dmap echarts react react-dom

# pnpm
pnpm add @armctory/3dmap echarts react react-dom

echarts、react、react-dom 为 peer dependencies，使用方需自行安装。echarts-for-react 已作为内置依赖，无需额外安装。

快速开始

import * as echarts from 'echarts';
import { Map3D } from '@armctory/3dmap';
import guangdongGeo from './guangdong.json';

// 先注册地图
echarts.registerMap('guangdong', guangdongGeo);

export default function Demo() {
  return <Map3D mapName="guangdong" height={500} />;
}

组件 API - Map3D

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | mapName | 必填 地图名称（需与 echarts.registerMap 时使用的名称一致） | string | - | | height | 容器高度 | number \| string | 400 | | className | 容器类名 | string | - | | backgroundColor | 背景色 | string | 'transparent' | | areaColor | 地图区域填充色 | string | '#033251' | | borderColor | 区域边框色 | string | 'rgba(140, 206, 255, 0.6)' | | borderWidth | 区域边框宽度 | number | 2 | | outlineGlowScale | 外轮廓发光粗细缩放 | number | 1 | | outlineGlowColor | 外轮廓发光颜色 | string | '#2EA6FF' | | showLabel | 是否显示区域名称标签 | boolean | true | | labelColor | 标签文字颜色 | string | '#FFFFFF' | | labelFontSize | 标签字号 | number | 14 | | roam | 是否允许鼠标缩放/平移 | boolean | true | | zoom | 初始缩放比例 | number | 1.1 | | scaleLimit | 缩放限制 | { min?: number; max?: number } | { min: 0.5, max: 5 } | | shadow | 3D 阴影配置，传 false 关闭 | boolean \| Partial<Get3dShadowSeriesOptions> | true | | extraSeries | 额外的业务 series，追加到底图 series 之后 | EChartsOption['series'] | - | | option | 额外的 ECharts option（深合并） | EChartsOption | - | | onClick | 地图点击事件回调 | (params: any) => void | - | | onChartReady | 图表初始化完成回调 | (chart: ECharts) => void | - | | excludeFeatureNames | 排除的 feature 名称（不参与 3D 阴影与外轮廓） | string[] | ['十段线', '南海诸岛'] |

其余 echarts-for-react 的 props（如 notMerge、lazyUpdate、style 等）均支持透传。

Ref 方法

ref 直接透传到 echarts-for-react 组件，可使用其全部能力：

| 方法名 | 说明 | | -------------------- | ----------------- | | getEchartsInstance | 获取 echarts 实例 | | resize | 手动触发 resize |

独立 API - get3dShadowSeries

通用的 ECharts 3D 立体阴影系列生成器。输入地图外环经纬度数据，输出可直接拼接到 ECharts series 数组中的 custom series 配置，实现地图向下挤出的伪 3D 立体底座效果。

适用于不使用 Map3D 组件、需要在自定义 ECharts option 中手动组合 3D 阴影的场景。

import { get3dShadowSeries, extractPolygonRings, getTopLevel } from '@armctory/3dmap';

const geoJson = await fetch('/maps/guangdong.json').then((r) => r.json());
echarts.registerMap('guangdong', geoJson);

const topLevel = getTopLevel(geoJson) || 'city';
const mapRings = extractPolygonRings(geoJson, ['十段线', '南海诸岛'], topLevel);

const option = {
  geo: { map: 'guangdong', roam: true, itemStyle: { areaColor: '#033251' } },
  series: [
    // ... 其他 series
    get3dShadowSeries({ mapRings, shadowHeight: 40 }),
  ],
};

get3dShadowSeries 参数

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | mapRings | 必填 地图外环经纬度数据，每个区域一个外环数组，每个点为 [lng, lat] | number[][][] | - | | shadowHeight | 阴影向下延伸的像素高度 | number | 30 | | topColor | 阴影顶部颜色（最亮处） | string | 'rgba(131, 210, 255, 1)' | | bottomColor | 阴影底部颜色（最透明处） | string | 'rgba(131, 210, 255, 0.1)' | | z | series 的 z 层级值 | number | -1 | | id | series id | string | '地图3D立体阴影效果' | | name | series name | string | '地图3D立体阴影效果' | | silent | 是否不响应鼠标事件 | boolean | true |

GeoJSON 工具函数

| 函数 | 说明 | | --- | --- | | extractPolygonRings(geoJson, filters?, level?) | 从 GeoJSON 提取所有区域的外环坐标 | | filterByLevel(features, level?) | 按 properties.level 过滤 feature | | getTopLevel(geoJson) | 获取 GeoJSON 中最顶层的 level（province > city > district） | | deepMerge(target, source) | 深合并两个对象（用于合并 ECharts option） |

注意事项

1. 地图注册：使用组件前，需在应用入口或组件挂载前调用 echarts.registerMap(mapName, geoJson) 注册地图数据。
2. GeoJSON 格式：标准 GeoJSON FeatureCollection，每个 feature 的 properties.level 建议标记为 province / city / district。
3. 3D 阴影原理：通过将地图外环沿 Y 轴挤出指定高度并填充垂直渐变，模拟立体效果。shadowHeight 为像素单位，不随地图缩放变化。
4. 排除特殊区域：南海诸岛、十段线等 feature 默认被排除在 3D 阴影和外轮廓之外，可通过 excludeFeatureNames 自定义。

License

MIT