Xamarin.Forms 地圖釘選

發行項
10/23/2019

控制項 Xamarin.FormsMap 允許使用物件標記 Pin 位置。 Pin是點選時開啟資訊視窗的地圖示記：

Pin當物件加入至集合時Map.Pins，圖釘會在地圖上轉譯。

Pin 類別具有下列屬性：

Address型 string別為的，這通常代表針腳位置的位址。不過，它可以是任何 string 內容，而不只是位址。
Label型 string別為的，通常代表釘選標題。
Position型 Position別為的，表示針腳的緯度和經度。
Type型 PinType別為的，表示針腳的類型。

這些屬性是由 BindableProperty 物件所支援，這表示 Pin 可以是數據系結的目標。如需數據系結 Pin 對象的詳細資訊，請參閱顯示釘選集合。

此外，類別 Pin 會 MarkerClicked 定義和 InfoWindowClicked 事件。點 MarkerClicked 選釘選時會引發事件，並在 InfoWindowClicked 點選資訊視窗時引發事件。 PinClickedEventArgs同時同時伴隨這兩個事件的物件具有單HideInfoWindow一屬性，類型為 bool。

顯示釘選

Pin可以在 XAML 中新增至 Map ：

<ContentPage ...
             xmlns:maps="clr-namespace:Xamarin.Forms.Maps;assembly=Xamarin.Forms.Maps">
     <maps:Map x:Name="map"
               IsShowingUser="True"
               MoveToLastRegionOnLayoutChange="False">
         <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.Pins>
             <maps:Pin Label="Santa Cruz"
                       Address="The city with a boardwalk"
                       Type="Place">
                 <maps:Pin.Position>
                     <maps:Position>
                         <x:Arguments>
                             <x:Double>36.9628066</x:Double>
                             <x:Double>-122.0194722</x:Double>
                         </x:Arguments>
                     </maps:Position>
                 </maps:Pin.Position>
             </maps:Pin>
         </maps:Map.Pins>
     </maps:Map>
</ContentPage>

這個 XAML 會 Map 建立物件，以顯示物件所 MapSpan 指定的區域。此 MapSpan 物件是以物件表示 Position 的緯度和經度為中心，其會延伸0.01緯度和經度度。 Pin物件會加入至Map.Pins集合，並在其 Position 屬性所指定的位置上Map繪製。如需結構的相關信息 Position ，請參閱地圖位置和距離。如需將 XAML 中的自變數傳遞至缺少預設建構函式的物件的相關信息，請參閱在 XAML 中傳遞自變數。

對等的 C# 程式碼為：

using Xamarin.Forms.Maps;
// ...
Map map = new Map
{
  // ...
};
Pin pin = new Pin
{
  Label = "Santa Cruz",
  Address = "The city with a boardwalk",
  Type = PinType.Place,
  Position = new Position(36.9628066, -122.0194722)
};
map.Pins.Add(pin);

警告

無法設定 Pin.Label 屬性會導致ArgumentException在新增至 Map時Pin擲回。

此範例程式代碼會導致在地圖上轉譯單一釘選：

與釘選互動

根據預設， Pin 點選時會顯示其資訊視窗：

點選地圖上的其他地方會關閉信息視窗。

類別 Pin 會 MarkerClicked 定義事件，該事件會在點選時 Pin 引發。不需要處理此事件，才能顯示信息視窗。相反地，當需要通知特定針腳已點選時，應該處理此事件。

類別 Pin 也會定義 InfoWindowClicked 點選資訊窗口時引發的事件。當需要通知特定資訊視窗已點選時，應該處理此事件。

下列程式代碼示範處理這些事件的範例：

using Xamarin.Forms.Maps;
// ...
Pin boardwalkPin = new Pin
{
    Position = new Position(36.9641949, -122.0177232),
    Label = "Boardwalk",
    Address = "Santa Cruz",
    Type = PinType.Place
};
boardwalkPin.MarkerClicked += async (s, args) =>
{
    args.HideInfoWindow = true;
    string pinName = ((Pin)s).Label;
    await DisplayAlert("Pin Clicked", $"{pinName} was clicked.", "Ok");
};

Pin wharfPin = new Pin
{
    Position = new Position(36.9571571, -122.0173544),
    Label = "Wharf",
    Address = "Santa Cruz",
    Type = PinType.Place
};
wharfPin.InfoWindowClicked += async (s, args) =>
{
    string pinName = ((Pin)s).Label;
    await DisplayAlert("Info Window Clicked", $"The info window was clicked for {pinName}.", "Ok");
};

PinClickedEventArgs同時同時伴隨這兩個事件的物件具有單HideInfoWindow一屬性，類型為 bool。當這個屬性設定為 true 事件處理程式內時，將會隱藏信息視窗。

釘選類型

Pin 物件包含 Type 類型的 PinType屬性，代表針腳的類型。 PinType 列舉會定義下列成員：

Generic，表示泛型針腳。
Place，表示位置的釘選。
SavedPin，表示儲存位置的釘選。
SearchResult，表示搜尋結果的釘選。

不過，將 Pin.Type 屬性設定為任何 PinType 成員並不會變更轉譯釘選的外觀。相反地，您必須建立自定義轉譯器來自定義釘選外觀。如需詳細資訊，請參閱自定義地圖釘選。

顯示 PIN 集合

類別 Map 會定義下列屬性：

ItemsSource型 IEnumerable別為的，指定要顯示的專案 IEnumerable 集合。
ItemTemplate型 DataTemplate別為的，指定要 DataTemplate 套用至所顯示專案集合中每個專案的。
ItemTemplateSelector型 DataTemplateSelector別為的，指定 DataTemplateSelector 將在運行時間為項目選擇 DataTemplate 的。

重要

設定 ItemTemplate 和 ItemTemplateSelector 屬性時ItemTemplate，屬性會優先使用。

Map可以使用資料系結將其ItemsSource屬性系結至IEnumerable集合，以釘選填入：

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:maps="clr-namespace:Xamarin.Forms.Maps;assembly=Xamarin.Forms.Maps"
             x:Class="WorkingWithMaps.PinItemsSourcePage">
    <Grid>
        ...
        <maps:Map x:Name="map"
                  ItemsSource="{Binding Locations}">
            <maps:Map.ItemTemplate>
                <DataTemplate>
                    <maps:Pin Position="{Binding Position}"
                              Address="{Binding Address}"
                              Label="{Binding Description}" />
                </DataTemplate>
            </maps:Map.ItemTemplate>
        </maps:Map>
        ...
    </Grid>
</ContentPage>

屬性ItemsSource數據會系結至Locations連接的 viewmodel 屬性，該屬性會ObservableCollectionLocation傳回物件的，這是自定義型別。每個Location物件都會Address定義型string別的和 Description 屬性，以及 Position 型別 Position的屬性。

集合中 IEnumerable 每個項目的外觀都是藉由將屬性設定 ItemTemplate 為 DataTemplate Pin ，其中包含數據系結至適當屬性之物件的。

下列螢幕快照顯示 Map 使用資料系結來 Pin 顯示集合：

選擇運行時間的項目外觀

您可以藉由將屬性設定ItemTemplateSelector為 DataTemplateSelector，在執行時間根據專案值選擇集合中IEnumerable每個項目的外觀：

<ContentPage ...
             xmlns:local="clr-namespace:WorkingWithMaps"
             xmlns:maps="clr-namespace:Xamarin.Forms.Maps;assembly=Xamarin.Forms.Maps">
    <ContentPage.Resources>
        <local:MapItemTemplateSelector x:Key="MapItemTemplateSelector">
            <local:MapItemTemplateSelector.DefaultTemplate>
                <DataTemplate>
                    <maps:Pin Position="{Binding Position}"
                              Address="{Binding Address}"
                              Label="{Binding Description}" />
                </DataTemplate>
            </local:MapItemTemplateSelector.DefaultTemplate>
            <local:MapItemTemplateSelector.XamarinTemplate>
                <DataTemplate>
                    <!-- Change the property values, or the properties that are bound to. -->
                    <maps:Pin Position="{Binding Position}"
                              Address="{Binding Address}"
                              Label="Xamarin!" />
                </DataTemplate>
            </local:MapItemTemplateSelector.XamarinTemplate>    
        </local:MapItemTemplateSelector>
    </ContentPage.Resources>

    <Grid>
        ...
        <maps:Map x:Name="map"
                  ItemsSource="{Binding Locations}"
                  ItemTemplateSelector="{StaticResource MapItemTemplateSelector}" />
        ...
    </Grid>
</ContentPage>

下列範例顯示類別 MapItemTemplateSelector ：

public class MapItemTemplateSelector : DataTemplateSelector
{
    public DataTemplate DefaultTemplate { get; set; }
    public DataTemplate XamarinTemplate { get; set; }

    protected override DataTemplate OnSelectTemplate(object item, BindableObject container)
    {
        return ((Location)item).Address.Contains("San Francisco") ? XamarinTemplate : DefaultTemplate;
    }
}

類別 MapItemTemplateSelector 會 DefaultTemplate 定義和 XamarinTemplate DataTemplate 屬性，這些屬性會設定為不同的數據範本。當專案具有包含「San Francisco」的位址時，此方法 OnSelectTemplate 會 XamarinTemplate傳回，當點選時 Pin ，會將「Xamarin」顯示為標籤。當項目沒有包含「San Francisco」的位址時， OnSelectTemplate 此方法會傳 DefaultTemplate回。

注意

這項功能的使用案例是根據Pin子類型，將子類別Pin對象的屬性系結至不同的屬性。

如需數據範本選取器的詳細資訊，請參閱建立 Xamarin.Forms DataTemplateSelector。

共用方式為

Xamarin.Forms 地圖釘選

顯示釘選

與釘選互動

釘選類型

顯示 PIN 集合

選擇運行時間的項目外觀

其他資源

共用方式為

Xamarin.Forms 地圖釘選

顯示釘選

與釘選互動

釘選類型

顯示 PIN 集合

選擇運行時間的項目外觀

相關連結

其他資源