@lius1314/china-map-3d-designer

基于 Three.js 的 3D 中国地图可视化设计器 SDK。内置可视化设计器 UI（图层面板、属性配置、数据编辑、主题预设），同时也可作为纯渲染组件嵌入到任意 React 项目中。

特性

• 3D 地图渲染：可视化省级/市级地图，支持双击下钻
• 设计器模式：实时编辑场景配置（顶面、侧面、边界、粒子等），所见即所得
• 数据驱动：外部注入数据驱动柱图、飞线、散点、标签、悬浮卡片
• 主题预设：内置多套精选主题，一键切换
• 配置导出/导入：将设计结果导出为 JSON，供生产环境加载
• 交互回调：悬浮、单击、下钻均暴露回调，方便联动外部组件

安装

从 npm 安装

npm install @lius1314/china-map-3d-designer

本地 tgz 包安装（离线场景）

npm install file:./@lius1314-china-map-3d-designer-x.x.x.tgz

快速开始

1. 引入样式（必须）

import '@lius1314/china-map-3d-designer/style.css'

2. 纯展示模式（生产环境推荐）

import { ChinaMap3DDesigner } from '@lius1314/china-map-3d-designer'
import '@lius1314/china-map-3d-designer/style.css'
import configJson from './chinamap3d-config.json'
import type { AppConfig, MapDataInput } from '@lius1314/china-map-3d-designer'

const mapData: MapDataInput = {
  regions: [
    { name: '广东省', value: 95 },
    { name: '北京市', value: 87 },
    { name: '上海市', value: 91 },
  ],
}

export default function MapPage() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <ChinaMap3DDesigner
        initialConfig={configJson.config as AppConfig}
        mapData={mapData}
        enableDrillDown={false}
        showBreadcrumb={false}
      />
    </div>
  )
}

3. 设计器模式（内网/开发环境）

import { ChinaMap3DDesigner } from '@lius1314/china-map-3d-designer'
import '@lius1314/china-map-3d-designer/style.css'

export default function DesignerPage() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ChinaMap3DDesigner
        editable={true}
        showEditModeToggle={false}
      />
    </div>
  )
}

打开后点击右上角「配置」按钮导出 chinamap3d-config.json，将其放入项目并通过 initialConfig 传入即可还原设计结果。

Props 说明

| Prop | 类型 | 默认值 | 说明 | |------|------|--------|------| | editable | boolean | false | 是否开启设计器编辑模式 | | showLayerPanel | boolean | true | 是否显示左侧图层树面板（仅 editable=true 有效） | | showPropertyPanel | boolean | true | 是否显示右侧属性配置面板（仅 editable=true 有效） | | showToolbar | boolean | true | 是否显示顶部工具栏（仅 editable=true 有效） | | showDataPanel | boolean | true | 是否显示数据编辑面板（仅 editable=true 有效） | | showEditModeToggle | boolean | true | 是否显示内置「进入/退出编辑」浮动切换按钮 | | showBreadcrumb | boolean | true | 是否显示左上角下钻路径面包屑 | | initialConfig | AppConfig | — | 初始场景配置（从设计器导出的 JSON 中取 config 字段） | | initialData | MapDataInput | — | 初始地图数据（优先级低于 mapData） | | initialRegion | { adcode: number; name: string } | — | 初始显示区域，不填默认展示全国；示例：{ adcode: 440000, name: '广东省' } | | enableDrillDown | boolean | true | 是否允许双击下钻到子区域 | | mapData | MapDataInput | — | 外部受控数据（散点/柱图/飞线/标签/悬浮卡片） | | onDataChange | (data: MapDataInput) => void | — | 数据编辑面板内容变化回调 | | onConfigChange | (config: AppConfig) => void | — | 场景配置变化回调（可用于持久化） | | onRegionClick | (info: RegionClickInfo) => void | — | 单击省份/城市回调 | | onRegionHover | (info: RegionHoverInfo \| null) => void | — | 鼠标悬浮省份/城市回调，null 表示移出 | | onRegionDrillDown | (info: RegionClickInfo) => void | — | 双击下钻成功后回调（enableDrillDown=false 时不触发） | | className | string | "" | 容器 className | | style | React.CSSProperties | — | 容器 style |

数据注入（MapDataInput）

通过 mapData prop 或 initialData prop 注入，驱动地图上的所有数据图层。

interface MapDataInput {
  regions?:    RegionDataItem[]   // 省份/城市数值 → 驱动柱图、散点
  flyLines?:   FlyLineItem[]      // 飞线
  labels?:     LabelItem[]        // 文字标签
  clickCards?: ClickCardItem[]    // 悬浮卡片（鼠标悬浮时展示）
}

RegionDataItem — 区域数值

interface RegionDataItem {
  name: string           // 省份/城市名称，需与地图区划名称完全一致
  value: number          // 数值（建议归一化到 0-100）
  extra?: Record<string, unknown>  // 自定义附加字段
}

名称示例："广东省" "北京市" "上海市" "内蒙古自治区" "新疆维吾尔自治区"

FlyLineItem — 飞线

interface FlyLineItem {
  from: string           // 起点省份/城市名称
  to: string             // 终点省份/城市名称
  weight?: number        // 权重（越大线越粗，可选）
}

LabelItem — 文字标签

interface LabelItem {
  name: string           // 匹配的省份/城市名称
  text?: string          // 显示文本（不填则用 name）
}

ClickCardItem — 悬浮卡片

鼠标悬浮该区域时，tooltip 自动展示卡片内容，优先级高于默认数值展示。

interface ClickCardItem {
  name: string           // 匹配的省份/城市名称
  title?: string         // 卡片标题
  metrics?: {            // 指标列表
    label: string
    value: string | number
    unit?: string
  }[]
  html?: string          // 自定义 HTML（优先级高于 metrics）
}

完整示例

import type { MapDataInput } from '@lius1314/china-map-3d-designer'

const mapData: MapDataInput = {
  regions: [
    { name: '广东省', value: 95 },
    { name: '北京市', value: 87 },
    { name: '上海市', value: 91 },
    { name: '浙江省', value: 79 },
    { name: '四川省', value: 70 },
  ],
  flyLines: [
    { from: '广东省', to: '北京市' },
    { from: '广东省', to: '上海市' },
    { from: '北京市', to: '黑龙江省' },
  ],
  labels: [
    { name: '广东省', text: '粤' },
    { name: '北京市', text: '京' },
  ],
  clickCards: [
    {
      name: '广东省',
      title: '广东省 · 数据看板',
      metrics: [
        { label: 'GDP（亿元）', value: '129118', unit: '亿' },
        { label: '人口', value: '12684', unit: '万人' },
        { label: '增速', value: '4.8', unit: '%' },
      ],
    },
  ],
}

SDK 也导出了一套内置示例数据，可直接使用：

import {
  CHINA_PROVINCES,    // 31个省级区划示例数值
  DEFAULT_FLY_LINES,  // 示例飞线
  DEFAULT_LABELS,     // 示例标签
  DEFAULT_CARDS,      // 示例悬浮卡片
} from '@lius1314/china-map-3d-designer'

回调类型

RegionHoverInfo

interface RegionHoverInfo {
  name: string      // 区域名称
  adcode: number    // 行政区代码
  value: number     // 当前区域数据值
  x: number         // 鼠标视口 X 坐标（可用于自定义 Tooltip 定位）
  y: number         // 鼠标视口 Y 坐标
}

RegionClickInfo

interface RegionClickInfo {
  name: string
  adcode: number
  value?: number
}

场景配置（AppConfig）

AppConfig 是设计器导出 JSON 中 config 字段的完整类型，包含以下 9 个图层的配置：

| 字段 | 类型 | 说明 | |------|------|------| | global | GlobalConfig | 全局 / 后处理（背景色、Bloom、雾效、相机 FOV、自动旋转） | | baseScene | BaseSceneConfig | 底座场景（grid/water/hex/nebula/flywheel/energy 等类型，含粒子配置） | | topface | TopFaceConfig | 地图顶面（渐变色、悬浮高亮色、动画、菲涅尔、贴图） | | sideface | SideFaceConfig | 地图侧面（渐变色、厚度、流光动画） | | border | BorderConfig | 流光边界线（颜色、宽度、流速、辉光） | | scatter | ScatterConfig | 波纹散点（marker 类型、颜色、尺寸、速度） | | flyline | FlyLineConfig | 飞线（渐变色、速度、拖尾长度、飞行高度） | | bar | BarConfig | 3D 柱图（形状、渐变色、最大/最小高度、顶部标记） | | label | LabelConfig | 文字标签（颜色、尺寸、背景形状、字体） |

建议通过设计器 UI 调整后导出 JSON，而不是手写配置。

主题预设

SDK 内置多套精选主题，可通过 THEME_PRESETS 使用：

import { THEME_PRESETS, defaultConfig } from '@lius1314/china-map-3d-designer'
import type { AppConfig } from '@lius1314/china-map-3d-designer'

// 获取「暗夜霓虹」主题配置
const neonTheme = THEME_PRESETS.find(t => t.id === 'dark-neon')?.build()

<ChinaMap3DDesigner initialConfig={neonTheme} />

| 主题 ID | 主题名 | 风格描述 | |---------|--------|----------| | tech-blue | 科技蓝 | 深蓝背景 · 青色流光 · 经典大屏 | | deep-sea | 深海波光 | 星云背景 · 卫星贴图 · 深邃光影 | | dark-neon | 暗夜霓虹 | 霓虹紫粉 · 赛博朋克 · 六边形底 | | cyber-gold | 赛博金 | 暗金奢华 · 商务汇报大屏 | | aurora-night | 极光夜空 | 星空底座 · 绿紫极光 · 星云缭绕 | | 更多... | — | 在设计器工具栏「主题预设」中查看所有主题 |

配置导出与导入工作流

设计 → 导出

1. 在设计器中调整各图层参数，确认效果满意
2. 在数据面板填入示例数据（点击「示例」按钮快速填充）
3. 点击工具栏「配置」按钮，下载 chinamap3d-config.json

导出的 JSON 结构如下：

{
  "version": "1.0.0",
  "meta": { "name": "ChinaMap3D 配置", "createTime": "..." },
  "config": { /* AppConfig 完整配置 */ },
  "data": {
    "regions": [...],
    "flyLines": [...],
    "labels": [...],
    "clickCards": [...]
  }
}

导入到生产项目

import configJson from './chinamap3d-config.json'
import type { AppConfig, MapDataInput } from '@lius1314/china-map-3d-designer'

<ChinaMap3DDesigner
  initialConfig={configJson.config as AppConfig}
  initialData={configJson.data as MapDataInput}
/>

生产环境建议通过 API 获取数据后通过 mapData 实时注入，而非依赖静态 initialData。

高级用法

受控数据模式

通过 mapData prop 实现数据受控，适合与后端接口联动：

const [data, setData] = useState<MapDataInput>({ regions: [] })

useEffect(() => {
  fetchMapData().then(res => setData(res))
}, [])

<ChinaMap3DDesigner mapData={data} />

监听交互事件

<ChinaMap3DDesigner
  onRegionClick={(info) => {
    console.log('单击：', info.name, info.adcode, info.value)
    // 联动侧边栏、弹窗等
  }}
  onRegionHover={(info) => {
    if (info) {
      console.log('悬浮：', info.name, `(${info.x}, ${info.y})`)
    }
  }}
  onRegionDrillDown={(info) => {
    console.log('下钻到：', info.name, info.adcode)
  }}
/>

直接操控 Store（高级）

import { useDesigner } from '@lius1314/china-map-3d-designer'

// 在任意子组件中读取/修改场景状态
const { config, updateLayer, undo, redo } = useDesigner()

// 修改顶面颜色
updateLayer('topface', { hoverColor: '#ff0000' })

固定显示某省（不展示全国图）

<ChinaMap3DDesigner
  initialRegion={{ adcode: 440000, name: '广东省' }}
  enableDrillDown={false}
  showBreadcrumb={false}
/>

注意事项

1. 容器必须设置高度：组件默认填满父容器（height: 100%），父容器若无高度则地图无法显示
2. 样式必须引入：必须引入 @lius1314/china-map-3d-designer/style.css，否则设计器 UI 样式缺失
3. 名称精确匹配：regions、flyLines、labels、clickCards 中的 name 字段必须与地图区划名称完全一致（如 "广东省" 而非 "广东"、"内蒙古自治区" 而非 "内蒙古"）
4. 数据驱动原则：不传数据时地图不渲染任何柱图/飞线/散点，所有视觉元素均需通过 mapData 或 initialData 注入
5. transform 容器兼容：如果父容器使用了 transform（如 autofit 自适应方案），Tooltip 定位已自动处理，无需额外操作
6. 下钻限制：enableDrillDown=false 时禁用双击下钻，onRegionDrillDown 回调也不会触发

依赖

| 依赖 | 版本 | 说明 | |------|------|------| | three | ^0.184.0 | 3D 渲染核心 | | gsap | ^3.15.0 | 动画过渡 | | zustand | ^5.0 | 场景状态管理 | | lucide-react | ^1.17.0 | 图标库 | | react / react-dom | >=18 | peerDependency |

开发

# 启动独立设计器开发服务
npm run dev

# 构建 SDK 库文件（输出到 dist/）
npm run build:lib

# 打包为 tgz（供本地安装）
npm pack