Mapeamento

Navegue pelo exemplo

O controle .NET Multi-platform App UI (.NET MAUI) Map é uma exibição multiplataforma para exibir e anotar mapas. O Map controle usa o controle de mapa nativo em cada plataforma e é fornecido pelo pacote NuGet Microsoft.Maui.Controls.Maps.

Importante

O Map controle não é suportado no Windows devido à falta de um controle de mapa no WinUI. No entanto, o pacote NuGet CommunityToolkit.Maui.Maps fornece acesso ao Bing Maps por meio de um WebView no Windows. Para obter mais informações, consulte Introdução.

Instalação

O Map controle usa o controle de mapa nativo em cada plataforma. Isso fornece uma experiência de mapas rápida e familiar para os usuários, mas significa que algumas etapas de configuração são necessárias para aderir aos requisitos de API de cada plataforma.

Inicialização do mapa

O Map controle é fornecido pelo pacote NuGet Microsoft.Maui.Controls.Maps, que deve ser adicionado ao seu projeto de aplicativo .NET MAUI.

Depois de instalar o pacote NuGet, ele deve ser inicializado em seu aplicativo chamando o UseMauiMapMauiAppBuilder método no objeto no CreateMauiApp método de sua MauiProgram classe:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            })
            .UseMauiMaps();

        return builder.Build();
    }
}

Depois que o pacote NuGet for adicionado e inicializado, Map as APIs poderão ser usadas em seu projeto.

Configuração da plataforma

Configuração adicional é necessária no Android antes que o mapa seja exibido. Além disso, no iOS, Android e Mac Catalyst, o acesso à localização do usuário requer que as permissões de localização tenham sido concedidas ao seu aplicativo.

iOS e Mac Catalyst

A exibição e a interação com um mapa no iOS e no Mac Catalyst não exigem nenhuma configuração adicional. No entanto, para acessar os serviços de localização, você deve definir as solicitações de serviços de localização necessárias em Info.plist. Estes serão normalmente um ou mais dos seguintes:

• NSLocationAlwaysAndWhenInUseUsageDescription – para usar os serviços de localização em todos os momentos.
• NSLocationWhenInUseUsageDescription – para usar serviços de localização quando o aplicativo está em uso.

Para obter mais informações, consulte Escolhendo a autorização de serviços de local a ser solicitada no developer.apple.com.

A representação XML para essas chaves em Info.plist é mostrada abaixo. Você deve atualizar os string valores para refletir como seu aplicativo está usando as informações de localização:

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Can we use your location at all times?</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Can we use your location when your app is being used?</string>

Um prompt é exibido quando o aplicativo tenta acessar a localização do usuário, solicitando acesso:

Android

O processo de configuração para exibir e interagir com um mapa no Android é:

1. Obtenha uma chave da API do Google Maps e adicione-a ao manifesto do seu aplicativo.
2. Especifique o número da versão dos serviços do Google Play no manifesto.
3. [opcional] Especifique permissões de local no manifesto.
4. [opcional] Especifique a permissão WRITE_EXTERNAL_STORAGE no manifesto.

Obter uma chave da API do Google Maps

Para usar o controle no Android, você deve gerar uma chave de API, que será consumida pelo SDK do Google Maps no qual o MapMap controle depende do Android. Para fazer isso, siga as instruções em Configurar no Google Cloud Console e Usar chaves de API no developers.google.com.

Depois de obter uma chave de API, ela deve ser adicionada <application> ao elemento do arquivo Platforms/Android/AndroidManifest.xml especificando-a como o valor dos com.google.android.geo.API_KEY metadados:

<application android:allowBackup="true" android:icon="@mipmap/appicon" android:roundIcon="@mipmap/appicon_round" android:supportsRtl="true">
  <meta-data android:name="com.google.android.geo.API_KEY" android:value="PASTE-YOUR-API-KEY-HERE" />
</application>

Isso incorpora a chave de API no manifesto. Sem uma chave de API válida, o Map controle exibirá uma grade em branco.

Observação

com.google.android.geo.API_KEY é o nome de metadados recomendado para a chave de API. Uma chave com esse nome pode ser usada para autenticar várias APIs baseadas no Google Maps no Android. Para compatibilidade com versões anteriores, o nome dos com.google.android.maps.v2.API_KEY metadados pode ser usado, mas só permite a autenticação para a API v2 do Android Maps. Um aplicativo só pode especificar um dos nomes de metadados da chave da API.

Especificar o número da versão dos serviços do Google Play

Adicione a seguinte declaração dentro do <application> elemento de AndroidManifest.xml:

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />

Isso incorpora a versão dos serviços do Google Play com a qual o aplicativo foi compilado no manifesto.

Especificar permissões de localização

Se seu aplicativo precisar acessar o local do usuário, você deverá solicitar permissão adicionando as ACCESS_COARSE_LOCATION permissões ou (ou ACCESS_FINE_LOCATION ambas) ao manifesto, como filho do <manifest> elemento:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  ...
  <!-- Required to access the user's location -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

A ACCESS_COARSE_LOCATION permissão permite que a API use Wi-Fi ou dados móveis, ou ambos, para determinar a localização do dispositivo. As ACCESS_FINE_LOCATION permissões permitem que a API use o Sistema de Posicionamento Global (GPS), Wi-Fi ou dados móveis para determinar uma localização precisa possível.

Um prompt é exibido quando o aplicativo tenta acessar a localização do usuário, solicitando acesso:

Como alternativa, essas permissões podem ser habilitadas no editor de manifesto do Android do Visual Studio.

Especifique a permissão WRITE_EXTERNAL_STORAGE

Se seu aplicativo tiver como alvo a API 22 ou inferior, será necessário adicionar a WRITE_EXTERNAL_STORAGE permissão ao manifesto, como filho do <manifest> elemento:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Isso não será necessário se seu aplicativo tiver como alvo a API 23 ou superior.

Controle de mapeamento

A Map classe define as seguintes propriedades que controlam a aparência e o comportamento do mapa:

• IsShowingUser, do tipo bool, indica se o mapa está mostrando a localização atual do usuário.
• ItemsSource, do tipo IEnumerable, que especifica a coleção de itens PIN IEnumerable a serem exibidos.
• ItemTemplate, do tipo DataTemplate, que especifica o DataTemplate a ser aplicado a cada item na coleção de pinos exibidos.
• ItemTemplateSelector, do tipo DataTemplateSelector, que especifica o DataTemplateSelector que será usado para escolher um para um DataTemplate PIN em tempo de execução.
• IsScrollEnabled, do tipo bool, determina se o mapa tem permissão para rolar.
• IsTrafficEnabled, do tipo bool, indica se os dados de tráfego estão sobrepostos no mapa.
• IsZoomEnabled, do tipo bool, determina se o mapa tem permissão para ampliar.
• MapElements, do tipo IList<MapElement>, representa a lista de elementos no mapa, como polígonos e polilinhas.
• MapType, do tipo MapType, indica o estilo de exibição do mapa.
• Pins, do tipo IList<Pin>, representa a lista de pinos no mapa.
• VisibleRegion, do tipo MapSpan, retorna a região do mapa exibida no momento.

Essas propriedades, com exceção das propriedades , e VisibleRegion , são apoiadas MapElementspor BindableProperty objetos, Pinso que significa que elas podem ser alvos de associações de dados.

A Map classe também define um MapClicked evento que é disparado quando o mapa é tocado. O MapClickedEventArgs objeto que acompanha o evento tem uma única propriedade chamada Location, do tipo Location. Quando o evento é acionado, a Location propriedade é definida como o local do mapa que foi tocado. Para obter informações sobre a Location classe, consulte Localização e distância.

Para obter informações sobre o ItemsSource, e ItemTemplateSelector propriedades, ItemTemplateconsulte Exibir uma coleção de pinos.

Exibir um mapa

Um Map pode ser exibido adicionando-o a um layout ou página:

<ContentPage ...
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps">
    <maps:Map x:Name="map" />
</ContentPage>

Este é o código C# equivalente:

using Map = Microsoft.Maui.Controls.Maps.Map;

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

Este exemplo chama o construtor padrão Map , que centraliza o mapa em Maui, Havaí::

Como alternativa, um argumento pode ser passado para um MapSpanMap construtor para definir o ponto central e o nível de zoom do mapa quando ele é carregado. Para obter mais informações, consulte Exibir um local específico em um mapa.

Importante

.NET MAUI tem dois Map tipos - Microsoft.Maui.Controls.Maps.Map e Microsoft.Maui.ApplicationModel.Map. Como o namespace é uma das diretivas do .NET MAUI, ao usar o Microsoft.Maui.ApplicationModelMicrosoft.Maui.Controls.Maps.Map controle do código, você terá que qualificar totalmente seu Map uso ou usar um alias global usingde uso.

Tipos de mapa

A Map.MapType propriedade pode ser definida como um MapType membro de enumeração para definir o estilo de exibição do mapa. A enumeração MapType define os seguintes membros:

• Street Especifica que um mapa de ruas será exibido.
• Satellite Especifica que um mapa contendo imagens de satélite será exibido.
• Hybrid especifica que um mapa combinando dados de rua e satélite será exibido.

Por padrão, um exibirá um Map mapa de ruas se a MapType propriedade estiver indefinida. Como alternativa, a MapType propriedade pode ser definida como um dos MapType membros da enumeração:

<maps:Map MapType="Satellite" />

Este é o código C# equivalente:

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

Exibir um local específico em um mapa

A região de um mapa a ser exibida quando um mapa é carregado pode ser definida passando um MapSpan argumento para o Map construtor:

<ContentPage ...
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
             xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
    <maps:Map>
        <x:Arguments>
            <maps:MapSpan>
                <x:Arguments>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>36.9628066</x:Double>
                            <x:Double>-122.0194722</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                    <x:Double>0.01</x:Double>
                    <x:Double>0.01</x:Double>
                </x:Arguments>
            </maps:MapSpan>
        </x:Arguments>
    </maps:Map>
</ContentPage>

Este é o código C# equivalente:

using Microsoft.Maui.Maps;
using Map = Microsoft.Maui.Controls.Maps.Map;
...

Location location = new Location(36.9628066, -122.0194722);
MapSpan mapSpan = new MapSpan(location, 0.01, 0.01);
Map map = new Map(mapSpan);

Este exemplo cria um Map objeto que mostra a região especificada pelo MapSpan objeto. O MapSpan objeto é centrado na latitude e longitude representadas por um Location objeto, e abrange 0,01 latitude e 0,01 graus de longitude. Para obter informações sobre a Location classe, consulte Localização e distância. Para obter informações sobre como passar argumentos em XAML, consulte Passar argumentos em XAML.

O resultado é que, quando o mapa é exibido, ele é centralizado em um local específico e abrange um número específico de graus de latitude e longitude:

Criar um objeto MapSpan

Há uma série de abordagens para a criação MapSpan de objetos. Uma abordagem comum é fornecer os argumentos necessários ao MapSpan construtor. Estes são uma latitude e longitude representadas por um Location objeto, e valores que representam os graus de latitude e double longitude que são estendidos pelo MapSpan. Para obter informações sobre a Location classe, consulte Localização e distância.

Como alternativa, há três métodos na MapSpan classe que retornam novos MapSpan objetos:

1. ClampLatitudeRetorna um com o mesmo LongitudeDegrees que a instância de classe do método e um MapSpan raio definido por seus north argumentos E south .
2. FromCenterAndRadius retorna um MapSpan que é definido por seus Location e Distance argumentos.
3. WithZoom Retorna um com o mesmo centro que a instância de classe do método, mas com um MapSpan raio multiplicado por seu double argumento.

Para obter informações sobre a Distance estrutura, consulte Localização e distância.

Depois que um MapSpan tiver sido criado, as seguintes propriedades podem ser acessadas para recuperar dados sobre ele:

• Center, do tipo Location, que representa a localização no centro geográfico do MapSpan.
• LatitudeDegrees, do tipo double, que representa os graus de latitude que são estendidos pelo MapSpan.
• LongitudeDegrees, do tipo double, que representa os graus de longitude que são atravessados pelo MapSpan.
• Radius, do tipo Distance, que representa o raio MapSpan .

Mover o mapa

O Map.MoveToRegion método pode ser chamado para alterar a posição e o nível de zoom de um mapa. Esse método aceita um MapSpan argumento que define a região do mapa a ser exibida e seu nível de zoom.

O código a seguir mostra um exemplo de como mover a região exibida em um mapa:

using Microsoft.Maui.Maps;
using Microsoft.Maui.Controls.Maps.Map;
...

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

Ampliar o mapa

O nível de zoom de um Map pode ser alterado sem alterar sua localização. Isso pode ser feito usando a interface do usuário do mapa ou programaticamente chamando o método com um MapSpan argumento que usa o MoveToRegion local atual como argumentoLocation:

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

Neste exemplo, o método é chamado com um MapSpan argumento que especifica o local atual do mapa, por meio Map.VisibleRegion da propriedade, e o MoveToRegion nível de zoom como graus de latitude e longitude. O resultado geral é que o nível de zoom do mapa é alterado, mas sua localização não. Uma abordagem alternativa para implementar o zoom em um mapa é usar o método para controlar o MapSpan.WithZoom fator de zoom.

Importante

Ampliar um mapa, seja por meio da interface do usuário do mapa ou programaticamente, requer que a Map.IsZoomEnabled propriedade seja true. Para obter mais informações sobre essa propriedade, consulte Desabilitar zoom.

Personalizar o comportamento do mapa

O comportamento de um Map pode ser personalizado definindo algumas de suas propriedades e manipulando o MapClicked evento.

Observação

A personalização adicional do comportamento do mapa pode ser obtida personalizando seu manipulador. Para obter mais informações, consulte Personalizar controles com manipuladores.

Mostrar dados de tráfego

A Map classe define uma IsTrafficEnabled propriedade do tipo bool. Por padrão, essa propriedade é false, o que indica que os dados de tráfego não serão sobrepostos no mapa. Quando essa propriedade é definida como true, os dados de tráfego são sobrepostos no mapa:

<maps:Map IsTrafficEnabled="true" />

Este é o código C# equivalente:

Map map = new Map
{
    IsTrafficEnabled = true
};

Desativar rolagem

A Map classe define uma IsScrollEnabled propriedade do tipo bool. Por padrão, essa propriedade é true, o que indica que o mapa tem permissão para rolar. Quando essa propriedade é definida como false, o mapa não rola:

<maps:Map IsScrollEnabled="false" />

Este é o código C# equivalente:

Map map = new Map
{
    IsScrollEnabled = false
};

Desativar zoom

A Map classe define uma IsZoomEnabled propriedade do tipo bool. Por padrão, essa propriedade é true, o que indica que o zoom pode ser executado no mapa. Quando essa propriedade é definida como false, o mapa não pode ser ampliado:

<maps:Map IsZoomEnabled="false" />

Este é o código C# equivalente:

Map map = new Map
{
    IsZoomEnabled = false
};

Mostrar a localização do usuário

A Map classe define uma IsShowingUser propriedade do tipo bool. Por padrão, essa propriedade é false, que indica que o mapa não está mostrando a localização atual do usuário. Quando essa propriedade é definida como true, o mapa mostra a localização atual do usuário:

<maps:Map IsShowingUser="true" />

Este é o código C# equivalente:

Map map = new Map
{
    IsShowingUser = true
};

Importante

O acesso à localização do usuário requer que as permissões de localização tenham sido concedidas ao aplicativo. Para obter mais informações, consulte Configuração da plataforma.

Cliques no mapa

A Map classe define um MapClicked evento que é acionado quando o mapa é tocado. O MapClickedEventArgs objeto que acompanha o evento tem uma única propriedade chamada Location, do tipo Location. Quando o evento é acionado, a Location propriedade é definida como o local do mapa que foi tocado. Para obter informações sobre a Location classe, consulte Localização e distância.

O exemplo de código a seguir mostra um manipulador de eventos para o MapClicked evento:

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

Neste exemplo, o manipulador de eventos gera a latitude e a longitude que representam o OnMapClicked local do mapa tocado. O manipulador de eventos deve ser registrado com o MapClicked evento:

<maps:Map MapClicked="OnMapClicked" />

Este é o código C# equivalente:

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

Localização e distância

O Microsoft.Maui.Devices.Sensors namespace contém uma Location classe que normalmente é usada ao posicionar um mapa e seus pinos. O Microsoft.Maui.Maps namespace contém uma Distance struct que pode ser usada opcionalmente ao posicionar um mapa.

Localidade

A Location classe encapsula um local armazenado como valores de latitude e longitude. Essa classe define as seguintes propriedades:

• Accuracy, do tipo double?, que representa a precisão horizontal do Location, em metros.
• Altitude, do tipo double?, que representa a altitude em metros em um sistema de referência especificado pela AltitudeReferenceSystem propriedade.
• AltitudeReferenceSystem, do tipo AltitudeReferenceSystem, que especifica o sistema de referência no qual o valor de altitude é fornecido.
• Course, do tipo double?, que indica o valor dos graus em relação ao norte verdadeiro.
• IsFromMockProvider, do tipo bool, que indica se a localização é do GPS ou de um provedor de localização fictício.
• Latitude, do tipo double, que representa a latitude do local em graus decimais.
• Longitude, do tipo double, que representa a longitude do local em graus decimais.
• Speed, do tipo double?, que representa a velocidade em metros por segundo.
• Timestamp, do tipo DateTimeOffset, que representa o carimbo de data/hora quando o Location foi criado.
• VerticalAccuracy, do tipo double?, que especifica a precisão vertical do Location, em metros.

Location Os Location objetos são criados com uma das sobrecargas do construtor, que normalmente exigem no mínimo argumentos de latitude e longitude especificados como double valores:

Location location = new Location(36.9628066, -122.0194722);

Ao criar um Location objeto, o valor de latitude será fixado entre -90,0 e 90,0, e o valor de longitude será fixado entre -180,0 e 180,0.

Observação

A GeographyUtils classe tem um método de extensão que converte um valor de graus em radianos e um método de extensão que converte um ToDegreesToRadiansdoubledouble valor de radianos em graus.

A Location classe também tem CalculateDistance métodos que calculam a distância entre dois locais.

Distância

A Distance struct encapsula uma distância armazenada como um double valor, que representa a distância em metros. Essa estrutura define três propriedades somente leitura:

• Kilometers, do tipo double, que representa a distância em quilômetros que é percorrida pelo Distance.
• Meters, do tipo double, que representa a distância em metros que é estendida pelo Distance.
• Miles, do tipo double, que representa a distância em milhas que é percorrida pelo Distance.

Distance objetos podem ser criados com o Distance construtor, que requer um argumento meters especificado como um double:

Distance distance = new Distance(1450.5);

Como alternativa, os objetos podem ser criados com os FromKilometersmétodos , FromMetersDistance , FromMilese BetweenPositions factory:

Distance distance1 = Distance.FromKilometers(1.45); // argument represents the number of kilometers
Distance distance2 = Distance.FromMeters(1450.5);   // argument represents the number of meters
Distance distance3 = Distance.FromMiles(0.969);     // argument represents the number of miles
Distance distance4 = Distance.BetweenPositions(location1, location2);

marcadores

O Map controle permite que os locais sejam marcados com Pin objetos. A Pin é um marcador de mapa que abre uma janela de informações quando tocado:

Quando um Pin objeto é adicionado à Map.Pins coleção, o pino é renderizado no mapa.

A classe Pin tem as propriedades a seguir:

• Address, do tipo string, que normalmente representa o endereço do local do pino. No entanto, pode ser qualquer string conteúdo, não apenas um endereço.
• Label, do tipo string, que normalmente representa o título do pino.
• Location, do tipo Location, que representa a latitude e longitude do pino.
• Type, do tipo , que representa o tipo PinTypede pino.

Essas propriedades são apoiadas por BindableProperty objetos, o que significa que um Pin pode ser o destino de associações de dados. Para obter mais informações sobre objetos de vinculação Pin de dados, consulte Exibir uma coleção de pinos.

Além disso, a Pin classe define MarkerClicked e InfoWindowClicked eventos. O MarkerClicked evento é disparado quando um pino é tocado e o evento é disparado InfoWindowClicked quando a janela de informações é tocada. O PinClickedEventArgs objeto que acompanha ambos os eventos tem uma única HideInfoWindow propriedade, do tipo bool.

Exibir um alfinete

Um Pin pode ser adicionado a um Map em XAML:

<ContentPage ...
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
             xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
    <maps:Map x:Name="map">
        <x:Arguments>
            <maps:MapSpan>
                <x:Arguments>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>36.9628066</x:Double>
                            <x:Double>-122.0194722</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                    <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.Location>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>36.9628066</x:Double>
                            <x:Double>-122.0194722</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                </maps:Pin.Location>
            </maps:Pin>
        </maps:Map.Pins>
    </maps:Map>
</ContentPage>

Esse XAML cria um Map objeto que mostra a região especificada pelo MapSpan objeto. O MapSpan objeto é centrado na latitude e longitude representadas por um Location objeto, que se estende 0,01 graus de latitude e longitude. Um Pin objeto é adicionado à Map.Pins coleção e desenhado Map no no local especificado por sua Location propriedade. Para obter informações sobre a Location classe, consulte Localização e distância. Para obter informações sobre como passar argumentos em XAML para objetos que não possuem construtores padrão, consulte Passar argumentos em XAML.

Este é o código C# equivalente:

using Microsoft.Maui.Controls.Maps;
using Microsoft.Maui.Maps;
using Map = Microsoft.Maui.Controls.Maps.Map;
...

Map map = new Map
{
  ...
};

Pin pin = new Pin
{
  Label = "Santa Cruz",
  Address = "The city with a boardwalk",
  Type = PinType.Place,
  Location = new Location(36.9628066, -122.0194722)
};
map.Pins.Add(pin);

Este código de exemplo resulta em um único pino sendo renderizado em um mapa:

Interagir com um alfinete

Por padrão, quando um Pin é tocado sua janela de informações é exibida:

Tocar em outro lugar no mapa fecha a janela de informações.

A Pin classe define um evento, que é acionado quando um PinMarkerClicked é tocado. Não é necessário manipular esse evento para exibir a janela de informações. Em vez disso, esse evento deve ser manipulado quando houver um requisito para ser notificado de que um pino específico foi tocado.

A Pin classe também define um InfoWindowClicked evento que é acionado quando uma janela de informações é tocada. Esse evento deve ser tratado quando houver um requisito para ser notificado de que uma janela de informações específica foi tocada.

O código a seguir mostra um exemplo de manipulação desses eventos:

using Microsoft.Maui.Controls.Maps;
using Microsoft.Maui.Maps;
using Map = Microsoft.Maui.Controls.Maps.Map;
...

Pin boardwalkPin = new Pin
{
    Location = new Location(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
{
    Location = new Location(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");
};

O PinClickedEventArgs objeto que acompanha ambos os eventos tem uma única HideInfoWindow propriedade, do tipo bool. Quando essa propriedade é definida como true dentro de um manipulador de eventos, a janela de informações será ocultada.

Tipos de pinos

Pin Os objetos incluem uma Type propriedade, do tipo , que representa o tipo PinTypede PIN. A enumeração PinType define os seguintes membros:

• Generic, representa um pino genérico.
• Place, representa um alfinete para um lugar.
• SavedPin, representa um alfinete para um local salvo.
• SearchResult, representa um alfinete para um resultado de pesquisa.

No entanto, definir a Pin.Type propriedade como qualquer PinType membro não altera a aparência do pino renderizado. Em vez disso, você deve personalizar o manipulador para personalizar a aparência do Pin pino. Para obter mais informações sobre a personalização do manipulador, consulte Personalizar controles com manipuladores.

Exibir uma coleção de marcadores

A Map classe define as seguintes propriedades vinculáveis:

• ItemsSource, do tipo IEnumerable, que especifica a coleção de itens PIN IEnumerable a serem exibidos.
• ItemTemplate, do tipo DataTemplate, que especifica o DataTemplate a ser aplicado a cada item na coleção de pinos exibidos.
• ItemTemplateSelector, do tipo DataTemplateSelector, que especifica o DataTemplateSelector que será usado para escolher um para um DataTemplate PIN em tempo de execução.

Importante

A ItemTemplate propriedade tem precedência quando as ItemTemplate propriedades e ItemTemplateSelector são definidas.

Um Map pode ser preenchido com pinos usando a vinculação de dados para vincular sua ItemsSource propriedade a uma IEnumerable coleção:

<ContentPage ...
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps">    
    <Grid>
        ...
        <maps:Map x:Name="map"
                  ItemsSource="{Binding Positions}">
            <maps:Map.ItemTemplate>
                <DataTemplate>
                    <maps:Pin Location="{Binding Location}"
                              Address="{Binding Address}"
                              Label="{Binding Description}" />
                </DataTemplate>    
            </maps:Map.ItemTemplate>
        </maps:Map>
        ...
    </Grid>
</ContentPage>

Os ItemsSource dados da propriedade se vinculam à Positions propriedade do modelo de exibição conectado, que retorna um de Position objetos, que é um ObservableCollection tipo personalizado. Cada Position objeto define Address e propriedades, do tipo , e Description uma Location propriedade, do tipo Locationstring.

A aparência de cada item na IEnumerable coleção é definida definindo a ItemTemplate propriedade como um que contém um DataTemplatePin objeto que os dados se vinculam às propriedades apropriadas.

A captura de tela a seguir mostra uma exibição de uma MapPin coleção usando associação de dados:

Escolher a aparência do item em tempo de execução

A aparência de cada item na coleção pode ser escolhida em IEnumerable tempo de execução, com base no valor do item, definindo a ItemTemplateSelector propriedade como :DataTemplateSelector

<ContentPage ...
             xmlns:templates="clr-namespace:WorkingWithMaps.Templates"
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps">
    <ContentPage.Resources>
       <templates:MapItemTemplateSelector x:Key="MapItemTemplateSelector">
           <templates:MapItemTemplateSelector.DefaultTemplate>
               <DataTemplate>
                   <maps:Pin Location="{Binding Location}"
                             Address="{Binding Address}"
                             Label="{Binding Description}" />
               </DataTemplate>
           </templates:MapItemTemplateSelector.DefaultTemplate>
           <templates:MapItemTemplateSelector.SanFranTemplate>
               <DataTemplate>
                   <maps:Pin Location="{Binding Location}"
                             Address="{Binding Address}"
                             Label="Xamarin!" />
               </DataTemplate>
           </templates:MapItemTemplateSelector.SanFranTemplate>    
       </templates:MapItemTemplateSelector>
    </ContentPage.Resources>

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

O exemplo a seguir mostra a classe MapItemTemplateSelector:

using WorkingWithMaps.Models;

namespace WorkingWithMaps.Templates;

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

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

A MapItemTemplateSelector classe define DefaultTemplate e SanFranTemplateDataTemplate propriedades que são definidas para modelos de dados diferentes. O OnSelectTemplate método retorna o , que exibe "Xamarin" como um rótulo quando um é tocado, quando o SanFranTemplateitem tem um Pin endereço que contém "San Francisco". Quando o item não tem um endereço que contém "São Francisco", o método retorna o OnSelectTemplateDefaultTemplate.

Observação

Um caso de uso para essa funcionalidade é vincular propriedades de objetos subclassificados Pin a propriedades diferentes, com base no Pin subtipo.

Para obter mais informações sobre seletores de modelo de dados, consulte Criar um DataTemplateSelector.

Polígonos, polilinhas e círculos

Polygon, Polylinee Circle os elementos permitem realçar áreas específicas em um mapa. A Polygon é uma forma totalmente fechada que pode ter um traçado e cor de preenchimento. A Polyline é uma linha que não abrange totalmente uma área. A Circle destaca uma área circular do mapa:

As Polygonclasses , e Circle derivam da MapElement classe, Polylineque expõe as seguintes propriedades vinculáveis:

• StrokeColor é um Color objeto que determina a cor da linha.
• StrokeWidth é um float objeto que determina a largura da linha.

A Polygon classe define uma propriedade vinculável adicional:

• FillColor é um Color objeto que determina a cor de plano de fundo do polígono.

Além disso, as Polygon classes e Polyline definem uma propriedade, que é uma GeoPath lista de Location objetos que especificam os pontos da forma.

A Circle classe define as seguintes propriedades vinculáveis:

• Center é um Location objeto que define o centro do círculo, em latitude e longitude.
• Radius é um Distance objeto que define o raio do círculo em metros, quilômetros ou milhas.
• FillColor é uma Color propriedade que determina a cor dentro do perímetro do círculo.

Criar um polígono

Um Polygon objeto pode ser adicionado a um mapa instanciando-o e adicionando-o à coleção do MapElements mapa:

<ContentPage ...
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
             xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
    <maps:Map>
        <maps:Map.MapElements>
            <maps:Polygon StrokeColor="#FF9900"
                          StrokeWidth="8"
                          FillColor="#88FF9900">
                <maps:Polygon.Geopath>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>47.6458676</x:Double>
                            <x:Double>-122.1356007</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>47.6458097</x:Double>
                            <x:Double>-122.142789</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                    ...
                </maps:Polygon.Geopath>
            </maps:Polygon>
        </maps:Map.MapElements>
    </maps:Map>
</ContentPage>

Este é o código C# equivalente:

using Microsoft.Maui.Controls.Maps;
using Microsoft.Maui.Maps;
using Map = Microsoft.Maui.Controls.Maps.Map;
...

Map map = new Map();

// Instantiate a polygon
Polygon polygon = new Polygon
{
    StrokeWidth = 8,
    StrokeColor = Color.FromArgb("#1BA1E2"),
    FillColor = Color.FromArgb("#881BA1E2"),
    Geopath =
    {
        new Location(47.6368678, -122.137305),
        new Location(47.6368894, -122.134655),
        ...
    }
};

// Add the polygon to the map's MapElements collection
map.MapElements.Add(polygon);

As StrokeColor propriedades e StrokeWidth são especificadas para definir o contorno do polígono. Neste exemplo, o valor da propriedade corresponde ao valor da propriedade, mas tem um valor alfa especificado para torná-lo transparente, permitindo que o mapa subjacente fique visível por meio da FillColorStrokeColor forma. A GeoPath propriedade contém uma lista de objetos que definem as coordenadas geográficas dos pontos de Location polígono. Um Polygon objeto é renderizado no mapa depois de ter sido adicionado à MapElements coleção do Map.

Observação

A Polygon é uma forma totalmente fechada. O primeiro e o último pontos serão automaticamente conectados se não corresponderem.

Criar uma polilinha

Um Polyline objeto pode ser adicionado a um mapa instanciando-o e adicionando-o à coleção do MapElements mapa:

<ContentPage ...
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
             xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
    <maps:Map>
        <maps:Map.MapElements>
            <maps:Polyline StrokeColor="Black"
                           StrokeWidth="12">
                <maps:Polyline.Geopath>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>47.6381401</x:Double>
                            <x:Double>-122.1317367</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>47.6381473</x:Double>
                            <x:Double>-122.1350841</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                    ...
                </maps:Polyline.Geopath>
            </maps:Polyline>
        </maps:Map.MapElements>
    </maps:Map>
</ContentPage>

Este é o código C# equivalente:

using Microsoft.Maui.Controls.Maps;
using Microsoft.Maui.Maps;
using Map = Microsoft.Maui.Controls.Maps.Map;
...

Map map = new Map();

// instantiate a polyline
Polyline polyline = new Polyline
{
    StrokeColor = Colors.Blue,
    StrokeWidth = 12,
    Geopath =
    {
        new Location(47.6381401, -122.1317367),
        new Location(47.6381473, -122.1350841),
        ...
    }
};

// Add the Polyline to the map's MapElements collection
map.MapElements.Add(polyline);

As StrokeColor propriedades e StrokeWidth são especificadas para definir a aparência da linha. A GeoPath propriedade contém uma lista de objetos que definem as coordenadas geográficas dos pontos de Location polilinha. Um Polyline objeto é renderizado no mapa depois de ter sido adicionado à MapElements coleção do Map.

Criar um círculo

Um Circle objeto pode ser adicionado a um mapa instanciando-o e adicionando-o à coleção do MapElements mapa:

<ContentPage ...
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
             xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
    <maps:Map>
        <maps:Map.MapElements>
            <maps:Circle StrokeColor="#88FF0000"
                         StrokeWidth="8"
                         FillColor="#88FFC0CB">
                <maps:Circle.Center>
                    <sensors:Location>
                        <x:Arguments>
                            <x:Double>37.79752</x:Double>
                            <x:Double>-122.40183</x:Double>
                        </x:Arguments>
                    </sensors:Location>
                </maps:Circle.Center>
                <maps:Circle.Radius>
                    <maps:Distance>
                        <x:Arguments>
                            <x:Double>250</x:Double>
                        </x:Arguments>
                    </maps:Distance>
                </maps:Circle.Radius>
            </maps:Circle>             
        </maps:Map.MapElements>
    </maps:Map>
</ContentPage>

Este é o código C# equivalente:

using Microsoft.Maui.Controls.Maps;
using Microsoft.Maui.Maps;
using Map = Microsoft.Maui.Controls.Maps.Map;

Map map = new Map();

// Instantiate a Circle
Circle circle = new Circle
{
    Center = new Location(37.79752, -122.40183),
    Radius = new Distance(250),
    StrokeColor = Color.FromArgb("#88FF0000"),
    StrokeWidth = 8,
    FillColor = Color.FromArgb("#88FFC0CB")
};

// Add the Circle to the map's MapElements collection
map.MapElements.Add(circle);

A localização do Circle no Mapa é determinada pelo valor das Center propriedades e Radius . A Center propriedade define o centro do círculo, em latitude e longitude, enquanto a Radius propriedade define o raio do círculo em metros. As StrokeColor propriedades e StrokeWidth são especificadas para definir o contorno do círculo. O FillColor valor da propriedade especifica a cor dentro do perímetro do círculo. Neste exemplo, ambos os valores de cor especificam um canal alfa, permitindo que o mapa subjacente seja visível através do círculo. O Circle objeto é renderizado no mapa depois de ter sido adicionado à MapElements coleção do Map.

Observação

A GeographyUtils classe tem um método de extensão que converte um ToCircumferencePositionsCircle objeto (que define Center e valores de propriedade) em uma lista de objetos que compõem as coordenadas de Location latitude e Radius longitude do perímetro do círculo.

Geocodificação e geolocalização

A Geocoding classe, no Microsoft.Maui.Devices.Sensors namespace, pode ser usada para geocodificar um marcador para coordenadas posicionais e inverter coordenadas geográficas para um marcador. Para obter mais informações, consulte Geocodificação.

A Geolocation classe, no Microsoft.Maui.Devices.Sensors namespace, pode ser usada para recuperar as coordenadas de geolocalização atuais do dispositivo. Para obter mais informações, consulte Localização geográfica.

Inicie o aplicativo de mapa nativo

O aplicativo de mapa nativo em cada plataforma pode ser iniciado a Launcher partir de um aplicativo .NET MAUI pela classe. Essa classe permite que um aplicativo abra outro aplicativo por meio de seu esquema de URI personalizado. A funcionalidade do iniciador pode ser invocada com o método, passando um string ou Uri argumento que representa o OpenAsync esquema de URL personalizado a ser aberto. Para obter mais informações sobre a Launcher classe, consulte Iniciador.

Observação

Uma alternativa para usar a classe é usar Map a LauncherMicrosoft.Maui.ApplicationModel classe do namespace. Para obter mais informações, consulte Mapa.

O aplicativo de mapas em cada plataforma usa um esquema de URI personalizado exclusivo. Para obter informações sobre o esquema de URI de mapas no iOS, consulte Links de mapa no developer.apple.com. Para obter informações sobre o esquema de URI do Google Maps no Android, consulte Guia do desenvolvedor do Google Maps e Intenções do Google Maps para Android no developers.android.com. Para obter informações sobre o esquema de URI de mapas no Windows, consulte Iniciar o aplicativo Windows Maps.

Inicie o aplicativo de mapa em um local específico

Um local no aplicativo de mapas nativo pode ser aberto adicionando parâmetros de consulta apropriados ao esquema de URI personalizado para cada aplicativo de mapa:

if (DeviceInfo.Current.Platform == DevicePlatform.iOS || DeviceInfo.Current.Platform == DevicePlatform.MacCatalyst)
{
    // https://developer.apple.com/library/ios/featuredarticles/iPhoneURLScheme_Reference/MapLinks/MapLinks.html
    await Launcher.OpenAsync("http://maps.apple.com/?q=394+Pacific+Ave+San+Francisco+CA");
}
else if (DeviceInfo.Current.Platform == DevicePlatform.Android)
{
    // opens the Maps app directly
    await Launcher.OpenAsync("geo:0,0?q=394+Pacific+Ave+San+Francisco+CA");
}
else if (DeviceInfo.Current.Platform == DevicePlatform.WinUI)
{
    await Launcher.OpenAsync("bingmaps:?where=394 Pacific Ave San Francisco CA");
}

Este código de exemplo resulta no aplicativo de mapa nativo sendo iniciado em cada plataforma, com o mapa centralizado em um alfinete representando o local especificado.

Inicie o aplicativo de mapa com direções

O aplicativo de mapas nativo pode ser iniciado exibindo direções, adicionando parâmetros de consulta apropriados ao esquema de URI personalizado para cada aplicativo de mapa:

if (DeviceInfo.Current.Platform == DevicePlatform.iOS || DeviceInfo.Current.Platform == DevicePlatform.MacCatalyst)
{
    // https://developer.apple.com/library/ios/featuredarticles/iPhoneURLScheme_Reference/MapLinks/MapLinks.html
    await Launcher.OpenAsync("http://maps.apple.com/?daddr=San+Francisco,+CA&saddr=cupertino");
}
else if (DeviceInfo.Current.Platform == DevicePlatform.Android)
{
    // opens the 'task chooser' so the user can pick Maps, Chrome or other mapping app
    await Launcher.OpenAsync("http://maps.google.com/?daddr=San+Francisco,+CA&saddr=Mountain+View");
}
else if (DeviceInfo.Current.Platform == DevicePlatform.WinUI)
{
    await Launcher.OpenAsync("bingmaps:?rtp=adr.394 Pacific Ave San Francisco CA~adr.One Microsoft Way Redmond WA 98052");
}

Este código de exemplo resulta no aplicativo de mapa nativo sendo iniciado em cada plataforma, com o mapa centralizado em uma rota entre os locais especificados.