原生地图 Capacitor 插件

使用 @capgo/capacitor-native-map

通过一个 TypeScript API，即可在 Android 上使用 Google Maps、iOS 上使用 Apple MapKit 以及 Web 端使用 Google Maps JS，轻松实现标记、相机、形状、聚合和事件管理。

安装

bun add @capgo/capacitor-native-map
bunx cap sync

此插件公开的内容

• create：将地图嵌入 DOM 元素，或 toBack: true ：用于透明 HTML 背后的地图。
• updateLayout：调整原生地图大小和位置（CSS 像素）。
• setCamera / fitBounds：相机与视口控制。
• addMarker / addMarkers / removeMarker：带点击和拖拽监听器的标记。
• enableClustering：聚合密集标记集。
• enableCurrentLocation：有权限时显示用户位置点。
• 覆盖层：多边形、折线、圆形和瓦片图层（因平台而异）。

使用示例

嵌入式地图

import { NativeMap } from '@capgo/capacitor-native-map';

const map = await NativeMap.create({
  id: 'main-map',
  element: document.getElementById('map')!,
  apiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
  config: {
    center: { lat: 37.7749, lng: -122.4194 },
    zoom: 12,
  },
});

map.setOnMapClickListener((e) => console.log(e.latitude, e.longitude));

// In a framework component, call `await map.destroy()` from your teardown/cleanup hook.

带 HTML UI 的背景地图

const map = await NativeMap.create({
  id: 'stores-map',
  toBack: true,
  apiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
  config: {
    center: { lat: 40.7128, lng: -74.006 },
    zoom: 11,
    x: 0,
    y: 0,
    width: window.innerWidth,
    height: window.innerHeight,
  },
});

await map.updateLayout({
  x: 0,
  y: 0,
  width: window.innerWidth,
  height: window.innerHeight,
});

用以下内容包裹 HUD 区块 data-map-overlay （见入门指南）这样 overlay CSS 才能让点击生效；透明区域会把手势传递给地图。

完整参考文档

• GitHub： https://github.com/Cap-go/capacitor-native-map/
• 文档：/docs/plugins/native-map/