Native Build 맵 Capacitor 플러그인

@capgo/capacitor-native-map 사용하기

Android는 Google Maps, iOS는 Apple MapKit, 웹은 Google Maps JS를 하나의 TypeScript API로 마커, 카메라, 도형, 클러스터링, 이벤트를 처리합니다.

설치

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 (시작하기 참고) 그래야 오버레이 CSS가 탭을 허용하며, 투명한 영역을 통해 제스처가 맵으로 전달됩니다.

전체 레퍼런스

• GitHub: https://github.com/Cap-go/capacitor-native-map/
• 문서: /docs/plugins/native-map/