Mars3D Vue3 Components

基于 Vue 3 + Mars3D 的地图组件库，封装了基础地图能力及常用业务组件。

功能特性

基础能力

• 🗺️ 地图容器 - MarsMapContainer 一键接入地图
• 📏 测量工具 - 距离、面积、高度差、角度测量
• ✏️ 绘制工具 - 点、线、面、圆、矩形、自由多边形
• 👁️ 视角控制 - 环绕飞行、飞向位置、第一视角、键盘漫游

业务组件

• 📍 POI 标注管理 - POI 数据 + 地图图形双向绑定，支持分类筛选、名称编辑
• 🛤️ 轨迹管理 - 历史轨迹回放（播放/暂停/倍速/进度拖拽）+ 实时轨迹推送

安装

npm install yi-map-web

前置依赖

确保项目已安装以下依赖：

npm install vue@^3.4 mars3d@~3.11.0 mars3d-cesium@~1.140.0
npm install @fortawesome/fontawesome-free@^6.5.1
npm install -D vite-plugin-mars3d

并在 vite.config.ts 中配置插件：

import { mars3dPlugin } from "vite-plugin-mars3d";

export default {
  plugins: [
    vue(),
    mars3dPlugin(), // 必须
  ],
};

快速开始

完整引入

// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import Mars3dVueComponents from "yi-map-web";
import "yi-map-web/dist/yi-map-web.css";
import "@fortawesome/fontawesome-free/css/all.min.css"; // 图标库

const app = createApp(App);
app.use(Mars3dVueComponents);
app.mount("#app");

地图配置

组件库内置了默认地图配置（config/config.json），位于 public/config/ 目录下。消费者可以获取并覆盖：

// 获取默认配置
import defaultConfig from 'yi-map-web/config/config.json';

// 或在项目中创建自己的 config.json 并通过 prop 传入
<MarsMapContainer config-url="/your/path/config.json" />

按需引入（推荐）

<template>
  <MarsMapContainer
    config-url="/public/config/config.json"
    @onload="onMapReady"
  >
    <!-- 业务组件插槽 -->
    <PoiMarkerLayer ref="poiLayer">
      <PoiMarkerPanel />
    </PoiMarkerLayer>

    <TrackLayer ref="trackLayer">
      <TrackPanel />
    </TrackLayer>
  </MarsMapContainer>
</template>

<script setup lang="ts">
import { MarsMapContainer } from "yi-map-web";
import {
  PoiMarkerLayer,
  PoiMarkerPanel,
  TrackLayer,
  TrackPanel,
} from "yi-map-web";

const poiLayer = ref();

function onMapReady(map: any) {
  // 地图加载完成后可调用组件方法
  poiLayer.value?.addPoi({
    name: "天安门",
    lng: 116.397,
    lat: 39.908,
    alt: 50,
    category: "default",
  });
}
</script>

API 参考

MarsMapContainer

| Prop | 类型 | 默认值 | 说明 | | -------------- | --------- | -------------------- | ---------------- | | config-url | string | config/config.json | 地图配置文件路径 | | map-key | string | "default" | 多地图实例标识 | | hide-toolbar | boolean | false | 隐藏工具栏 | | hide-vision | boolean | false | 隐藏视角控制 |

| Event | 说明 | | -------- | --------------------------- | | onload | 地图加载完成，回传 map 实例 |

| Expose | 类型 | 说明 | | -------------- | ------------------- | ---------- | | map | Ref<Mars3D.Map> | 地图实例 | | graphicLayer | Ref<GraphicLayer> | 业务图层 | | measureLayer | Ref<GraphicLayer> | 测量图层 | | measure | UseMeasureReturn | 测量工具集 | | draw | UseDrawReturn | 绘制工具集 | | vision | UseVisionReturn | 视角控制集 |

通过 inject 获取上下文

在 MarsMapContainer 的插槽内，任意子组件可通过 inject 获取地图上下文：

import { inject } from "vue";
import type { UseMapReturn } from "yi-map-web";

const mapCtx = inject<UseMapReturn>("mapContext");
// mapCtx.map.value - 地图实例
// mapCtx.addGraphic() - 添加图形

组件使用规范

Layer + Panel 模式

业务组件采用 Layer + Panel 双组件模式：

• Layer（逻辑层）：注入地图上下文，管理图层和业务逻辑
• Panel（UI层）：注入业务上下文，负责界面展示

⚠️ 重要：Panel 必须作为 Layer 的子内容（slot），否则 provide/inject 链路断裂。

<!-- ✅ 正确 -->
<MarsMapContainer>
  <PoiMarkerLayer>
    <PoiMarkerPanel />
  </PoiMarkerLayer>
</MarsMapContainer>

<!-- ❌ 错误 -->
<MarsMapContainer>
  <PoiMarkerLayer />
  <PoiMarkerPanel />
</MarsMapContainer>

开发

# 安装依赖
npm install

# 开发调试
npm run dev

# 构建发布
npm run build

打包后使用

组件库打包后，在消费项目中引入组件时，必须额外引入样式文件：

import "yi-map-web/dist/yi-map-web.css";

完整的消费项目入口文件示例：

import { createApp } from "vue";
import App from "./App.vue";
import Mars3dVueComponents from "yi-map-web";
import "yi-map-web/dist/yi-map-web.css"; // 必须引入，否则样式错乱
import "@fortawesome/fontawesome-free/css/all.min.css";

const app = createApp(App);
app.use(Mars3dVueComponents);
app.mount("#app");

许可证

MIT