threesmap

threesmap

纯 three.js 实现的 Vue 3 3D 地图组件，不依赖 TresJS / R3F 等任何 Vue 3D 框架。 内置示例数据与贴图，零配置即可运行；支持省 → 市下钻、区县信息卡与企业布点聚合。

• 纯 three.js，不侵入你的技术栈
• 内置安徽省示例 GeoJSON + 8 张贴图，装完即用（无配套法线贴图）
• 下钻：点击区域进入该市的区县视图，面包屑返回，镜头平滑过渡
• 企业布点：DOM 标点 + 悬浮卡片 + 点击聚焦 + 按屏幕像素自动聚合
• 图层开关：云层 / 边界流光 / 底部光环 / 数据柱 / 热力图 / 企业打点 / 是否允许下钻
• 完整 TypeScript 类型；卸载时自动释放贴图、几何体、材质、渲染器与 DOM

安装

npm i threesmap
npm i three vue          # 这两个是 peer 依赖，需要你自己装

three 的版本区间为什么不用 ^0.160：semver 对 0.x 的 caret 只允许补丁位变化， ^0.160.0 实际等于 >=0.160.0 <0.161.0，会把 0.161 ~ 0.18x 全挡在外面。

本包只提供 ESM 产物，需通过打包工具使用：Vite（含 Vitest / Nuxt 等）、 webpack 5+、rspack、esbuild 均可；内置贴图与示例数据是按需加载的独立分包， 因此不支持 webpack 4 及更早版本，也不支持 require() 直接引入。

不想走 npm？ 也可以把 src/ThreeMap/ 整个目录拷进你的工程直接用 （import ThreeMap from "@/components/ThreeMap/ThreeMap.vue"）。该目录是自包含的： 只需 three / gsap / d3-geo，零额外构建配置，热力图引擎已 vendored 在内。 细节与注意事项见 src/ThreeMap/README.md。

产物结构

内置贴图与示例数据不进主产物，用到才下载：

• 不传任何 props 时，主产物只有百 KB 量级的代码，贴图与大地图数据都是网络按需加载；
• 想连这 1.4 MB 内置资产都不要？用精简入口 threesmap/core（约 104 KB，零内置数据与贴图）：

// 换省份 / 换国家的业务侧推荐：不会为用不到的内置安徽资产买单
import ThreeMap from "threesmap/core";
import "threesmap/style.css"; // 样式与主入口共用同一份
// 必须自己传 mapData（贴图可选），未传时组件给出开发期告警

不想经 npm、想把源码整目录拷进项目？差异说明见 src/ThreeMap/README.md——除导入路径与样式引入方式外，用法与本手册一致。

30 秒跑通

<template>
  <div class="map-page">
    <ThreeMap />
  </div>
</template>

<script setup lang="ts">
import ThreeMap from "threesmap";
import "threesmap/style.css";
</script>

<style scoped>
/* 父容器必须有明确高度：组件内部是 100% × 100% */
.map-page {
  width: 100%;
  height: 100vh;
}
</style>

就这一步。不传任何 props 时用的是内置的安徽省数据与贴图。

功能导航

0. 数据契约

这一节是最容易踩坑的地方：配错了组件不会报错，只是"那块东西不显示"。 好在开发期组件会直接把这些情况打到控制台（前缀 [ThreeMap]），照着提示改即可。

key 规则

三类业务数据的 key 统一为 adcode：

区域名（properties.name）只用于展示（地图标签、卡片标题），不做 key—— 名称会跨市重名（比如多个"城关区"），adcode 才是稳定标识。 误把名称当 key 时控制台会给出 map-hover-data 的 key 应该是 adcode（如 "340100"），但检测到名称 key：… 的提示， 并列出当前层可用的 adcode 示例，直接照抄即可。

量级约定

顶面贴图

贴图必须严格按顶层 GeoJSON 的经纬度包围盒裁剪（含所有岛屿、无留白、纵横比与投影后一致）—— UV 是按包围盒归一化映射的，范围不一致就会"只贴对一部分"。 想先确认几何对不对，把 textures.map 传 null 用纯色顶面看一眼最快。

什么时候传数据

mapData / subMapData / 悬浮卡 / 企业数据要求初始化时传入； 飞线与热力图支持运行时替换（见 API 速查 的"动态更新"）， 其余数据如需运行时更换，用实例方法 setSubMapData，或重建组件。

1. 基础地图

传了就用你的，没传的继续用内置默认值。

<template>
  <ThreeMap
    :map-data="myMapData"
    :map-hover-data="myHoverData"
    :textures="{ map: myMapTexture }"
    :depth="6"
    background="#fff5e8"
  />
</template>

<script setup lang="ts">
import ThreeMap from "threesmap";
import type { CityGeoJSON, CityInfo } from "threesmap";
import "threesmap/style.css";

import myMapJson from "@/data/myMap.json";
import myMapTexture from "@/assets/my_map.png";

const myMapData = myMapJson as unknown as CityGeoJSON;
// key 是**要素的 adcode**（不是区域名），内容决定悬浮卡文字与数据柱高度
const myHoverData: Record<string, CityInfo> = {
  340100: { population: 963, gdp: "1.27万亿", area: "11445平方公里" },
};
</script>

GeoJSON 数据要求

• 必须是 FeatureCollection；几何支持 MultiPolygon 与 Polygon，GeometryCollection 会被自动展平（内部统一成 MultiPolygon）
• properties 至少要提供：

贴图

textures 可以只覆盖部分 key，其余继续用内置图——被覆盖的 key 不会去下载对应的内置图：

import myMapTexture from "@/assets/my_map.png";

// 只换地图主贴图：其余 7 张内置图照常按需下载
<ThreeMap :textures="{ map: myMapTexture }" />

全部 9 个 key：map、normalMap、barQuan、bottomGaoguang、bottomGrid、bottomGridBlack、bottomRotation1、bottomRotation2、cloud。 内置示例只提供其中 8 个（normalMap 为空：示例没有配套法线贴图）； 需要程序化拿到内置图片地址时用 loadDefaultTextures()（异步，可只取子集）：

import { loadDefaultTextures } from "threesmap";

const textures = await loadDefaultTextures(["map", "cloud"]); // 只想复用这两张
// <ThreeMap :textures="{ ...textures, bottomGrid: null }" />  null = 显式禁用某张内置贴图

每个 key 的 wrap / colorSpace / repeat 属于材质固有配置，已内置，外部只需给图片地址。地址支持相对路径、import 出来的资源 URL、远程 http(s)、data:、blob:。

2. 图层开关

options 支持响应式变更（内部 deep watch 同步显隐），配合内置的 MapToolbar 可以直接做出开关工具栏：

<template>
  <div class="map-page">
    <ThreeMap :options="options" />
    <MapToolbar v-model="options" />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ThreeMap, MapToolbar } from "threesmap";
import type { ThreeMapOptions } from "threesmap";
import "threesmap/style.css";

const options = ref<ThreeMapOptions>({
  cloud: true,
  boundary: true,
  rotation: true,
  bar: false,
  heat: false,
  drillDown: true,
});
</script>

所有图层都在初始化时一次性构建，开关只切 visible，所以切换是即时的、没有任何加载。 代价是：想让热力图后续能开关，必须在初始化时就传入 heatmapData；传 null 表示完全不创建。

3. 下钻

点击某个市即进入该市的下钻态：场景里只保留该市的区县，其余市级要素被移除。

下钻态的点击不再切层级：点区县只切换本地高亮（再点同一区县取消），并抛出 @sub-city-click（见下方事件表）；点地图外空白处会把视角飞回当前层的默认位置。

需要什么数据

不传任何数据时，组件用内置的安徽示例数据直接渲染（零配置可用）。一旦传了自己的 mapData，内置示例业务数据（下级区县 / 城市数据 / 热力图）全部不再兜底——省份对不上，需要哪份就显式传哪份；换省份 = 成对替换 mapData 与 subMapData（或替换 assets/ 里的两个 JSON），组件内部没有任何省份/城市字面量。

配置

<ThreeMap
  :map-data="myMapData"
  :sub-map-data="mySubMapData"
  :drill-down-config="drillConfig"
  @city-click="onCityClick"
  @sub-city-click="onSubCityClick"
  @level-change="onLevelChange"
/>

import type { DrillDownConfig } from "threesmap";

const drillConfig: DrillDownConfig = {
  topLevelName: "安徽省",              // 面包屑里的顶层名称，默认「全省」
  cameraDuration: 900,                // 镜头过渡时长 ms，默认 800
};

事件

@level-change 常用于让业务自己的覆盖层跟着层级显隐——比如图层工具栏只该在省级显示：

<ThreeMap :options="options" @level-change="onLevelChange" />
<MapToolbar v-if="levelState.level === 'province'" v-model="options" />

import { ref } from "vue";
import type { LevelState } from "threesmap";

const levelState = ref<LevelState>({ level: "province", city: null });
const onLevelChange = (state: LevelState) => (levelState.value = state);

用外部 UI 驱动层级

组件实例暴露了一组方法，配合 ref 即可用任意自己的按钮/菜单控制层级：

<template>
  <ThreeMap ref="mapRef" :sub-map-data="mySubMapData" />
  <button @click="mapRef?.drillDown(340100)">进入合肥市</button>
  <button @click="mapRef?.drillUp()">返回</button>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { ThreeMap } from "threesmap";

const mapRef = ref<InstanceType<typeof ThreeMap> | null>(null);
</script>

动态更新

哪些数据能"改了就生效"、哪些必须重新挂载组件，一览：

4. 下级区域信息

下钻后鼠标悬浮区县会弹出信息卡，内容由 subMapHoverData 驱动，key 是 adcode：

<ThreeMap
  :sub-map-data="mySubMapData"
  :sub-map-hover-data="subMapHoverData"
  :drill-down-config="{ districtFields: { population: '人口(万)', enterprises: '企业数' } }"
/>

const subMapHoverData = {
  340102: { population: 146, enterprises: 46 },   // 瑶海区
  340103: { population: 102, enterprises: 38 },   // 庐阳区
};

// districtFields 的对象插入顺序 = 卡片里的渲染顺序
// 这里只显示 population 与 enterprises，其余字段忽略

• subMapHoverData 的值是自由字段对象，想展示哪些由 districtFields 决定
• 某区域没有配数据时，信息卡只显示名称（不会报错）

5. 企业布点

企业数据以 adcode 为 key，只有在对应要素可见时才渲染。两层各有一套数据：

两者共用一个开关 options.enterprise（默认开启），关闭时标点、标签、悬浮卡与簇列表一并隐藏。

<ThreeMap
  :sub-map-data="mySubMapData"
  :enterprise-data="enterpriseData"
  :drill-down-config="{
    enterpriseFields: { industry: '行业', scale: '规模', employees: '员工数' },
    cluster: true,
    clusterRadius: 46,
  }"
  @enterprise-click="onEnterpriseClick"
/>

import type { Enterprise } from "threesmap";

const enterpriseData: Record<string, Enterprise[]> = {
  340102: [
    { id: 1, name: "某电子信息公司", lng: 104.115, lat: 30.601,
      industry: "电子信息", scale: "大型", employees: 860 },
  ],
};

字段要求

• 缺必需字段或经纬度非法的记录会被跳过并告警，不会中断整层渲染
• 落在当前市范围外的企业会被裁掉，避免脏点飘在屏幕外
• key 必须是 adcode，不是区县名（区县名会跨市重名）。写错时开发期会输出警告

交互行为

聚合

• 判据是屏幕像素距离（默认 44px），所以镜头拉近后标点会自然散开，不需要"展开"动画
• 相机下探到该层最近距离后，成员数 ≤ 3 的小簇会直接展开为独立标点——避免出现"只剩两三家却怎么也拆不开、看不到是谁"的死角
• cluster: false 可整体关闭聚合，所有企业都渲染为独立标点

点击事件

import type { Enterprise, EnterpriseClickContext } from "threesmap";

const onEnterpriseClick = (enterprise: Enterprise, ctx: EnterpriseClickContext) => {
  console.log(enterprise.name, ctx.district, ctx.city);
  // ctx = { district: "瑶海区", city: { adcode: 340100, name: "合肥市" } }
};

6. 迁徙飞线

只传一个数组就能出效果，端点是 { name, lng, lat }：

<ThreeMap :fly-line-data="flyLineData" />

const flyLineData = [
  { from: { name: "芜湖市", lng: 118.38, lat: 31.33 },
    to:   { name: "合肥市", lng: 117.28, lat: 31.86 }, value: 1280 },
  // ...再放几条
];

效果构成：抛物线拱起的管状弧线（拱高随起终点距离变化）+ 沿线循环前进的流动亮带（各线相位错开）+ 起点呼吸圆环 / 终点光点。鼠标悬浮到线上会提亮该线、压低其余线，并弹出提示。

配色可配（5 个色位，只传要改的）：

<ThreeMap
  :fly-line-data="flyLineData"
  :fly-line-colors="{ track: '#7dd3fc', flow: '#0ea5e9', core: '#38bdf8' }"
/>

取色规律：浅色底图上"更亮"表达不出强度，只能用"更饱和"，所以默认是浅青轨道 + 饱和青流光。 如果底图换成深色，整组改霓虹色（如 track: '#0e7490', flow: '#22d3ee'）会更好看。

提示的两种扩展方式：

// 1) 传函数，完全接管内容
const flyLineTip = (item) =>
  `<b>${item.from.name} → ${item.to.name}</b><br/>运量 ${item.value} 人次`;

/* 2) 不改组件，直接覆盖内置提示元素的样式 */
.tm-fly-tip { border-radius: 4px; }

内置提示元素带 tm-fly-tip class 与 data-from / data-to / data-value 属性，方便外部取用。

飞线支持运行时替换：改 flyLineData prop 或调 setFlyLineData()，组件会重建该图层； 改 flyLineColors 也会用新配色重建。飞线只在顶层出现，下钻态自动隐藏。

API 速查

Props

cameraView 用方位角 / 仰角描述镜头方向，比 xyz 直观：

<!-- 下面这组就是内置默认视角（不传 cameraView 时即为此）；要调就改这几个数 -->
<ThreeMap :camera-view="{ azimuth: 20.6, elevation: 36.2, scale: 1 }" />

对所有层级生效（入场画面 / 下钻与返回 / 点空白复位 / 点聚合簇推近），所以切换层级时视角保持一致； 距离部分仍按各层范围自适应，scale / distance 只是统一的倍数。 不传则完全沿用内置默认视角，行为不变。

Events

实例方法（defineExpose）

完整签名与用法见 用外部 UI 驱动层级。 组件卸载时会自动释放全部资源（含 WebGL 上下文）；dispose() 之后这些方法都会直接返回。

包的其它导出

除组件外，threesmap 还导出了内置数据与底层工具，便于按需复用：

import {
  // 内置数据（可用于兜底或参考格式）
  defaultMapHoverData, defaultHeatmapData,
  defaultTextureKeys,        // 内置贴图的 key 清单（8 个，不含 normalMap）
  defaultOptions,
  loadDefaultTextures,       // 按需加载内置贴图地址，返回 Promise（每个 key 一个懒加载分包）
  loadDefaultMapData,        // 异步加载内置省级 GeoJSON，返回 Promise（独立分包）
  loadDefaultSubMapData,     // 异步加载内置区县数据，返回 Promise（独立分包）
  // 底层工具
  loadTexture, textureLoaders, createThreeMap,
  buildLevelData, computeLevelMetrics, indexByParent,
  projectFeatureBounds, defaultResolveChildren,
} from "threesmap";

完整清单见 src/ThreeMap/index.ts。createThreeMap 是纯 three.js 的场景工厂，脱离 Vue 也能用。

注意事项

1. 父容器必须有明确高度，否则画布高度为 0（组件内部是 100% × 100%）。
2. 组件在挂载后异步批量加载贴图，全部就绪才创建场景。单张贴图失败（404 / 无 CORS / 超时 15s）只会丢掉那一张，不影响其余贴图与地图渲染。
3. 下钻态会强制打开边界流光、关闭云层 / 数据柱 / 热力图（那套光效是按省级尺度搭建的，拉近后只剩几道巨大弧线，很突兀）；返回时按你的开关原样还原。
4. 体积：运行时入口约 119 KB（已含内置热力图引擎）；8 张内置贴图（约 1.4 MB） 与两级 GeoJSON 都是按需下载——自带地图与贴图的项目运行时不请求这些示例资源 （见上文「产物结构」）。想连这些资产都不装，用精简入口 threesmap/core（约 104 KB）。
5. 内置的 8 张贴图是示例资源，商用请替换成你自己的图片。 内置贴图以 data: URL 形式加载，若站点配置了 CSP，需保证 img-src 允许 data:； 自己传 URL 的贴图不受此影响。
6. 组件卸载时会自动释放贴图、几何体、材质、渲染器、WebGL 上下文、控制器监听与注入的 DOM。 GL 上下文不会被残留（浏览器对同时存活的上下文数量有上限，反复挂载 / 卸载也不会耗尽）。
7. 开销只在需要时发生：CSS2D 标注层是按需刷新的——相机静止、且标注没有增删或显隐变化时， 一整帧不写一次标注 DOM；悬停判定与渲染帧对齐（pointermove 只记最新坐标，每帧最多判定一次）。 实测相机静止 5 秒的样式重算次数为 0（旧行为是每帧全量刷新，约 293 次）。
8. 畸形数据不会白屏、也不会抛异常：坐标缺失 / 非法、centroid 与 center 双缺、 coordinates 为空、甚至 mapData 是空数组——都只会跳过对应内容并在控制台告警， 其余部分照常渲染。
9. 直接用底层 createThreeMap（脱离 Vue）时，用完必须调 dispose()： 它会释放 GL 上下文与控制器监听。dispose() 之后该实例的所有方法都会直接返回， 不会再创建图层或重新挂载数据。

控制台告警速查

组件只在开发期告警、从不抛异常中断渲染（前缀统一为 [ThreeMap]）。常见几条：

不想翻文档？让 AI 读它

仓库根目录的 CLAUDE.md 是面向 AI 助手的项目入口：包含技术栈与约束、 目录地图、常用命令、开发流程（OpenSpec 变更工作流）、编码与测试规范、发布流程， 以及一张"易踩坑清单"。把仓库丢给 AI 时，让它先读这个文件即可，省去逐篇翻 README。