高德地图接入

2026-06-21 22:20:12 +08:00
parent 58187c96b3
commit d1a8d835fa
11 changed files with 628 additions and 3 deletions
--- a/.env
+++ b/.env
@@ -0,0 +1,9 @@
+# ============================================================
+# 高德地图配置
+# 请在 https://console.amap.com/dev/key/app 申请
+# ============================================================
+# 高德 JSAPI Key（用于地图展示、定位、搜索等前端功能）
+VITE_AMAP_JSAPI_KEY=f71bdfbf074620937b6b127128f49086
+
+# 高德 Web Service Key（用于服务端 API，如地理编码、路径规划等）
+VITE_AMAP_WEB_KEY=6a30265609e6099d02eddc4e3085de5c
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,6 +8,7 @@
      "name": "microapp-vue3",
      "version": "0.0.0",
      "dependencies": {
+        "@amap/amap-jsapi-loader": "^1.0.1",
        "@micro-zoe/micro-app": "^1.0.0-rc.31",
        "vue": "^3.5.34",
        "vue-router": "^4.6.4"
@@ -21,6 +22,12 @@
        "vue-tsc": "^3.2.8"
      }
    },
+    "node_modules/@amap/amap-jsapi-loader": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@amap/amap-jsapi-loader/-/amap-jsapi-loader-1.0.1.tgz",
+      "integrity": "sha512-nPyLKt7Ow/ThHLkSvn2etQlUzqxmTVgK7bIgwdBRTg2HK5668oN7xVxkaiRe3YZEzGzfV2XgH5Jmu2T73ljejw==",
+      "license": "MIT"
+    },
    "node_modules/@babel/helper-string-parser": {
      "version": "7.29.7",
      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
--- a/package.json
+++ b/package.json
@@ -9,6 +9,7 @@
    "preview": "vite preview"
  },
  "dependencies": {
+    "@amap/amap-jsapi-loader": "^1.0.1",
    "@micro-zoe/micro-app": "^1.0.0-rc.31",
    "vue": "^3.5.34",
    "vue-router": "^4.6.4"
--- a/src/App.vue
+++ b/src/App.vue
@@ -5,6 +5,7 @@
      <nav>
        <router-link to="/">首页</router-link>
        <router-link to="/about">关于</router-link>
+        <router-link to="/map">地图</router-link>
      </nav>
    </header>
    <main class="sub-app-main">
@@ -18,12 +19,28 @@
 </script>

 <style>
+/* 消除 body/html 默认 margin，确保全屏无滚动条 */
+html, body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  overflow: hidden;
+}
+
+/* 子应用挂载点 — 必须撑满才能让内部 100% 生效 */
+#microapp-vue3-root {
+  height: 100%;
+}
+
 /* 子应用全局样式 — 使用独立的选择器前缀避免污染主应用 */
 #microapp-vue3-container {
+  display: flex;
+  flex-direction: column;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
    'Helvetica Neue', Arial, 'Microsoft YaHei', sans-serif;
  color: #333;
-  min-height: 100vh;
+  height: 100%;
+  overflow: hidden;
  background: #fafafa;
 }

@@ -37,6 +54,7 @@
  background: linear-gradient(135deg, #42b883 0%, #35495e 100%);
  color: #fff;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+  flex-shrink: 0;
 }

 .sub-app-header h1 {
@@ -70,6 +88,13 @@
 }

 .sub-app-main {
-  min-height: calc(100vh - 48px);
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  /* 默认允许垂直滚动（首页/关于页等长内容页面需要），
+     地图页面通过自身 overflow: hidden 阻止滚动 */
+  overflow-y: auto;
+  overflow-x: hidden;
 }
 </style>
--- a/src/composables/useAmap.ts
+++ b/src/composables/useAmap.ts
@@ -0,0 +1,124 @@
+// ============================================================
+// 高德地图 Composable — 封装地图加载与实例管理
+// ============================================================
+
+import { ref, shallowRef, onUnmounted } from 'vue'
+import AMapLoader from '@amap/amap-jsapi-loader'
+import { AMAP_JSAPI_KEY, AMAP_VERSION, AMAP_PLUGINS } from '@/config/amap'
+
+/** 全局加载状态：避免重复加载 JSAPI 脚本 */
+let amapPromise: Promise<typeof AMap> | null = null
+
+/** 高德地图 JSAPI 全局对象缓存 */
+let AMapGlobal: typeof AMap | null = null
+
+/**
+ * 加载高德地图 JSAPI（单例模式，全局只加载一次）
+ * 返回 AMap 全局对象
+ */
+export async function loadAMap(): Promise<typeof AMap> {
+  if (AMapGlobal) return AMapGlobal
+
+  if (!amapPromise) {
+    amapPromise = AMapLoader.load({
+      key: AMAP_JSAPI_KEY,
+      version: AMAP_VERSION,
+      plugins: [...AMAP_PLUGINS],
+    })
+      .then((amap) => {
+        AMapGlobal = amap
+        return amap
+      })
+      .catch((err) => {
+        amapPromise = null // 失败后允许重试
+        throw new Error(`高德地图 JSAPI 加载失败: ${err.message}`)
+      })
+  }
+
+  return amapPromise
+}
+
+/**
+ * 地图 Composable — 管理地图实例的生命周期
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <div ref="containerRef" style="width: 100%; height: 400px" />
+ * </template>
+ *
+ * <script setup lang="ts">
+ * import { useAmap } from '@/composables/useAmap'
+ * const { containerRef, loading, error } = useAmap({
+ *   center: [116.397428, 39.90923],
+ *   zoom: 11
+ * })
+ * </script>
+ * ```
+ */
+export function useAmap(options: AMap.MapOptions = {}) {
+  const containerRef = ref<HTMLDivElement | null>(null)
+  const mapInstance = shallowRef<AMap.Map | null>(null)
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+
+  /** 初始化地图 */
+  async function initMap(): Promise<AMap.Map | null> {
+    if (!containerRef.value) {
+      error.value = '地图容器不存在'
+      return null
+    }
+
+    loading.value = true
+    error.value = null
+
+    try {
+      const AMap = await loadAMap()
+
+      if (mapInstance.value) {
+        mapInstance.value.destroy()
+      }
+
+      const defaultOptions: AMap.MapOptions = {
+        center: [116.397428, 39.90923], // 默认：北京天安门
+        zoom: 11,
+        viewMode: '3D', // 3D 模式
+        resizeEnable: true,
+      }
+
+      mapInstance.value = new AMap.Map(containerRef.value, {
+        ...defaultOptions,
+        ...options,
+      })
+
+      return mapInstance.value
+    } catch (err: any) {
+      error.value = err.message || '地图初始化失败'
+      return null
+    } finally {
+      loading.value = false
+    }
+  }
+
+  /** 销毁地图实例 */
+  function destroyMap(): void {
+    if (mapInstance.value) {
+      mapInstance.value.destroy()
+      mapInstance.value = null
+    }
+  }
+
+  // 组件卸载时自动销毁地图
+  onUnmounted(() => {
+    destroyMap()
+  })
+
+  return {
+    containerRef, // 模板绑定到地图容器 div
+    mapInstance, // 地图实例
+    loading, // 加载状态
+    error, // 错误信息
+    initMap, // 初始化方法
+    destroyMap, // 销毁方法
+  }
+}
--- a/src/config/amap.ts
+++ b/src/config/amap.ts
@@ -0,0 +1,22 @@
+// ============================================================
+// 高德地图配置
+// 使用 Vite 环境变量，必须以 VITE_ 前缀暴露给客户端
+// ============================================================
+
+/** 高德地图 JSAPI Key — 用于前端地图展示和交互 */
+export const AMAP_JSAPI_KEY = import.meta.env.VITE_AMAP_JSAPI_KEY as string
+
+/** 高德地图 Web Service Key — 用于服务端 API 调用 */
+export const AMAP_WEB_KEY = import.meta.env.VITE_AMAP_WEB_KEY as string
+
+/** 高德地图 JSAPI 版本 */
+export const AMAP_VERSION = '2.0'
+
+/** 需要加载的高德地图插件列表 */
+export const AMAP_PLUGINS = [
+  'AMap.Geocoder', // 地理编码/逆地理编码
+  'AMap.AutoComplete', // 输入提示
+  'AMap.PlaceSearch', // 搜索服务
+  'AMap.Geolocation', // 定位
+  'AMap.MarkerClusterer', // 点聚合
+] as const
--- a/src/main.ts
+++ b/src/main.ts
@@ -44,7 +44,7 @@ function unmount(): void {
 if (window.__MICRO_APP_ENVIRONMENT__) {
  // ✅ 运行在微前端环境中 — 导出生命周期钩子
  // micro-app 会通过 window[`micro-app-${appName}`] 找到并调用 mount/unmount
-  window[`micro-app-${window.__MICRO_APP_NAME__}`] = { mount, unmount }
+  ;(window as Record<string, any>)[`micro-app-${window.__MICRO_APP_NAME__}`] = { mount, unmount }

  console.log(
    `[microapp-vue3] 检测到微前端环境，应用名称: ${window.__MICRO_APP_NAME__}`
--- a/src/router/index.ts
+++ b/src/router/index.ts
@@ -10,6 +10,11 @@ const routes = [
    path: '/about',
    name: 'about',
    component: () => import('@/views/About.vue')
+  },
+  {
+    path: '/map',
+    name: 'map',
+    component: () => import('@/views/MapView.vue')
  }
 ]

--- a/src/views/MapView.vue
+++ b/src/views/MapView.vue
@@ -0,0 +1,332 @@
+<template>
+  <div class="map-page">
+    <!-- 地图初始化加载/错误状态 -->
+    <div v-if="loading" class="map-status">⏳ 地图加载中...</div>
+    <div v-else-if="error" class="map-status map-error">❌ {{ error }}</div>
+
+    <!-- 定位进行中提示 -->
+    <div v-if="locating" class="map-status map-locating">
+      {{ locatingSource === 'amap' ? '📡 基站/IP 定位中...' : '🛰️ GPS 定位中...' }}
+    </div>
+
+    <!-- 地图容器 -->
+    <div
+      ref="containerRef"
+      class="map-container"
+      :class="{ 'map-hidden': loading || error }"
+    />
+
+    <!-- 底部操作栏 -->
+    <div class="map-controls">
+      <span class="map-title">
+        🗺️ 高德地图
+        <span v-if="locatingSourceLabel" class="locate-badge">{{ locatingSourceLabel }}</span>
+      </span>
+      <div class="map-actions">
+        <button @click="resetView" :disabled="!mapInstance || locating">📍 回到默认位置</button>
+        <button
+          @click="locate"
+          :disabled="!mapInstance || locating"
+          class="btn-locate"
+        >
+          <span v-if="locating" class="spinner" />
+          {{ locating ? '定位中...' : '🎯 我的位置' }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, nextTick } from 'vue'
+import { useAmap, loadAMap } from '@/composables/useAmap'
+
+const { containerRef, mapInstance, loading, error, initMap } = useAmap({
+  center: [116.397428, 39.90923], // 北京天安门
+  zoom: 12,
+  pitch: 30,
+})
+
+void containerRef
+
+// ─────────────────────────────────────────
+// 定位状态
+// ─────────────────────────────────────────
+const locating = ref(false)
+const locatingSource = ref<'gps' | 'amap' | ''>('')
+const locatingSourceLabel = ref('')
+
+// ─────────────────────────────────────────
+// 地图初始化
+// ─────────────────────────────────────────
+async function bootstrapMap() {
+  const map = await initMap()
+  if (map) {
+    nextTick(() => map.resize())
+  }
+}
+onMounted(() => bootstrapMap())
+
+// ─────────────────────────────────────────
+// 📍 回到默认视图
+// ─────────────────────────────────────────
+function resetView(): void {
+  locatingSourceLabel.value = ''
+  const map = mapInstance.value
+  if (!map) return
+  map.setCenter([116.397428, 39.90923])
+  map.setZoom(12)
+}
+
+// ─────────────────────────────────────────
+// 🎯 我的位置 — 双通道定位
+// ─────────────────────────────────────────
+async function locate(): Promise<void> {
+  if (locating.value || !mapInstance.value) return
+
+  locating.value = true
+
+  // ── 通道 1：浏览器原生 GPS（高精度，需 HTTPS / localhost）──
+  const gpsResult = await tryBrowserGPS()
+  if (gpsResult) {
+    applyLocation(gpsResult.lng, gpsResult.lat, 16, '🛰️ GPS')
+    locating.value = false
+    return
+  }
+
+  // ── 通道 2：高德 IP / 基站定位（低精度，但无需用户授权）──
+  const amapResult = await tryAmapGeolocation()
+  if (amapResult) {
+    applyLocation(amapResult.lng, amapResult.lat, 14, '📡 IP定位')
+    locating.value = false
+    return
+  }
+
+  // ── 通道 3：完全失败 ──
+  locating.value = false
+  alert('无法获取您的位置，请检查浏览器定位权限或网络连接')
+}
+
+// ─────────────────────────────────────────
+// 通道 1：浏览器原生 Geolocation API
+// ─────────────────────────────────────────
+function tryBrowserGPS(): Promise<{ lng: number; lat: number } | null> {
+  return new Promise((resolve) => {
+    if (!navigator.geolocation) {
+      console.log('[定位] 浏览器不支持 Geolocation API，降级到高德定位')
+      resolve(null)
+      return
+    }
+
+    locatingSource.value = 'gps'
+    console.log('[定位] 🛰️ 尝试浏览器 GPS 定位...')
+
+    navigator.geolocation.getCurrentPosition(
+      (pos) => {
+        const { longitude: lng, latitude: lat, accuracy } = pos.coords
+        console.log(`[定位] ✅ GPS 成功 — 经度:${lng} 纬度:${lat} 精度:${accuracy}米`)
+        resolve({ lng, lat })
+      },
+      (err) => {
+        // GeolocationPositionError.code:
+        //   1 = PERMISSION_DENIED（用户拒绝）
+        //   2 = POSITION_UNAVAILABLE（信号不可用）
+        //   3 = TIMEOUT（超时）
+        const reason = ['', '用户拒绝授权', '信号不可用', '定位超时'][err.code] || err.message
+        console.log(`[定位] ❌ GPS 失败 (${reason})，降级到高德定位`)
+        resolve(null)
+      },
+      {
+        timeout: 8000,             // 8 秒超时
+        enableHighAccuracy: true,  // 强制启用 GPS 芯片
+        maximumAge: 60000,         // 允许 60 秒内的缓存（避免每次冷启动 GPS）
+      }
+    )
+  })
+}
+
+// ─────────────────────────────────────────
+// 通道 2：高德 IP / 基站定位
+// ─────────────────────────────────────────
+async function tryAmapGeolocation(): Promise<{ lng: number; lat: number } | null> {
+  try {
+    const AMap = await loadAMap()
+    locatingSource.value = 'amap'
+    console.log('[定位] 📡 尝试高德 IP 定位...')
+
+    return new Promise((resolve) => {
+      const geolocation = new AMap.Geolocation({
+        enableHighAccuracy: true,  // 混合定位（优先 GPS → Wi-Fi → 基站 → IP）
+        timeout: 6000,
+        panToLocation: false,      // 我们自己控制地图移动
+      })
+
+      geolocation.getCurrentPosition((status, result) => {
+        if (status === 'complete' && result.position) {
+          const { lng, lat } = result.position
+          console.log(
+            `[定位] ✅ 高德定位成功 — 经度:${lng} 纬度:${lat}`
+            + ` 地址:${result.formattedAddress} 精度:${result.accuracy}米`
+          )
+          resolve({ lng, lat })
+        } else {
+          console.log(`[定位] ❌ 高德定位失败: ${result.message}`)
+          resolve(null)
+        }
+      })
+    })
+  } catch (err: any) {
+    console.log(`[定位] ❌ 高德定位插件加载失败: ${err.message}`)
+    return null
+  }
+}
+
+// ─────────────────────────────────────────
+// 将定位结果应用到地图
+// ─────────────────────────────────────────
+function applyLocation(lng: number, lat: number, zoom: number, label: string): void {
+  const map = mapInstance.value
+  if (!map) return
+  map.setZoomAndCenter(zoom, [lng, lat])
+  locatingSourceLabel.value = label
+
+  // 3 秒后自动隐藏标签
+  setTimeout(() => {
+    if (locatingSourceLabel.value === label) {
+      locatingSourceLabel.value = ''
+    }
+  }, 3000)
+}
+</script>
+
+<style scoped>
+/* ============================================================
+   地图页面布局：header(48px) | map(剩余) | controls(52px)
+   ============================================================ */
+
+.map-page {
+  flex: 1;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  overflow: hidden;
+}
+
+/* ---- 状态提示（加载/错误/定位中）---- */
+.map-status {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 10;
+  padding: 14px 24px;
+  text-align: center;
+  font-size: 14px;
+  color: #666;
+  background: rgba(255, 255, 255, 0.95);
+  border-radius: 8px;
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.1);
+  pointer-events: none;
+}
+
+.map-error {
+  color: #e74c3c;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+}
+
+.map-locating {
+  color: #2d6cdf;
+  background: rgba(232, 240, 255, 0.95);
+  border: 1px solid #93c5fd;
+}
+
+/* ---- 地图容器 ---- */
+.map-container {
+  flex: 1;
+  width: 100%;
+  min-height: 0;
+}
+
+.map-hidden {
+  visibility: hidden;
+}
+
+/* ---- 底部操作栏 ---- */
+.map-controls {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 52px;
+  padding: 0 20px;
+  background: #fff;
+  border-top: 1px solid #e8e8e8;
+  box-shadow: 0 -2px 6px rgba(0, 0, 0, 0.04);
+  flex-shrink: 0;
+  z-index: 5;
+}
+
+.map-title {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 15px;
+  font-weight: 600;
+  color: #333;
+}
+
+/* 定位来源标签 */
+.locate-badge {
+  font-size: 11px;
+  font-weight: 500;
+  padding: 2px 8px;
+  border-radius: 10px;
+  background: #e8f5e9;
+  color: #2e7d32;
+}
+
+.map-actions {
+  display: flex;
+  gap: 10px;
+}
+
+.map-actions button {
+  padding: 7px 18px;
+  border: 1px solid #42b883;
+  border-radius: 6px;
+  background: #fff;
+  color: #42b883;
+  font-size: 13px;
+  cursor: pointer;
+  transition: all 0.2s;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.map-actions button:hover:not(:disabled) {
+  background: #42b883;
+  color: #fff;
+}
+
+.map-actions button:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* 定位按钮 loading 动画 */
+.spinner {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 2px solid transparent;
+  border-top-color: currentColor;
+  border-radius: 50%;
+  animation: spin 0.7s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+</style>
--- a/src/vite-env.d.ts
+++ b/src/vite-env.d.ts
@@ -1,5 +1,104 @@
 /// <reference types="vite/client" />

+// ============================================================
+// Vite 环境变量类型声明
+// ============================================================
+
+interface ImportMetaEnv {
+  readonly VITE_AMAP_JSAPI_KEY: string
+  readonly VITE_AMAP_WEB_KEY: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+
+// ============================================================
+// 高德地图 AMap 全局类型声明
+// ============================================================
+
+/** 高德地图 JSAPI v2 命名空间 */
+declare namespace AMap {
+  interface MapOptions {
+    center?: [number, number]
+    zoom?: number
+    viewMode?: '2D' | '3D'
+    resizeEnable?: boolean
+    pitch?: number
+    [key: string]: any
+  }
+
+  class Map {
+    constructor(container: HTMLElement | string, opts?: MapOptions)
+    setCenter(center: [number, number]): void
+    setZoom(zoom: number): void
+    setZoomAndCenter(zoom: number, center: [number, number]): void
+    resize(): void
+    add(overlay: any): void
+    remove(overlay: any): void
+    clearMap(): void
+    destroy(): void
+    on(event: string, handler: (...args: any[]) => void): void
+    off(event: string, handler: (...args: any[]) => void): void
+  }
+
+  class Geocoder {
+    constructor(opts?: Record<string, any>)
+  }
+  class AutoComplete {
+    constructor(opts?: Record<string, any>)
+  }
+  class PlaceSearch {
+    constructor(opts?: Record<string, any>)
+  }
+  /** 高德定位插件 — IP + 基站定位，精度低于浏览器 GPS */
+  interface GeolocationOptions {
+    /** 是否使用高精度定位，默认 true */
+    enableHighAccuracy?: boolean
+    /** 超时时间（毫秒），默认 Infinity */
+    timeout?: number
+    /** 定位成功后是否调整地图视野到定位精度范围，默认 false */
+    zoomToAccuracy?: boolean
+    /** 定位按钮的停靠位置：LT | RT | LB | RB */
+    position?: 'LT' | 'RT' | 'LB' | 'RB'
+    /** 定位按钮偏移量 [x, y] */
+    offset?: [number, number]
+    /** 是否显示定位按钮，默认 true */
+    showButton?: boolean
+    /** 定位成功后是否将定位点作为地图中心，默认 true */
+    panToLocation?: boolean
+    [key: string]: any
+  }
+
+  interface GeolocationResult {
+    position: { lng: number; lat: number }
+    accuracy: number
+    formattedAddress: string
+    addressComponent: {
+      province: string
+      city: string
+      district: string
+      township: string
+      street: string
+      streetNumber: string
+    }
+    message?: string
+  }
+
+  class Geolocation {
+    constructor(opts?: AMap.GeolocationOptions)
+    /** 获取当前位置 */
+    getCurrentPosition(
+      callback: (status: 'complete' | 'error', result: AMap.GeolocationResult) => void
+    ): void
+    /** 取消定位请求 */
+    cancelWatch(): void
+  }
+  class MarkerClusterer {
+    constructor(map: Map, markers: any[], opts?: Record<string, any>)
+  }
+}
+
 declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent<object, object, unknown>
--- a/tsconfig.app.json
+++ b/tsconfig.app.json
@@ -7,6 +7,7 @@
      "@/*": ["./src/*"]
    },
    "baseUrl": ".",
+    "ignoreDeprecations": "6.0",

    /* Linting */
    "noUnusedLocals": true,