yudada-map

Vue3 的 HnMap 组件（基于 Three.js 的 3D 区域地图），贴图 / GeoJSON / 图标等资源全部随包发布，安装后即可开箱即用，也支持按业务自定义。

安装

npm i yudada-map three gsap @tweenjs/tween.js

快速上手

全局注册

import { createApp } from 'vue';
import App from './App.vue';
import { HnMapPlugin } from 'yudada-map';

createApp(App).use(HnMapPlugin).mount('#app');

<template>
  <div style="width: 100%; height: 600px">
    <HnMap @map-ready="onReady" />
  </div>
</template>

<script setup>
const onReady = () => {
  console.log('map ready');
};
</script>

局部引入

<template>
  <div style="width: 100%; height: 600px">
    <HnMap :sites="sites" :geo-json="geo" :textures="textures" />
  </div>
</template>

<script setup>
import { HnMap } from '@sjkj/hn-map';

// 1) 可选：自定义 geojson（对象或 URL）
const geo = '/data/your-province.json';

// 2) 可选：自定义贴图与图标
const textures = {
  topMap: '/images/map-top.png',
  fxMap: '/images/map-fx.png',
  windIcon: '/images/icons/wind.png',
  pvIcon: '/images/icons/pv.png'
};

// 3) 可选：自定义站点（经纬度 + 业务字段）
const sites = [
  {
    lon: 112.5,
    lat: 28.1,
    type: 'wind',
    name: '风电场 A',
    installedCapacity: '50MW',
    power: '32MW',
    windSpeed: '7.5m/s',
    dailyEnergy: '620MWh',
    statusText: '正常',
    statusClass: 'status-normal'
  }
];
</script>

Props 说明

1. 基本 Props

• geoJson（可选）

  • 类型: object | string
  • 说明:
    • object: 直接传入解析后的 GeoJSON 数据；
    • string: 视为 URL，组件内部通过 THREE.FileLoader 异步加载；
    • 不传时使用内置的湖南省 GeoJSON。

• textures（可选）

  • 类型: object
  • 说明: 自定义贴图与图标资源，不传则使用组件内置默认贴图。
  • 可用字段:
    • topMap: 地图顶面贴图
    • fxMap: 地图发光特效贴图
    • rotatingAperture: 中心旋转光圈贴图
    • rotatingPoint: 旋转点贴图
    • circlePoint: 中心圆点贴图
    • sceneBg: 场景背景贴图
    • windIcon: 风机图标
    • pvIcon: 光伏图标

• sites（可选）

  • 类型: Array<object>
  • 说明: 通过经纬度配置风机 / 光伏点位，并驱动点击弹框的业务数据。
  • 每一项示例:

    {
      // 经纬度（必填其一）
      lon: number;          // 或 lng / longitude
      lat: number;          // 或 latitude
    
      // 类型（可选）：决定默认使用风机 / 光伏图标
      type?: 'wind' | 'pv';
    
      // 弹框 & 标签常用字段（均可选）
      name?: string;              // 电站 / 城市名称，用作标题
      installedCapacity?: string; // 装机容量
      power?: string;             // 实际功率
      windSpeed?: string;         // 平均风速
      dailyEnergy?: string;       // 日发电量
      statusText?: string;        // 状态文案（默认：正常）
      statusClass?: string;       // 状态样式 class，例如：status-normal / status-offline
    
      // 单点覆盖图标
      lightPillarUrl?: string;    // 当前点位单独使用的图标 URL
    
      // 其他自定义字段，会原样挂载在 activeSite.properties 上
      [key: string]: any;
    }

• config（可选）

  • 类型: object
  • 说明: 部分基础配置，未设置的字段会使用组件内部默认值。
  • 支持字段:
    • centerXY: [number, number]
      • 地图中心点经纬度，默认从 geoJson 自动计算；
      • 需要强制指定相机观察中心时可以传入。
    • bottomZ: number
      • 地图底部 Z 坐标（默认 -0.2），影响装饰元素位置。

事件

• @map-ready
  • 说明: 地图初始化完成（入场动画结束后）触发一次，适合在这里执行后续联动逻辑。
  • 示例:

    <HnMap @map-ready="handleReady" />

弹框数据说明

点击任意点位后，组件会内部维护一个 activeSite 对象，并在信息面板中使用 activeSite.properties 显示内容：

• 标题：activeSite.properties?.name || '电站详情'
• 装机容量：activeSite.properties?.installedCapacity ?? '2.5MW'
• 实际功率：activeSite.properties?.power ?? '343kW'
• 平均风速：activeSite.properties?.windSpeed ?? '3.13m/s'
• 日发电量：activeSite.properties?.dailyEnergy ?? '531kWh'
• 状态：
  • 文案：activeSite.properties?.statusText ?? '正常'
  • 样式 class：activeSite.properties?.statusClass || 'status-normal'

对于由 sites 传入的点位，这些字段就是你在 sites 中配置的值；对于内置 geoJson 里的城市，则为其 properties 字段。

注意事项

• 父容器必须给定明确高度，例如 height: 600px 或 height: 100vh，否则地图高度为 0。
• 组件内部已避免使用固定 DOM id，支持多实例同时渲染。
• 三方依赖（three / gsap / @tweenjs/tween.js）作为 peer 依赖，由宿主项目统一安装与复用。