スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いの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 (パッケージ 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とWebでGoogle Maps API キーを設定します。
• コンテナのサイズ変更時に updateLayout を呼び出してください。
• 画面を離れる際は、マップを破棄してください。

プラットフォームのセットアップ

プラットフォーム	マップエンジン	API キー
iOSと	Apple MapKit	マップには不要
Android	Google Maps SDK	GOOGLE_MAPS_API_KEY アプリのmanifest内
Web	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();

class属性を持つルート要素を使用してください。 map-overlay-root と data-native-map-overlay-rootを、 data-map-overlay タップを受け取る必要がある各HUD領域に配置します（例： header または footer wrapper）。その領域内のボタンやリンクが動作するのは、親要素に 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にある、ページの透明度と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 ビューポートやセーフエリアのインセットが変更された際に実行してください。