Xamarin.Forms 地图控件

项目
07/13/2023

控件 Map 是用于显示和批注地图的跨平台视图。它为每个平台使用本机地图控件，为用户提供快速熟悉的地图体验：

类 Map 定义控制地图外观和行为的以下属性：

IsShowingUser，类型 bool为，指示地图是否显示用户的当前位置。
ItemsSource，类型 IEnumerable为，指定要显示的项的 IEnumerable 集合。
ItemTemplate，类型 DataTemplate为，指定要 DataTemplate 应用于所显示项集合中每个项的。
ItemTemplateSelector，类型 DataTemplateSelector为，指定 DataTemplateSelector 用于在运行时为项选择 DataTemplate 的。
HasScrollEnabled类型 bool为，确定是否允许地图滚动。
HasZoomEnabled类型 bool为，确定是否允许地图缩放。
MapElements，类型 IList<MapElement>为，表示地图上的元素列表，例如多边形和折线。
MapType，属于类型 MapType，指示地图的显示样式。
MoveToLastRegionOnLayoutChange，类型 bool为，控制当布局发生更改时，所显示的地图区域是否会从其当前区域移动到以前设置的区域。
Pins，类型 IList<Pin>为，表示地图上的图钉列表。
TrafficEnabled，类型 bool为，指示交通数据是否叠加在地图上。
VisibleRegion，属于类型 MapSpan，返回当前显示的地图区域。

这些属性（、 Pins和 VisibleRegion 属性除外MapElements）由 BindableProperty 对象提供支持，这意味着它们可以成为数据绑定的目标。

类 Map 还定义点击 MapClicked 地图时触发的事件。 MapClickedEventArgs事件附带的对象具有名为的单个属性，该属性的类型PositionPosition为。触发事件时， Position 属性设置为点击的地图位置。有关结构的信息 Position ，请参阅地图位置和距离。

有关、 ItemTemplate和 ItemTemplateSelector 属性的信息ItemsSource，请参阅显示固定集合。

显示地图

Map可以通过将添加到布局或页面来显示：

<ContentPage ...
             xmlns:maps="clr-namespace:Xamarin.Forms.Maps;assembly=Xamarin.Forms.Maps">
    <maps:Map x:Name="map" />
</ContentPage>

注意

需要一个额外的 xmlns 命名空间定义来引用 Xamarin.Forms。地图控件。在前面的示例中，Xamarin.Forms.Maps命名空间通过 maps 关键字 (keyword) 引用。

等效 C# 代码如下：

using Xamarin.Forms;
using Xamarin.Forms.Maps;

namespace WorkingWithMaps
{
    public class MapTypesPageCode : ContentPage
    {
        public MapTypesPageCode()
        {
            Map map = new Map();
            Content = map;
        }
    }
}

此示例调用默认 Map 构造函数，该构造函数将地图居中位于罗马：

在 iOS 和 Android 上具有默认位置的的屏幕截图

或者， MapSpan 可以将参数传递给 Map 构造函数，以在加载地图时设置地图的中心点和缩放级别。有关详细信息，请参阅在地图上显示特定位置。

地图类型

可以将 Map.MapType 属性设置为 MapType 枚举成员，以定义地图的显示样式。 MapType 枚举定义下列成员：

Street 指定将显示街道地图。
Satellite 指定将显示包含卫星图像的地图。
Hybrid 指定将显示组合街道和卫星数据的地图。

默认情况下，如果 MapType 属性未定义， Map 将显示街道地图。或者， MapType 属性可以设置为枚举成员之 MapType 一：

<maps:Map MapType="Satellite" />

等效 C# 代码如下：

Map map = new Map
{
    MapType = MapType.Satellite
};

当属性设置为 Street时，MapType以下屏幕截图显示了 Map ：

iOS 和 Android 上具有街道地图类型的地图屏幕截图

当属性设置为 Satellite时，MapType以下屏幕截图显示了 Map ：

在 iOS 和 Android 上具有卫星地图类型的屏幕截图

当属性设置为 Hybrid时，MapType以下屏幕截图显示了 Map ：

iOS 和 Android 上混合地图类型的地图屏幕截图

在地图上显示特定位置

可以通过将参数传递给 MapSpanMap 构造函数来设置加载映射时要显示的映射区域：

<maps:Map>
    <x:Arguments>
        <maps:MapSpan>
            <x:Arguments>
                <maps:Position>
                    <x:Arguments>
                        <x:Double>36.9628066</x:Double>
                        <x:Double>-122.0194722</x:Double>
                    </x:Arguments>
                </maps:Position>
                <x:Double>0.01</x:Double>
                <x:Double>0.01</x:Double>
            </x:Arguments>
        </maps:MapSpan>
    </x:Arguments>
</maps:Map>

等效 C# 代码如下：

Position position = new Position(36.9628066, -122.0194722);
MapSpan mapSpan = new MapSpan(position, 0.01, 0.01);
Map map = new Map(mapSpan);

此示例创建一个 Map 对象，该对象显示由 MapSpan 对象指定的区域。对象 MapSpan 以对象表示 Position 的纬度和经度为中心，跨越 0.01 纬度和 0.01 经度。有关结构的信息 Position ，请参阅地图位置和距离。有关在 XAML 中传递参数的信息，请参阅在 XAML 中传递参数。

结果是，在显示地图时，地图以特定位置为中心，并跨越特定数量的纬度和经度度：

创建 MapSpan 对象

有多种方法可用于创建 MapSpan 对象。常见的方法是向构造函数提供所需的参数 MapSpan 。这些是由对象表示 Position 的纬度和经度，以及 double 表示跨越 MapSpan的纬度和经度度的值。有关结构的信息 Position ，请参阅地图位置和距离。

或者，类中有 MapSpan 三个返回新 MapSpan 对象的方法：

ClampLatitude 返回一个 MapSpan ，其与方法的类实例相同 LongitudeDegrees ，以及由其 north 和 south 参数定义的半径。
FromCenterAndRadius 返回 MapSpan 由其 Position 和 Distance 参数定义的。
WithZoom 返回一个 MapSpan ，其中心与方法的类实例相同，但半径乘以其 double 参数。

有关结构的信息 Distance ，请参阅地图位置和距离。

MapSpan创建后，可以访问以下属性来检索有关它的数据：

Center，它表示 Position 的地理中心的 MapSpan。
LatitudeDegrees，表示跨越 MapSpan的纬度。
LongitudeDegrees，表示跨越 MapSpan的经度度。
Radius，表示 MapSpan 半径。

移动地图

Map.MoveToRegion可以调用方法来更改地图的位置和缩放级别。此方法接受一个 MapSpan 参数，该参数定义要显示的地图区域及其缩放级别。

以下代码演示了在地图上移动所显示区域的示例：

MapSpan mapSpan = MapSpan.FromCenterAndRadius(position, Distance.FromKilometers(0.444));
map.MoveToRegion(mapSpan);

缩放地图

可以在不更改其位置的情况下更改的缩放级别 Map 。这可以使用地图 UI 来实现，也可以通过编程方式调用方法， MoveToRegion 并使用 MapSpan 当前位置作为 Position 参数的参数调用方法：

double zoomLevel = 0.5;
double latlongDegrees = 360 / (Math.Pow(2, zoomLevel));
if (map.VisibleRegion != null)
{
    map.MoveToRegion(new MapSpan(map.VisibleRegion.Center, latlongDegrees, latlongDegrees));
}

在此示例中， MoveToRegion 使用 MapSpan 参数调用方法，该参数通过 Map.VisibleRegion 属性指定地图的当前位置，并将缩放级别指定为纬度和经度度。总体结果是地图的缩放级别已更改，但其位置未更改。在地图上实现缩放的另一种方法是使用 MapSpan.WithZoom 方法来控制缩放因子。

重要

无论是通过地图 UI 还是以编程方式缩放地图，都需要 Map.HasZoomEnabled 属性为 true。有关此属性的详细信息，请参阅禁用缩放。

自定义地图行为

可以通过设置其某些属性和处理事件来MapClicked自定义的行为Map。

注意

可以通过创建地图自定义呈现器来实现其他地图行为自定义。有关详细信息，请参阅自定义 Xamarin.Forms 映射。

显示交通情况数据

类 Map 定义 TrafficEnabled 类型的 bool属性。默认情况下，此属性为 false，指示交通数据不会叠加在地图上。当此属性设置为 true时，交通数据将叠加在地图上。以下示例演示如何设置此属性：

<maps:Map TrafficEnabled="true" />

等效 C# 代码如下：

Map map = new Map
{
    TrafficEnabled = true
};

禁用滚动

类 Map 定义 HasScrollEnabled 类型的 bool属性。默认情况下，此属性为 true，表示允许地图滚动。当此属性设置为 false时，地图将不会滚动。以下示例演示如何设置此属性：

<maps:Map HasScrollEnabled="false" />

等效 C# 代码如下：

Map map = new Map
{
    HasScrollEnabled = false
};

禁用缩放

类 Map 定义 HasZoomEnabled 类型的 bool属性。默认情况下，此属性为 true，表示可以在地图上执行缩放。当此属性设置为 false时，无法缩放地图。以下示例演示如何设置此属性：

<maps:Map HasZoomEnabled="false" />

等效 C# 代码如下：

Map map = new Map
{
    HasZoomEnabled = false
};

显示用户的位置

类 Map 定义 IsShowingUser 类型的 bool属性。默认情况下，此属性为 false，指示地图未显示用户的当前位置。当此属性设置为 true时，地图将显示用户的当前位置。以下示例演示如何设置此属性：

<maps:Map IsShowingUser="true" />

等效 C# 代码如下：

Map map = new Map
{
    IsShowingUser = true
};

重要

在 iOS、Android 和通用 Windows 平台上，访问用户的位置需要向应用程序授予位置权限。有关详细信息，请参阅平台配置。

在布局更改时维护地图区域

类 Map 定义 MoveToLastRegionOnLayoutChange 类型的 bool属性。默认情况下，此属性为 true，它指示当布局发生更改（例如设备旋转时）时，显示的地图区域将从其当前区域移动到以前设置的区域。当此属性设置为 false时，当布局发生更改时，显示的地图区域将保持居中。以下示例演示如何设置此属性：

<maps:Map MoveToLastRegionOnLayoutChange="false" />

等效 C# 代码如下：

Map map = new Map
{
    MoveToLastRegionOnLayoutChange = false
};

映射单击次数

类 Map 定义点击 MapClicked 地图时触发的事件。事件 MapClickedEventArgs 附带的对象具有一个名为 Position的属性，其类型 Position为。触发事件时，属性 Position 将设置为已点击的地图位置。有关结构的信息 Position ，请参阅映射位置和距离。

下面的代码示例演示事件的 MapClicked 事件处理程序：

void OnMapClicked(object sender, MapClickedEventArgs e)
{
    System.Diagnostics.Debug.WriteLine($"MapClick: {e.Position.Latitude}, {e.Position.Longitude}");
}

在此示例中， OnMapClicked 事件处理程序输出表示点击地图位置的纬度和经度。事件处理程序可以注册到事件， MapClicked 如下所示：

<maps:Map MapClicked="OnMapClicked" />

等效 C# 代码如下：

Map map = new Map();
map.MapClicked += OnMapClicked;

Xamarin.Forms 地图控件

显示地图

地图类型

在地图上显示特定位置

创建 MapSpan 对象

移动地图

缩放地图

自定义地图行为

显示交通情况数据

禁用滚动

禁用缩放

显示用户的位置

在布局更改时维护地图区域

映射单击次数

相关链接

其他资源