mcpField
M
maui-maps

maui-maps

github.com/davidortinau开发17645 次安装16 周前更新
代码仓库

关于 maui-maps

面向 .NET MAUI 应用地图功能的实现与故障排查指南，涵盖平台配置、地图控件与形状、地理编码、动态图钉和性能注意事项。

主要功能

  1. 01地图控件与形状使用指南
  2. 02平台专属配置检查
  3. 03动态地图的数据绑定图钉
  4. 04地址与坐标转换
  5. 05地图性能建议

适用场景

  1. 01排查地图空白或崩溃问题
  2. 02显示动态图钉和地图形状
  3. 03转换地址与坐标

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/davidortinau/maui-skills --skill maui-maps

安装后在 Claude Code 中输入/maui-maps确认已加载。

附带文件references/maps-api.md

详细介绍

.NET MAUI Maps

常见问题

问题解决方法
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 类型冲突

评论

支持 Markdown