시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-map` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

npm install @capgo/capacitor-native-map
npx cap sync

필요 Capacitor 8+. 이 플러그인의 메이저 버전은 Capacitor (package) 버전을 따릅니다. v8).

가져오기

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

빠른 시작

import { NativeMap } from '@capgo/capacitor-native-map';
await NativeMap.create({ id: 'map', element: document.getElementById('map')!, config: { center: { lat: 0, lng: 0 }, zoom: 10 } });

자주 하는 실수

• Android 및 웹에서 Google Maps API 키를 설정합니다.
• 컨테이너 크기가 변경되면 updateLayout을 호출하세요.
• 화면을 벗어날 때 map 인스턴스를 해제하세요.

플랫폼 설정

플랫폼	지도 엔진	API 키
iOS	Apple MapKit	지도 사용 시 불필요
Android	Google Maps SDK	GOOGLE_MAPS_API_KEY 앱 매니페스트 내
웹	Google Maps JavaScript API	apiKey 그리고 선택적으로 config.mapId 켜짐 create

• iOS 설정 MapKit 및 위치 권한 사용 문구에 대해.
• Android 설정 Google Maps SDK API 키를 위해.

임베디드 맵

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('click', e.latitude, e.longitude));

await map.addMarker({
  coordinate: { lat: 37.7749, lng: -122.4194 },
  title: 'San Francisco',
});

// Call destroy() when leaving the screen or unmounting your map component.

배경 지도 (toBack) 및 HTML 오버레이

설정 toBack: true MapKit 또는 Google Maps가 렌더링되도록 뒤에 투명한 Capacitor WebView. 투명 영역의 터치(핀치, 회전, 기울기, 팬)는 지도로 전달됩니다. 탭을 받아야 하는 영역에는 data-map-overlay 그래서 README CSS가 이들에게 주는 pointer-events: auto.

시기 toBack 이며 true, element 는 ...에서 선택 사항입니다 CreateMapArgs (플러그인 기본값은 document.body)입니다. 이때 toBack 이며 false, 전달 element 위의 임베디드 예제와 같습니다. updateLayout, show, 그리고 hide 에(는) 있습니다. NativeMap 현재 플러그인 소스에(는) 있습니다 (다음의 README overlay 섹션을).

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

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

클래스가 있는 루트 요소를 사용하세요. map-overlay-root 및 data-native-map-overlay-root를(을) 배치하세요. data-map-overlay 탭을 수신해야 하는 각 HUD 영역에(는) (예를 들어 header 또는 footer 래퍼)를 사용하세요. 해당 영역 내부의 버튼과 링크는 부모 요소에 pointer-events: auto:

<div class="map-overlay-root" data-native-map-overlay-root>
  <header class="hud" data-map-overlay>
    <button type="button" id="recenter">Recenter</button>
  </header>
</div>

플러그인 README에 있는 page transparency 및 pointer-event 규칙을 추가하세요:

html.native-map-to-back,
body.native-map-to-back {
  background: transparent !important;
}

:root {
  --ion-background-color: transparent !important;
}

.map-overlay-root {
  position: fixed;
  inset: 0;
  pointer-events: none;
}

.map-overlay-root [data-map-overlay] {
  pointer-events: auto;
}

사용 show() 및 hide() 네이티브 맵을 파괴하지 않고 토글하려면 다음을 호출하세요: updateLayout viewport 또는 safe-area insets가 변경될 때 호출합니다.