vue2-wzx-3dmap

一个基于 Vue 2 + Three.js 的 3D 地图可视化组件库，支持地图区域高亮、动画效果和粒子特效。

功能特点

• 🌍 支持中国地图和省份地图的 3D 展示
• 🎨 可自定义地图区域颜色、高亮效果和材质
• 🎮 支持轨道控制器，可自由调整视角和缩放
• ✨ 内置多种特效：
  • 粒子系统动画
  • 区域发光效果
  • 扫描线动画
  • 区域点击动画
• 🔥 响应式属性更新
• 📦 支持按需引入
• ⚡️ 基于 Vue 2 + Three.js，性能出色

安装

安装组件

# 使用 npm 安装
npm install vue2-wzx-3dmap

# 使用 yarn 安装
yarn add vue2-wzx-3dmap

安装依赖

本组件依赖以下库，请确保它们已安装：

# 必需依赖
npm install three@^0.150.0 gsap@^3.0.0

# 如果使用 yarn
yarn add three@^0.150.0 gsap@^3.0.0

注意：如果您的项目中已经安装了这些依赖，请确保版本兼容性。

使用方法

全局注册

import Vue from "vue";
import ThreeMap from "vue2-wzx-3dmap";

Vue.use(ThreeMap);

局部注册

import { ThreeMap } from "vue2-wzx-3dmap";

export default {
  components: {
    ThreeMap,
  },
};

基础用法

<template>
  <div class="container">
    <three-map
      :map-data="mapData"
      :area-data="areaData"
      :map-config="mapConfig"
      :active-colors="activeColors"
      @area-click="handleAreaClick"
    />
  </div>
</template>

<script>
import guangdongJson from "./guangdong.json";

export default {
  data() {
    return {
      // 地图数据
      mapData: guangdongJson,
      // 区域数据
      areaData: [],
      // 地图基础配置
      mapConfig: {
        backgroundColor: "#040D21",
        areaColor: "#24CFF4",
        lineColor: "#181818",
        glowLineColor: "#bff7ff",
        outerGlowColor: "#7cfffd",
        opacity: 0.6,
      },
      // 选中状态颜色
      activeColors: {
        topColor: "#ffc64d",
        sideColor: "#c87a16",
      },
    };
  },
  methods: {
    handleAreaClick(area) {
      console.log("点击区域:", area);
    },
  },
};
</script>

<style>
.container {
  width: 100%;
  height: 100%;
}
</style>

API 文档

Props

| 属性名 | 类型 | 默认值 | 必填 | 说明 | | --------------- | ------ | ---------- | ---- | ----------------- | | mapData | Object | - | 是 | 地图 GeoJSON 数据 | | areaData | Array | [] | 否 | 区域数据数组 | | mapConfig | Object | 见下方说明 | 否 | 地图配置项 | | activeColors | Object | 见下方说明 | 否 | 选中状态颜色配置 | | backgroundImage | String | - | 否 | 背景图片 URL | | cameraConfig | Object | 见下方说明 | 否 | 相机配置项 |

mapConfig 配置项

{
  backgroundColor: "#040D21",    // 背景色
  areaColor: "#24CFF4",         // 区域颜色
  lineColor: "#181818",         // 边界线颜色
  glowLineColor: "#bff7ff",     // 发光线条颜色
  outerGlowColor: "#7cfffd",    // 外发光颜色
  opacity: 0.6                  // 区域透明度
}

activeColors 配置项

{
  topColor: "#ffc64d",    // 选中时顶面颜色
  sideColor: "#c87a16"    // 选中时侧面颜色
}

cameraConfig 配置项

{
  position: { x: 0, y: 1, z: 1 },  // 相机位置
  fov: 35,                         // 视场角
  near: 0.1,                       // 近裁剪面
  far: 1000,                       // 远裁剪面
  minDistance: 0.5,                // 最小缩放距离
  maxDistance: 3,                  // 最大缩放距离
  minPolarAngle: 0,                // 最小极角
  maxPolarAngle: Math.PI / 2,      // 最大极角
  enablePan: false,                // 是否启用平移
  dampingFactor: 0.1,              // 阻尼系数
  autoRotate: false,               // 是否自动旋转
  autoRotateSpeed: 2.0             // 自动旋转速度
}

Events

| 事件名 | 说明 | 回调参数 | | ---------- | -------------------- | ------------------------------------------------- | | area-click | 点击区域时触发 | { name: string, code: string, isActive: boolean } | | area-hover | 鼠标悬浮在区域时触发 | { name: string, code: string } | | area-leave | 鼠标离开区域时触发 | { name: string, code: string } |

Methods

通过 ref 可以调用组件实例方法：

// 重置相机视角
this.$refs.threeMap.resetCamera();

// 聚焦到指定区域
this.$refs.threeMap.focusArea(areaName);

// 缩放控制
this.$refs.threeMap.zoomIn();
this.$refs.threeMap.zoomOut();

特效说明

粒子系统

• 随机分布的动态粒子
• 支持颜色渐变和大小变化
• 可配置粒子数量和分布范围

区域高亮

• 点击区域时的颜色变化
• 区域高度动画
• 可自定义高亮颜色和动画参数

发光边框

• 地图区域边界发光效果
• 可配置发光颜色和强度
• 支持多层发光叠加

扫描线

• 网格状扫描动画
• 可配置扫描线颜色和速度
• 支持透明度渐变

环境要求

核心依赖

• Vue ^2.6.14
• Three.js ^0.150.0
• GSAP ^3.0.0

开发环境依赖

• Node.js >= 12
• npm >= 6 或 yarn >= 1.22

构建工具

• Vue CLI >= 4.5
• Webpack >= 4

浏览器支持

• Chrome (最新版)
• Firefox (最新版)
• Safari (最新版)
• Edge (最新版)

注意事项

1. 确保容器元素具有明确的宽高
2. 建议在路由切换时正确销毁组件
3. 大数据量时注意性能优化
4. WebGL 支持检测

常见问题

1. 地图不显示

   • 检查容器大小
   • 确认数据格式正确
   • 查看控制台报错

2. 性能问题

   • 减少地图数据精度
   • 调整粒子数量
   • 优化动画效果

贡献指南

欢迎提交 Issue 和 Pull Request。

License

MIT