Panduan Memulai

Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-native-map`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/native-map/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

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

Membutuhkan Capacitor 8+. Versi major plugin mengikuti Capacitor (package v8).

Impor

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

Mulai cepat

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

Kesalahan umum

Konfigurasi key Google Maps API di Android dan web.
Panggil updateLayout saat container di-resize.
Destroy peta saat keluar dari layar.

Setup platform

Platform	Mesin peta	key API
iOS	Apple MapKit	Tidak diperlukan untuk peta
Android	Google Maps SDK	`GOOGLE_MAPS_API_KEY` di manifest aplikasi
Web	Google Maps JavaScript API	`apiKey` dan opsional `config.mapId` aktif `create`

Setup iOS untuk string penggunaan MapKit dan lokasi.
Setup Android untuk kunci SDK API Google Maps.

Peta tertanam

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.

Peta latar belakang (`toBack`) dengan overlay HTML

Atur toBack: true agar MapKit atau Google Maps merender di balik WebView Capacitor yang transparan. Sentuhan pada area transparan akan diteruskan ke peta (pinch, rotate, tilt, pan). Area yang harus menerima tap memerlukan data-map-overlay agar CSS di README memberikannya pointer-events: auto.

Saat toBack adalah true, element bersifat opsional di CreateMapArgs (plugin secara default menggunakan document.body). Saat toBack adalah false, berikan element seperti pada contoh tertanam di atas. updateLayout, show, dan hide aktif NativeMap di sumber plugin saat ini (lihat bagian overlay README).

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();

Gunakan elemen root dengan class map-overlay-root dan data-native-map-overlay-root. Letakkan data-map-overlay di setiap area HUD yang harus menerima ketukan (misalnya header atau footer wrapper). Tombol dan tautan di dalam area tersebut berfungsi karena elemen induk memiliki 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>

Tambahkan aturan page transparency dan pointer-event dari README plugin:

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;
}

Gunakan show() dan hide() untuk me-toggle native map tanpa menghancurkannya. Panggil updateLayout saat viewport atau safe-area insets berubah.