syncfusion-maui-maps

实现 .NET MAUI Maps（SfMaps）

一份全面的指南，介绍如何实现 Syncfusion® .NET MAUI Maps 控件。SfMaps 控件是一款功能强大的数据可视化组件，可用于展示地理区域内的统计信息，并提供高度交互且可自定义的功能。

何时使用此技能

在需要以下操作时使用此技能：

• 安装和配置 Syncfusion® .NET MAUI Maps（SfMaps）控件
• 使用 shapefile 数据通过形状图层显示地理数据
• 集成来自各类提供商的基于图块的地图。
• 添加标记以标示位置，使用内置符号或自定义内容
• 使用气泡、颜色映射和分级统计地图可视化数据
• 使用可自定义的外观显示图例，适用于形状或气泡
• 在地图形状上通过智能定位显示数据标签
• 添加子图层（圆形、弧线、直线、多边形、折线）以进行额外的数据可视化
• 启用交互，例如缩放、平移、形状选择和工具提示
• 实现 AI 驱动的位置搜索，支持智能地理编码和搜索

组件概述

.NET MAUI Maps 提供两种主要图层类型：

1. 形状图层（MapShapeLayer）：从 GeoJSON 或 shapefile 数据渲染矢量地图
2. 图块图层（MapTileLayer）：从网络地图图块服务渲染栅格地图图块

主要功能：

• 支持多个图层和子图层
• 提供内置模板和自定义模板的标记
• 用于数据表示的气泡可视化
• 颜色映射（等值和范围）
• 交互式图例
• 支持智能定位的数据标签
• 缩放和平移功能
• 形状选择和工具提示
• AI 驱动的位置搜索

支持的平台： Android、iOS、Windows、macOS

文档和导航指南

入门

📄 阅读： references/getting-started.md

适合阅读的情形：首次设置、安装、创建基本地图

• NuGet 包安装（Syncfusion.Maui.Maps）
• 在 MauiProgram.cs 中注册处理程序
• 使用形状图层创建第一个地图
• 从本地加载 shapefile 数据。
• 使用图块图层创建第一个地图
• 基本配置和地图显示

图层类型

形状图层

📄 阅读： references/shape-layer.md

适合阅读的情形：使用矢量地图、shapefile 数据、分级统计地图和数据绑定

• MapShapeLayer 概述和配置
• 加载形状数据
• 使用 DataSource、PrimaryValuePath 和 ShapeDataField 绑定数据源
• 颜色映射策略（EqualColorMapping、RangeColorMapping）
• 形状样式（填充、描边、悬停状态）
• 形状自定义和主题
• AOT 模式注意事项和保留属性

图块图层

📄 阅读： references/tile-layer.md

适合阅读的情形：集成 OpenStreetMap、Bing Maps 或其他图块提供商

• MapTileLayer 概述
• URL 模板格式和 WMTS 规范
• 订阅密钥配置
• 地图中心和缩放设置
• 地图类型变体（道路、航空等）

可视化元素

标记

📄 阅读： references/markers.md

适合阅读的情形：向地图添加位置标记、图钉或自定义标记

• MapMarker 概述和 MapMarkerCollection
• 向形状图层添加标记
• 向图块图层添加标记
• 内置图标类型（圆形、菱形、矩形、正方形）
• 使用纬度/经度定位标记
• 图标自定义（大小、颜色、填充、描边）
• 使用 MarkerTemplate 创建自定义标记模板
• 标记对齐、偏移和锚定
• 标记工具提示
• 标记事件和选择

气泡

📄 阅读： references/bubbles.md

阅读时机：使用大小或颜色编码的气泡在形状上可视化数据

• 气泡可视化概述
• 使用 ShowBubbles 启用气泡
• BubbleSettings 配置
• 使用 SizeValuePath、MinSize、MaxSize 设置基于大小的气泡
• 使用 ColorValuePath 设置基于颜色的气泡
• 气泡样式（填充、描边、不透明度）
• 气泡工具提示
• 气泡颜色映射
• 多个气泡系列

数据标签

📄 阅读： references/data-labels.md

阅读时机：在地图形状上显示文本标签

• 数据标签概述及用途
• 使用 ShowDataLabels 启用标签
• DataLabelSettings 配置
• 使用 DataLabelPath 绑定标签文本
• 标签样式（字体、颜色、大小、字重）
• 标签位置和对齐方式
• 智能标签行为（截断、溢出时隐藏）
• 自定义标签模板
• 标签交互和事件

图例

📄 阅读： references/legends.md

阅读时机：为形状或气泡添加图例

• 图例概述和 MapLegend 配置
• 使用 SourceType.Shape 设置形状图例
• 使用 SourceType.Bubble 设置气泡图例
• 图例位置（顶部、底部、左侧、右侧）
• 根据 ColorMapping.Text 自定义图例文本
• 自定义图标（大小、类型、间距）
• 图例位置和内边距
• 使用 TextStyle 配置文本样式
• 自定义图例模板
• 图例显示与切换

高级功能

子图层

📄 阅读： references/sublayers.md

阅读时机：添加多个图层、圆形、弧线、线条、多边形或折线

• 子图层概述和类型
• 使用 MapShapeSublayer 添加额外的形状图层
• 使用 MapCircle 添加基于半径的圆形
• 使用 MapArc 通过弧线连接两点
• 使用 MapLine 创建简单的线条连接
• 使用 MapPolygon 创建自定义多边形
• 使用 MapPolyline 创建多点线路径
• 子图层数据绑定和集合
• 子图层样式和外观
• 多个子图层及其堆叠
• 图层 z-index 和顺序

交互功能

📄 阅读： references/interaction-features.md

阅读时机：启用缩放、平移、选择或工具提示

• 缩放和平移：
  • EnableZooming 和 EnablePanning 属性
  • ZoomPanBehavior 配置
  • MinZoomLevel 和 MaxZoomLevel
  • 以编程方式缩放的方法
  • 缩放至特定区域
• 选择：
  • 使用 EnableSelection 选择形状
  • 自定义选择外观
  • 选择事件和处理程序
• 工具提示：
  • 使用 ShowShapeTooltip 显示形状工具提示
  • 工具提示模板和样式
  • 标记和气泡的工具提示
  • 自定义工具提示内容

AI 驱动的位置搜索

📄 阅读： references/ai-location-search.md

阅读时机：实现智能位置搜索和地理编码

• AI 驱动的位置搜索概述
• 智能搜索功能
• 位置自动补全
• 地理编码集成
• 搜索配置
• 搜索结果处理
• 自定义搜索提供方