XxzxMapRender 地图渲染组件

基于 xxzx-lib 封装的 Vue 3 地图渲染组件，支持二维/三维模式切换和图层管理。

安装依赖

# 必须安装以下 peerDependencies
npm install vue vue-router axios element-plus @element-plus/icons-vue xxzx-lib

使用方式

1. 引入组件和样式

import { createApp } from "vue";
import ElementPlus from "element-plus";
import "element-plus/dist/index.css";
import * as ElementPlusIconsVue from "@element-plus/icons-vue";

import { XxzxMapRender, MapUtil, normalizeConfig, getLayerOne } from "xxzx-map-render";
import "xxzx-map-render/style.css";

const app = createApp(App);

// 注册 Element Plus
app.use(ElementPlus);
// 注册图标
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component);
}

app.mount("#app");

2. 基础使用

<template>
  <div style="width: 100%; height: 100vh;">
    <XxzxMapRender
      ref="mapRenderRef"
      :mode="initMode"
      :base-map-ids="baseLayerIds"
      :layer-ids="selectedLayerIds"
      @map-ready="handleMapReady"
      @layer-loaded="handleLayerLoaded"
      @layer-removed="handleLayerRemoved"
      @mode-changed="handleModeChanged"
      @error="handleError"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
import { XxzxMapRender } from "xxzx-map-render";
import { SceneModeType } from "xxzx-lib";

const mapRenderRef = ref(null);
const initMode = ref(SceneModeType.BOTH); // BOTH, SCENE2D, SCENE3D
const baseLayerIds = ref([10, 11]); // 底图图层ID列表（先加载）
const selectedLayerIds = ref([1, 2, 3]); // 业务图层ID列表（后加载）

const handleMapReady = (data) => {
  console.log("地图初始化完成:", data);
  // data.map, data.mapView, data.mode
};

const handleLayerLoaded = (data) => {
  console.log("图层加载完成:", data);
  // data.layerId, data.config, data.isBaseMap (是否为底图)
};

const handleLayerRemoved = (data) => {
  console.log("图层已移除:", data);
  // data.layerId, data.isBaseMap (是否为底图)
};

const handleModeChanged = (data) => {
  console.log("模式切换:", data);
  // data.oldMode, data.newMode
};

const handleError = (data) => {
  console.error("错误:", data);
  // data.type, data.message, ...
};
</script>

3. 通过 API 动态加载图层

<script setup>
import { ref, onMounted } from "vue";
import { XxzxMapRender, getLayerOne } from "xxzx-map-render";
import { SceneModeType } from "xxzx-lib";

const mapRenderRef = ref(null);
const selectedLayerIds = ref([]);

// 动态添加业务图层
const addLayer = async (layerId) => {
  const result = await mapRenderRef.value?.addLayerById(layerId);
  if (result && !result.alreadyLoaded) {
    console.log("业务图层加载成功:", result);
  }
};

// 动态添加底图图层
const addBaseLayer = async (layerId) => {
  const result = await mapRenderRef.value?.addBaseLayerById(layerId);
  if (result && !result.alreadyLoaded) {
    console.log("底图加载成功:", result);
  }
};

// 通过配置添加业务图层
const addLayerByConfig = () => {
  const config = {
    layerId: 999,
    layerName: "自定义图层",
    layerAddress: "https://example.com/layer.geojson",
    layerType: "geojson",
    layerConfig: {
      mode: SceneModeType.SCENE2D,
      useXxzxLib: true,
      styleConfig: [
        {
          type: "default",
          lineColor: "#ff0000",
          fillColor: "#00ff00",
        },
      ],
    },
  };
  mapRenderRef.value?.addLayerByConfig(config, 999);
};

// 通过配置添加底图图层
const addBaseLayerByConfig = () => {
  const config = {
    layerId: 888,
    layerName: "自定义底图",
    layerAddress: "https://example.com/basemap.wmts",
    layerType: "wmts",
    layerConfig: {
      mode: SceneModeType.BOTH,
      useXxzxLib: true,
    },
  };
  mapRenderRef.value?.addBaseLayerByConfig(config, 888);
};

// 移除业务图层
const removeLayer = (layerId) => {
  mapRenderRef.value?.removeLayer(layerId);
};

// 移除底图图层
const removeBaseLayer = (layerId) => {
  mapRenderRef.value?.removeBaseLayer(layerId);
};

// 获取已加载业务图层
const getAllLayers = () => {
  const layers = mapRenderRef.value?.getAllLayers();
  console.log("所有已加载业务图层:", layers);
};

// 获取已加载底图图层
const getBaseLayerById = (layerId) => {
  const layer = mapRenderRef.value?.getBaseLayerById(layerId);
  console.log("底图图层:", layer);
};
</script>

4. 模式切换

<script setup>
import { ref } from "vue";
import { XxzxMapRender } from "xxzx-map-render";
import { SceneModeType } from "xxzx-lib";

const mapRenderRef = ref(null);
const currentMode = ref(null);

// 切换到二维
const switchTo2D = () => {
  if (mapRenderRef.value?.canToggleMode()) {
    mapRenderRef.value.changeMode(SceneModeType.SCENE2D);
    currentMode.value = SceneModeType.SCENE2D;
  }
};

// 切换到三维
const switchTo3D = () => {
  if (mapRenderRef.value?.canToggleMode()) {
    mapRenderRef.value.changeMode(SceneModeType.SCENE3D);
    currentMode.value = SceneModeType.SCENE3D;
  }
};

const handleMapReady = (data) => {
  // 只有初始化模式为 BOTH 时才能切换
  const canToggle = mapRenderRef.value?.canToggleMode();
  currentMode.value = data.mode === SceneModeType.BOTH
    ? SceneModeType.SCENE2D
    : data.mode;
};
</script>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | mode | Number | SceneModeType.BOTH | 初始化模式，可选 SCENE2D(2)、SCENE3D(3)、BOTH(1) | | baseMapIds | Array | [] | 底图图层ID列表，作为地图底图先于 layerIds 加载 | | layerIds | Array | [] | 业务图层ID列表，组件会自动管理图层增删 |

Events

| 事件 | 参数 | 说明 | |------|------|------| | map-ready | { map, mapView, mode } | 地图初始化完成 | | layer-loaded | { layerId, config, isBaseMap? } | 图层加载完成，isBaseMap 标识是否为底图 | | layer-removed | { layerId, isBaseMap? } | 图层移除，isBaseMap 标识是否为底图 | | mode-changed | { oldMode, newMode } | 模式切换 | | error | { type, message, ... } | 发生错误 |

Expose Methods

Getter 方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | getMap() | - | Map_xxzx | 获取地图实例 | | getMapView() | - | MapView_xxzx | 获取地图视图实例 | | get3dInnerView() | - | Cesium.Viewer | 获取三维底层视图 | | get2dInnerView() | - | L.Map | 获取二维底层视图 | | getCurrentMode() | - | Number | 获取当前模式 | | getInitMode() | - | Number | 获取初始化模式 |

业务图层管理方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | addLayerById(layerId, customLayerId?) | - | Promise<Object> | 通过ID加载业务图层 | | addLayerByConfig(config, layerIdKey) | - | Promise<boolean> | 通过配置加载业务图层 | | removeLayer(layerIdKey) | - | boolean | 移除业务图层 | | removeAllLayers() | - | void | 移除所有业务图层 | | getLayerById(layerIdKey) | - | Object | 根据ID查找业务图层 | | getAllLayers() | - | Object | 获取所有已加载业务图层 |

底图图层管理方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | addBaseLayerById(layerId, customLayerId?) | - | Promise<Object> | 通过ID加载底图图层 | | addBaseLayerByConfig(config, layerIdKey) | - | Promise<boolean> | 通过配置加载底图图层 | | removeBaseLayer(layerIdKey) | - | boolean | 移除底图图层 | | removeAllBaseLayers() | - | void | 移除所有底图图层 | | getBaseLayerById(layerIdKey) | - | Object | 根据ID查找底图图层 |

模式切换方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | changeMode(newMode) | - | boolean | 切换模式 | | canToggleMode() | - | boolean | 是否可以切换模式 |

地图管理方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | initMap(mode) | - | void | 初始化地图 | | destroyMap() | - | void | 销毁地图 |

弹窗管理方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | closePopup() | - | void | 关闭属性信息弹窗 |

导出内容

// 组件
export { XxzxMapRender }

// 工具函数
export { MapUtil, normalizeConfig }

// API 函数
export { getLayerOne, uploadFile, getFileFullUrl }

图层模式兼容性

加载图层时会自动检查图层配置的 mode 与当前地图模式是否兼容：

| 地图模式 | 可加载的图层模式 | |---------|----------------| | BOTH | 全部（SCENE2D/SCENE3D/BOTH） | | SCENE3D | SCENE3D、BOTH | | SCENE2D | SCENE2D、BOTH |

注意事项

1. 组件高度需要父容器设置高度
2. 切换模式功能仅在初始化模式为 BOTH 时可用
3. 需要确保 xxzx-lib 已正确安装
4. API 请求需要配置正确的代理或 baseURL
5. 底图与业务图层分离管理：
   • baseMapIds 的底图图层先于 layerIds 的业务图层加载
   • 底图和业务图层使用独立的管理方法和存储结构
   • layer-loaded 和 layer-removed 事件会通过 isBaseMap 参数标识图层类型

完整示例 - MapRenderPage

查看 src/views/map-render/MapRenderPage.vue 获取完整的使用示例，包含：

• 树形图层选择面板
• 已加载图层列表管理
• 模式切换按钮
• 错误处理