tles-map3d

Vue 3 + Three.js 3D 行政区地图组件。组件包只提供稳定的渲染能力、类型和资源目录工具，地图数据、贴图、模型由业务项目自行管理。

安装

npm install tles-map3d

使用

<template>
  <div class="map-host">
    <Map3D v-bind="map3DResource320000" />
  </div>
</template>

<script setup lang="ts">
import { Map3D } from 'tles-map3d'
import 'tles-map3d/style.css'
import { map3DResource320000 } from '@/assets/map3d/320000'
</script>

<style scoped>
.map-host {
  width: 100%;
  height: 600px;
  background: #000;
}
</style>

资源说明

包内不内置 GeoJSON、大贴图和 GLB 模型，避免每个业务项目都下载用不到的资源。资源放在业务项目中，推荐固定为下面的结构：

src/assets/map3d/{adcode}/
├── geo.json
├── outline.json
├── district.json
├── heatmap.json             # 可选
└── index.ts                 # 资源统一导出

public/map3d/{adcode}/textures/
├── normal_map_{adcode}.png
├── satellite_texture_{adcode}.jpg
└── displacement_map_{adcode}.png # 可选

public/map3d/models/
└── *.glb / *.gltf

为什么这样放：

• geo.json / outline.json / district.json 放在 src/assets，便于 Vite 直接 import 成对象传给 Map3D。
• 贴图和模型放在 public，便于通过稳定 URL 传入，不会被组件库打进 JS。
• 多个项目只共享组件 npm 包，地图数据和业务模型由各项目自己管理。

资源脚本

安装组件包后，业务项目可以直接执行资源工具：

npm exec map3d-resources -- --help

如果当前项目还没有安装组件包，也可以临时执行：

npx -p tles-map3d map3d-resources --help

从旧项目一键迁移完整资源

这会复制 GeoJSON、法线贴图、卫星贴图和 GLB 模型，适合把已有项目的资源迁移到新目录规范。

cd 你的业务项目
npm exec map3d-resources -- copy \
  --adcode 320000 \
  --from /path/to/old-project \
  --target .

默认会从旧项目读取：

src/assets/geojson/{adcode}/
src/components/Bs/BgMap/3DMap/assets/
src/components/Bs/BgMap/3DMap/models/

如果旧项目目录不一致，可以显式指定：

npm exec map3d-resources -- copy \
  --adcode 320000 \
  --from /path/to/old-project \
  --from-geo-dir /path/to/geojson/320000 \
  --from-texture-dir /path/to/map3d/assets \
  --from-model-dir /path/to/models \
  --target .

复制后使用：

<script setup lang="ts">
import { Map3D } from 'tles-map3d'
import 'tles-map3d/style.css'
import { map3DResource320000 } from '@/assets/map3d/320000'

const models = [
  {
    modelName: 'tree',
    modelUrl: '/map3d/models/tree.glb',
    position: [118.78, 32.04],
  },
]
</script>

<template>
  <Map3D v-bind="map3DResource320000" :models="models" />
</template>

初始化一个新地区

这会从阿里 DataV 下载 geo.json / outline.json / district.json，并创建贴图和模型目录。新地区的卫星贴图、法线贴图如果当前没有现成文件，需要后续按项目已有制图流程生成后放入 public/map3d/{adcode}/textures/。

cd 你的业务项目
npm exec map3d-resources -- init --adcode 340000 --target .

如果只想创建目录和 index.ts，不下载 GeoJSON：

npm exec map3d-resources -- init --adcode 340000 --skip-download

生成后的 index.ts 会统一导出：

export const map3DResource340000 = {
  geoData,
  outlineData,
  districtGeoData,
  normalMapTexture: '/map3d/340000/textures/normal_map_340000.png',
  satelliteTexture: '/map3d/340000/textures/satellite_texture_340000.jpg',
  displacementMapTexture: '',
}

构建与发布

npm install
npm run build
npm publish

发布到公司私有仓库前，可以把 package.json 的 name 改成公司 scope，例如：

{
  "name": "@tles/map3d"
}

本地验证

npm install
npm run dev

本地 playground 需要你临时改 src/playground/main.ts，从业务项目导入一份真实 geoData 后再预览。