跳转至正文

原生地图 Capacitor 插件

通过一个 API 即可在 Android 上使用 Google Maps、iOS 上使用 Apple MapKit 以及 Web 端使用 Google Maps JS,统一管理标记、相机和覆盖层

安装

bun add @capgo/capacitor-native-map bunx cap sync
npm、pnpm 或 yarn
  • npm install @capgo/capacitor-native-map
  • pnpm add @capgo/capacitor-native-map
  • yarn add @capgo/capacitor-native-map

指南

如何在 Capacitor 中使用 Native Map

使用 @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 支持点击;透明区域会将手势传递给地图。

完整参考

常见问题

Native Map 插件常见问题

如何在 Capacitor 应用中安装 Native Map 插件?

运行 "bun add @capgo/capacitor-native-map"(或 "npm install @capgo/capacitor-native-map"),然后运行 "bunx cap sync",让 iOS 和 Android 项目加载原生 code。然后在应用的 code 中从 "@capgo/capacitor-native-map" 导入。

@capgo/capacitor-native-map 支持 React、Vue 和 Angular 吗?

支持。Native Map 是一个 Capacitor 包,因此任何运行在 Capacitor 中的 Web 框架都能用,包括 Ionic、React、Vue、Angular、Svelte 和纯 JavaScript。

@capgo/capacitor-native-map 支持哪个 Capacitor 版本?

Capgo 插件遵循 Capacitor 的主版本号:请使用与 Capacitor 主版本号一致的插件主版本(例如插件 v8 对应 Capacitor 8)。GitHub README 中的兼容性表列出了仍在维护的版本。

@capgo/capacitor-native-map 是免费开源的吗?

是的。code 源码已在 GitHub 公开,地址为 https://github.com/Cap-go/capacitor-native-map/,也可以从 npm 免费安装。欢迎提交 Bug 报告和 Pull Request。

我可以在不经过 App Store 审核的情况下,更新使用了 Native Map 的 code 吗?

安装或升级插件会改动原生 code,因此需要重新做一次商店构建。之后,调用该插件的 JavaScript、HTML 和 CSS 改动就能通过 Capgo live updates 立即发布。

无需等待应用审核,即可发布 Native Map 更新

只要插件已包含在你的商店版本中,Capgo live updates 就能在几分钟内把 JavaScript、HTML 和 CSS 的改动推送给用户。

开始使用 Capgo