指南
如何在 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 支持点击;透明区域会将手势传递给地图。
完整参考
- GitHub: https://github.com/Cap-go/capacitor-native-map/
- 文档:/docs/plugins/native-map/