简介

yudada-map3d 是一个基于 Vue 3 + Three.js 的 3D 省份地图组件库，用于在网页中快速渲染可配置的 3D 省级地图（默认示例为湖南省，也支持传入任意省份/地区的 GeoJSON）。

安装

项目需要 Vue 3 环境，并安装 Three.js、GSAP、TWEEN 作为依赖：

# npm
npm install yudada-map3d three gsap @tweenjs/tween.js

# 或 pnpm
pnpm add yudada-map3d three gsap @tweenjs/tween.js

快速上手示例

下面示例演示在 Vue 3 项目中使用 yudadaMap3D 组件渲染一个省级 3D 地图。

在组件中使用

<template>
  <div class="map-wrapper">
    <yudadaMap3D :geoJson="geoJson" :config="config" />
  </div>
</template>

<script setup>
import { ref } from "vue"
import yudadaMap3D from "yudada-map3d"
// 方式一：本地静态文件（构建后放到 public 下）
const geoJson = "./data/map/湖南省.json"
// 方式二：你也可以提前请求好数据再传入：const geoJson = geoJsonObject

const config = ref({
  camera: {
    finalPosition: { x: 111.33, y: 23.0, z: 9.73 }, // 相机最终位置
    startOffset: { x: -25, y: -16, z: 26 }, // 进场动画起始偏移
    introDuration: 3, // 进场动画时长（秒）
  },
  statsVisibel: false, // 关闭左上角性能统计
  axesVisibel: true, // 是否显示坐标轴
  controls: {
    enableDamping: true,
    maxPolarAngle: (Math.PI / 2) * 0.98,
  },
  label: {
    className: "map-32-label", // 自定义标签样式类名
    // getText: (properties) => properties.name, // 自定义标签文本
  },
  material: {
    topColor: 0xb4eeea,
    sideColor: 0x123024,
    textureScale: 0.128,
  },
  showDecorations: true, // 是否显示中心光圈、旋转点、背景等装饰
  debugGui: true, // 是否开启右上角调试面板（按 G 键显示/隐藏）
})
</script>

<style>
.map-wrapper {
  width: 100%;
  height: 100vh;
}

.map-32-label {
  font-size: 10px;
  color: #fff;
}
</style>

组件参数说明

组件名称：yudadaMap3D

1. 基本 Props

• geoJson（必填）

  • 类型: Object | string
  • 说明: 省份/区域 GeoJSON 数据。
    • 传 Object：直接使用该对象渲染。
    • 传 string：视为 URL，组件内部通过 THREE.FileLoader 异步加载。

• textures（可选）

  • 类型: Object
  • 说明: 自定义贴图资源，不传则使用组件内置默认贴图。
  • 可用字段:
    • topMap: 地图顶面贴图
    • fxMap: 顶部叠加特效贴图
    • rotatingAperture: 中心旋转光圈贴图
    • rotatingPoint: 中心旋转点贴图
    • circlePoint: 原点贴图
    • sceneBg: 场景背景贴图

• config（可选）

  • 类型: Object
  • 说明: 组件的所有可配置参数入口，未设置的字段会使用内置默认值。

2. config 详细配置

2.1 地图基础

• config.centerXY

  • 类型: [number, number]
  • 默认: 根据 GeoJSON 自动计算
  • 说明: 地图中心点坐标，一般无需手动设置。

• config.bottomZ

  • 类型: number
  • 默认: -0.2
  • 说明: 地图底部在 z 轴上的高度，用于微调整体高度。

• config.extrude（挤出参数）

  • depth：拉伸高度，默认 0.2
  • bevelEnabled：是否启用倒角，默认 true
  • bevelSegments：倒角段数，默认 1
  • bevelThickness：倒角厚度，默认 0.1

2.2 材质与贴图

• config.material

  • topColor：顶面颜色（十六进制数值），默认 0xb4eeea
  • sideColor：侧面颜色，默认 0x123024
  • topOpacity：顶面不透明度，默认 1
  • sideOpacity：侧面不透明度，默认 0.9
  • textureScale：顶面贴图缩放，默认 0.128（可配合 GUI 动态调节）

• config.border（边线）

  • border.top.*：顶边线
    • color、linewidth、transparent、depthTest、zOffset
  • border.bottom.*：底边线
    • color、linewidth、depthTest、zOffset

2.3 标签（城市/区域名称）

• config.label
  • className：标签 DOM 的 class 名称（用于自定义样式），默认 "map-32-label"
  • visible：是否显示标签，默认 true
  • getText(properties)：自定义标签文本函数，默认返回 properties.name

2.4 光柱效果

• config.lightPillar
  • visible：是否显示光柱，默认 true
  • z：光柱底部 z 高度，默认 0.31
  • heightMin：光柱最小高度，默认 0.4
  • heightMax：光柱最大高度，默认 1.4
  • scaleFactor / markedLightPillarOptions：透传给内部光柱 hook 的高级参数（一般保持默认即可）。

2.5 相机与进场动画

• config.camera
  • fov：相机视角，默认 38
  • near / far：近裁剪面/远裁剪面，默认 0.001 / 90000000
  • finalPosition：进场动画结束后的相机位置 { x, y, z }
  • startOffset：进场动画起始相机相对 finalPosition 的偏移 { x, y, z }
  • introDuration：进场动画时长（秒），默认 3

2.6 控制器与其他

• config.controls（OrbitControls 配置）

  • enableDamping：是否开启阻尼，默认 true
  • maxPolarAngle：最大俯视角，默认约为接近 90°

• 其他配置

  • axesVisibel：是否显示三维坐标轴，默认 true
  • statsVisibel：是否显示性能统计（FPS 面板），默认 false
  • showDecorations：是否显示中心光圈、旋转点、背景等装饰元素，默认 true
  • debugGui：是否开启右上角调试 GUI 面板，默认 false

小技巧：当 debugGui 为 true 时，在页面中按 G 键 可以显示 / 隐藏右上角的 GUI 面板，方便在开发阶段实时调节相机和材质参数。