maui-maps

.NET MAUI マップ

よくある注意点

問題	解決方法
Android でマップが空白になる	AndroidManifest.xml の Google Maps API キーがない、または間違っています
起動時にマップがクラッシュする	MauiProgram.cs で .UseMauiMaps() が呼び出されていません
Map 型が曖昧になる	Microsoft.Maui.ApplicationModel.Map と競合します — 名前空間エイリアスを追加してください
Windows でマップが表示されない	Windows はネイティブサポートに対応していません — CommunityToolkit.Maui.Maps を使用する必要があります
ユーザーの位置を示すドットが表示されない	IsShowingUser="True" は設定されていますが、位置情報の許可が付与されていません
Android 11 以降で外部マップアプリを起動できない	マニフェストに geo スキームの <queries> がありません

⚠️ 名前の競合 — 常にエイリアスを設定してください

Microsoft.Maui.Controls.Maps.Map は Microsoft.Maui.ApplicationModel.Map と競合します。これにより、わかりにくいコンパイルエラーが発生します。

// ✅ Correct — explicit alias
using Map = Microsoft.Maui.Controls.Maps.Map;

xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
<maps:Map ... />


<Map ... />

プラットフォーム設定時の注意点

Android — API キーは <application> の内側に配置する必要があります

<application ...>
  <meta-data android:name="com.google.android.geo.API_KEY"
             android:value="YOUR_GOOGLE_MAPS_KEY" />
</application>

⚠️ さらに必要な設定：Google Play Services のバージョンを示すメタデータと、API 30 以降では geo スキーム用の <queries>（references/maps-api.md を参照）。

iOS / Mac Catalyst

⚠️ Info.plist に NSLocationWhenInUseUsageDescription がない場合、位置情報の許可はプロンプトなしで拒否されます。

Windows — ネイティブサポートなし

CommunityToolkit.Maui.Maps と Bing キーを追加する必要があります。条件付きのパッケージ参照と、セットアップ用の #if WINDOWS を使用してください。

MauiProgram.cs — UseMauiMaps を忘れずに

// ✅ Required — without this, Map control throws at runtime
builder.UseMauiMaps();

// ❌ Forgetting this causes "No registered handler for Map" crash

パフォーマンスのヒント

• ⚠️ 何百ものピンを直接追加しないでください — 大量のピンには、データバインディングを使った ItemsSource を使用してください。
• 初期領域を設定するには MoveToRegion() を使用し、デフォルトの世界地図表示へのズームアニメーションを避けてください。
• MoveToRegion() の頻繁な呼び出しは避けてください — 呼び出すたびにマップのアニメーションが発生します。データ変更に連動する場合は、呼び出しをデバウンスしてください。

データバインドされたピン — 動的データではこちらを使用

<maps:Map ItemsSource="{Binding Locations}">
    <maps:Map.ItemTemplate>
        <DataTemplate>
            <maps:Pin Label="{Binding Name}"
                      Address="{Binding Description}"
                      Location="{Binding Position}" />
        </DataTemplate>
    </maps:Map.ItemTemplate>
</maps:Map>

選択ガイド

必要な機能	方法
ピン付きの基本的なマップ	Map コントロールと Pins.Add()、または ItemsSource バインディング
図形付きのマップ	MapElements — Polygon、Polyline、Circle
住所 → 座標	Geocoding.Default.GetLocationsAsync(address)
座標 → 住所	Geocoding.Default.GetPlacemarksAsync(lat, lon)
カスタムマップオーバーレイ	ハンドラーを使用してネイティブマップ API にアクセス
Windows のサポート	CommunityToolkit.Maui.Maps と Bing キーを追加する必要があります

クイックチェックリスト

• NuGet：Microsoft.Maui.Controls.Maps を追加済み
• MauiProgram.cs で .UseMauiMaps() を呼び出し済み
• Android：Google Maps API キーを AndroidManifest.xml の <application> 内に設定済み
• Android：Google Play Services のバージョンを示すメタデータを設定済み
• Android 11 以降：geo スキーム用の <queries> を追加済み
• iOS/Mac：Info.plist に NSLocationWhenInUseUsageDescription を設定済み
• Windows：CommunityToolkit.Maui.Maps と Bing Maps キーを条件付きで設定済み
• Map 型の競合を避けるため、名前空間エイリアスを追加済み