@liu_xl/map

@liu_xl/map 是 UAVS 的 Vue 3 地图能力包，当前主要提供 /map/3d 页面使用的三维模型地图组件。组件内部负责 Mars3D/Cesium 地图初始化、3D Tiles 模型展示、模型定位、模型总览、hover 边框高亮和清晰度调整；业务项目负责提供模型数据和模型文件地址。

功能

• 基于 Vue 3、Mars3D、Cesium 展示城市、园区、小区、工厂等区域的三维模型。
• 支持从外部传入模型分组数据或模型列表数据。
• 支持从外部传入 3D Tiles tileset.json 地址解析函数。
• 支持模型定位、当前模型状态面板、模型总览切换。
• 支持模型 hover 边框强化，不用透明色块覆盖模型。
• 支持配置返回按钮是否显示、按钮文字和返回行为。
• 不依赖业务项目里的 @uavs/ui、BaseDialog 或 Element Plus。

安装

pnpm add @liu_xl/map

如果发布到私有 npm 源，先配置 scope registry：

pnpm config set @uavs:registry <registry-url>

然后再安装：

pnpm add @liu_xl/map

@liu_xl/map 会把 vue、mars3d、mars3d-cesium、@turf/turf 作为 peer dependencies 使用。业务项目里已经有这些依赖时，不需要重复安装，只要版本兼容即可。

如果某个接入项目缺少这些依赖，再按需补装：

pnpm add <缺失的包名>

Cesium 依赖

组件会按下面的顺序使用 Cesium：

1. 如果业务项目已经初始化了 window.Cesium，直接复用。
2. 如果没有 window.Cesium，从 peer dependency mars3d-cesium 动态加载 Cesium 和 Widgets/widgets.css。

接入项目只要本身已经依赖 mars3d-cesium，并且构建工具可以正常处理 mars3d-cesium/Build/Cesium/Widgets/widgets.css 即可。

如果地图配置里用到了底图预览图片，也需要在业务项目里准备：

public/img/basemaps

这些底图预览图片不是组件运行必需文件，npm 包不会默认发布它们。只有当业务项目的地图配置引用 /img/basemaps/* 时才需要自行放置。

基础用法

在页面或应用入口里导入组件和样式：

<script setup lang="ts">
import { ThreeDimensionalMap } from '@liu_xl/map'
import '@liu_xl/map/style.css'
import type { MaterialModelItem, ThreeDimensionalMapDataSource } from '@liu_xl/map'

const dataSource: ThreeDimensionalMapDataSource = {
  async getModelGroups() {
    // 在业务项目里调用自己的接口，例如 /admin-api/material/threedList
    return []
  }
}

function resolveTilesetUrl(item: MaterialModelItem) {
  if (!item.file) return ''
  return `/mapdata/${String(item.file).replace(/^\/+|\/+$/g, '')}/tileset.json`
}
</script>

<template>
  <div class="map-page">
    <ThreeDimensionalMap
      map-key="project-3d-map"
      :data-source="dataSource"
      :resolve-tileset-url="resolveTilesetUrl"
      :show-back-button="false"
    />
  </div>
</template>

<style scoped>
.map-page {
  width: 100%;
  height: 100vh;
}
</style>

注意：地图容器必须有明确高度，否则 Cesium 容器可能无法正常显示。

数据接入

推荐在业务项目里通过 dataSource 注入数据，组件本身不绑定具体请求库，也不固定接口地址。

interface ThreeDimensionalMapDataSource {
  getModelGroups?: () => Promise<MaterialModelGroup[]>
  getModelItems?: () => Promise<MaterialModelItem[] | PageResult<MaterialModelItem>>
}

分组数据

getModelGroups 适合接入类似 /admin-api/material/threedList 的树形数据：

const dataSource: ThreeDimensionalMapDataSource = {
  async getModelGroups() {
    const res = await geyThreedList()
    return res.data ?? []
  }
}

顶层 modelType 为 2 的分组会被当作三维模型分组。因为部分接口返回的子项 modelType 不可靠，组件会按顶层分组归一化子项类型，不再依赖子项自己的 modelType 判断是否为 3D 模型。

平铺数据

getModelItems 适合接入普通模型列表接口。返回值可以是数组，也可以是带 list 字段的分页对象：

const dataSource: ThreeDimensionalMapDataSource = {
  async getModelItems() {
    const res = await getMaterialApi({ pageSize: 999, pageNo: 1, type: 2 })
    return res.data
  }
}

模型数据格式

模型项至少需要包含可唯一识别的 id。如果要让定位更准确，建议同时提供经纬度。

interface MaterialModelItem {
  id: number | string
  file?: string
  fileName?: string
  name?: string
  longitude?: number
  latitude?: number
  height?: number
}

字段说明：

| 字段 | 说明 | | --- | --- | | id | 模型唯一标识，用于图层创建、定位和当前模型判断。 | | file | 模型文件目录或 URL，默认会用于拼接 tileset.json。 | | fileName / name | 模型展示名称。 | | longitude / latitude | 模型中心点经纬度，用于定位和飞行。 | | height | 模型高度或定位高度，按业务接口实际含义传入。 |

模型地址解析

不同项目的模型文件可能放在不同域名、不同前缀下，所以建议传入 resolveTilesetUrl：

function resolveTilesetUrl(item: MaterialModelItem) {
  if (!item.file) return ''

  if (/^https?:\/\//i.test(item.file)) {
    return item.file.endsWith('tileset.json') ? item.file : `${item.file}/tileset.json`
  }

  return `/mapdata/${String(item.file).replace(/^\/+|\/+$/g, '')}/tileset.json`
}

如果不传 resolveTilesetUrl，包内默认逻辑会把 file 解析成：

/mapdata/<file>/tileset.json

Props

| Prop | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | configUrl | string | /config/config.json | Mars3D 地图配置地址。 | | mapKey | string | common-3d | 地图实例 key，会用于生成容器 id；同页多个地图时必须不同。 | | options | Record<string, unknown> | {} | 额外 Mars3D 地图配置，会合并到地图初始化配置里。 | | initialView | Map3dInitialView \| false | 内置默认视角 | 初始总览视角；传 false 可禁用回到总览能力。 | | flyToInitialView | boolean | true | 地图创建后是否飞到初始视角。 | | showRealModelLabels | boolean | true | 是否展示模型标签。 | | preloadModels | boolean | true | 是否预加载模型元数据。 | | modelGroups | MaterialModelGroup[] | - | 直接传入的分组模型数据。 | | modelItems | MaterialModelItem[] | - | 直接传入的平铺模型数据。 | | dataSource | ThreeDimensionalMapDataSource | - | 外部异步数据源。 | | resolveTilesetUrl | MaterialTilesetUrlResolver | 内置 /mapdata 解析 | 把模型项转换成 3D Tiles 地址。 | | showBackButton | boolean | true | 是否显示左上角返回按钮。 | | backButtonText | string | 返回 | 返回按钮文字。 | | backFallbackUrl | string | / | 没有浏览器历史可退时跳转的兜底地址。 | | onBack | () => void | - | 自定义返回行为。 |

常用导出

export {
  ThreeDimensionalMap,
  ThreeDimensionalMapPage,
  TwoDimensionalMapPage,
  createMapApi,
  provideMapApi,
  formatMaterialModelTree,
  isThreeDimensionalModel,
  resolveTilesetUrl
}

常用类型：

export type {
  MaterialModelGroup,
  MaterialModelItem,
  MaterialTilesetUrlResolver,
  ThreeDimensionalMapDataSource,
  Map3dInitialView
}

发布前检查

发布前先执行：

pnpm --filter @liu_xl/map build
pnpm --filter @liu_xl/map pack:check

pack:check 会执行构建并运行 npm pack --dry-run，用于确认最终 npm 包里只包含需要发布的文件。

发布

公开发布：

pnpm --filter @liu_xl/map publish --access public

如果发布到私有源，需要先在发布环境里配置 registry 和登录信息：

pnpm config set @uavs:registry <registry-url>
npm login --registry <registry-url>
pnpm --filter @liu_xl/map publish

接入项目检查清单

• 已安装 @liu_xl/map。
• 业务项目已有并满足版本要求的 peer dependencies：vue、mars3d、mars3d-cesium、@turf/turf。
• 已导入 @liu_xl/map/style.css。
• 构建工具可以正常处理 mars3d-cesium/Build/Cesium/Widgets/widgets.css。
• 已准备 Mars3D 配置文件，默认路径为 /config/config.json，或通过 configUrl 指定。
• 已在业务项目里实现模型接口请求，并通过 dataSource 传入。
• 已根据项目模型文件路径实现 resolveTilesetUrl。
• 地图容器有明确宽高。
• 如果不需要组件内返回按钮，传入 :show-back-button="false"。