Mapa

Navegar na amostra

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

Configuração

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

Inicialização do mapa

O controle Map é 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, você deve inicializá-lo em seu aplicativo chamando o método UseMauiMaps no objeto MauiAppBuilder dentro do método CreateMauiApp da classe MauiProgram.

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 tiver sido adicionado e inicializado, Map as APIs poderão ser usadas em seu projeto.

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

Configuração da plataforma

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

Catalisador para iOS e Mac

Exibir e interagir com um mapa no iOS e no Mac Catalyst não requer 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 no Info.plist. Normalmente, eles serão um ou mais dos seguintes:

• NSLocationAlwaysAndWhenInUseUsageDescription – para usar serviços de localização o tempo todo.
• NSLocationWhenInUseUsageDescription – para usar serviços de localização quando o aplicativo estiver em uso.

Para obter mais informações, consulte Escolher a autorização de serviços de localização para solicitar no developer.apple.com.

A representação XML dessas 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 seu 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 de API do Google Mapas e adicione-a ao manifesto do aplicativo.
2. Especifique o número de versão do Google Play Services no manifesto.
3. [opcional] Especifique as permissões de localização no manifesto.
4. [opcional] Especifique a permissão WRITE_EXTERNAL_STORAGE no manifesto.

Obter uma chave de API do Google Mapas

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

Depois de obter uma chave de API, ela deverá ser adicionada no <application> elemento do arquivo Platforms/Android/AndroidManifest.xml especificando-a com.google.android.geo.API_KEY como o valor dos 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 insira a chave de API no manifesto. Sem uma chave de API válida, o Map controle exibirá uma grade em branco.

Especificar o número de 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 insere a versão dos serviços do Google Play com os quais o aplicativo foi compilado, no manifesto do aplicativo.

Especificar permissões de localização

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

<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 GPS (Global Positioning System), WiFi ou dados móveis para determinar um local preciso o mais possível.

Um prompt é exibido quando seu 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.

Especificar a permissão de WRITE_EXTERNAL_STORAGE

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

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

Isso não será necessário se o seu aplicativo for direcionado à API 23 ou superior.

Controle de mapa

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 de pino IEnumerable a serem exibidos.
• ItemTemplate, do tipo DataTemplate, que especifica o critério DataTemplate para cada item da coleção de pinos exibidos.
• ItemTemplateSelector, do tipo DataTemplateSelector, que especifica o DataTemplateSelector que será usado para escolher o DataTemplate do pino 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 sã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 polilinha.
• 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 exibida no momento do mapa.

Essas propriedades, com exceção de MapElements, Pins e VisibleRegion, são apoiadas por objetos BindableProperty, o que significa que podem ser destinos de vinculações de dados.

A Map classe também 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.

Para obter informações sobre as propriedades ItemsSource, ItemTemplate e ItemTemplateSelector, consulte 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>

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 MapSpan argumento pode ser passado para um Map 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.

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 rua será exibido.
• Satellite especifica que um mapa que contém imagens de satélite será exibido.
• Hybrid especifica que um mapa combinando dados de rua e satélite será exibido.

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

<maps:Map MapType="Satellite" />

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>

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 é centralizado 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 Os argumentos Pass no 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:

<maps:Map Region="36.9628066,-122.0194722,0.01,0.01" />

<maps:Pin Location="36.9628066,-122.0194722" Label="Santa Cruz" />

Criar um objeto MapSpan

Há várias abordagens para criar MapSpan objetos. Uma abordagem comum é fornecer os argumentos necessários ao MapSpan construtor. Estas são as coordenadas de latitude e longitude representadas por um objeto Location e valores numéricos double que representam os graus de latitude e longitude abrangidos 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. ClampLatitude retorna um MapSpan com o mesmo LongitudeDegrees da instância de classe do método e um raio definido por seus north e south argumentos.
2. FromCenterAndRadius retorna um MapSpan que é definido por seus Location e Distance argumentos.
3. WithZoom retorna um MapSpan com o mesmo centro da instância de classe do método, mas com um raio multiplicado por seu double argumento.

var locations = new[]
{
    new Location(36.9628066, -122.0194722),
    new Location(37.7749295, -122.4194155),
    new Location(36.1699412, -115.1398296)
};
MapSpan span = MapSpan.FromLocations(locations);
map.MoveToRegion(span);

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

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

• Center, do tipo Location, que representa a localização do centro geográfico do MapSpan.
• LatitudeDegrees, do tipo double, que representa os graus de latitude abrangidos pelo MapSpan.
• LongitudeDegrees, do tipo double, que representa os graus de longitude que são abrangidos pelo MapSpan.
• Radius, do tipo Distance, que representa o raio de 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);

// Move to region without animation (instant transition)
map.MoveToRegion(mapSpan, animated: false);

// Move to region with animation (smooth transition, default behavior)
map.MoveToRegion(mapSpan, animated: true);

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 de mapa, ou chamando programaticamente o método MoveToRegion com um argumento MapSpan que usa o local atual como argumento Location.

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 MoveToRegion método é chamado com um MapSpan argumento que especifica o local atual do mapa, por meio da Map.VisibleRegion propriedade, e o 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 MapSpan.WithZoom método para controlar o fator de zoom.

Personalizar o comportamento do mapa

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

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" />

O código C# equivalente é:

Map map = new Map
{
    IsTrafficEnabled = true
};

Desabilitar 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 estiver definida como false, o mapa não rolará:

<maps:Map IsScrollEnabled="false" />

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" />

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, o 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" />

O código C# equivalente é:

Map map = new Map
{
    IsShowingUser = true
};

Map map = new Map
{
    IsShowingUser = true
};

map.UserLocationChanged += (sender, args) =>
{
    System.Diagnostics.Debug.WriteLine(
        $"User location: {args.Location.Latitude}, {args.Location.Longitude}");
};

// Access the last known user location at any time
Location? lastLocation = map.LastUserLocation;

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 OnMapClicked manipulador de eventos gera a latitude e a longitude que representam o local do mapa tocado. O manipulador de eventos deve ser registrado com o MapClicked evento:

<maps:Map MapClicked="OnMapClicked" />

O código C# equivalente é:

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

map.MapLongClicked += (sender, args) =>
{
    // Add a pin at the long-pressed location
    map.Pins.Add(new Pin
    {
        Label = "Dropped Pin",
        Location = args.Location
    });
};

map.MapElementClick += (sender, args) =>
{
    MapElement clickedElement = args.MapElement;
    System.Diagnostics.Debug.WriteLine($"Tapped a {clickedElement.GetType().Name}");
};

Localização e distância

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

Localização

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 de graus relativo ao norte verdadeiro.
• IsFromMockProvider, do tipo bool, que indica se o local é 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 timestamp quando o Location foi criado.
• VerticalAccuracy, do tipo double?, que especifica a precisão vertical do Location, em metros.

Location os objetos são criados com uma das sobrecargas do Location construtor, que normalmente exigem argumentos mínimos 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.

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

Distância

O Distance struct encapsula uma distância armazenada como um double valor, que representa a distância em metros. Esta estrutura define três propriedades de leitura única.

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

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

Distance distance = new Distance(1450.5);

Como alternativa, Distance, os objetos podem ser criados com os métodos de fábrica FromKilometers, FromMeters, FromMiles e BetweenPositions.

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);

Pinos

O Map controle permite que os locais sejam marcados com Pin objetos. Um 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 da posição 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 pin.
• Location, do tipo Location, que representa a latitude e a longitude do pino.
• Type, do tipo PinType, que representa o tipo de pino.

Essas propriedades são apoiadas por BindableProperty objetos, o que significa que um Pin pode ser o destino das associações de dados. Para obter mais informações sobre objetos de associaçã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 é acionado quando um pino é tocado e o InfoWindowClicked evento é acionado 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 pino

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 objeto MapSpan está centrado na latitude e longitude representadas por um objeto Location, que se estende por 0,01 graus de latitude e longitude. Um Pin objeto é adicionado à Map.Pins coleção e desenhado no Map na localização especificada por sua propriedade Location. 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 têm construtores padrão, consulte argumentos Pass no XAML.

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 pino

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 MarkerClicked evento, que é acionado quando um Pin é tocado. Não é necessário lidar com esse evento para exibir a janela de informações. Em vez disso, esse evento deve ser tratado quando há uma necessidade de receber uma notificação de que um pin específico foi tocado.

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

O código a seguir mostra um exemplo de tratamento 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");
};

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 DisplayAlertAsync("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 DisplayAlertAsync("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 for definida como true dentro de um manipulador de eventos, a janela de informações ficará oculta.

// Show the info window for a specific pin
pin.ShowInfoWindow();

// Hide the info window
pin.HideInfoWindow();

Tipos de pin

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

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

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

Pin pin = new Pin
{
    Location = new Location(36.9628066, -122.0194722),
    Label = "Santa Cruz",
    ImageSource = ImageSource.FromFile("custom_pin.png")
};

<maps:Pin Location="36.9628066,-122.0194722"
          Label="Santa Cruz"
          ImageSource="custom_pin.png" />

<maps:Map IsClusteringEnabled="true" />

Map map = new Map
{
    IsClusteringEnabled = true
};

map.ClusterClicked += (sender, args) =>
{
    System.Diagnostics.Debug.WriteLine($"Cluster with {args.Pins.Count} pins tapped");

    // Set Handled to true to prevent the default zoom-to-cluster behavior
    args.Handled = true;
};

Exibir uma coleção de pinos

A Map classe define as seguintes propriedades associáveis:

• ItemsSource, do tipo IEnumerable, que especifica a coleção de itens de pino IEnumerable a serem exibidos.
• ItemTemplate, do tipo DataTemplate, que especifica o critério DataTemplate para cada item da coleção de pinos exibidos.
• ItemTemplateSelector, do tipo DataTemplateSelector, que especifica o DataTemplateSelector que será usado para escolher o DataTemplate do pino em tempo de execução.

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

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

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

A aparência de cada item na IEnumerable coleção é determinada ao definir a ItemTemplate propriedade para um DataTemplate que contém um objeto Pin que vincula os dados às propriedades apropriadas.

A captura de tela a seguir mostra um Map exibindo uma coleção Pin usando a associação de dados:

Escolher a aparência do item no runtime

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

<ContentPage ...
             xmlns:templates="clr-namespace:WorkingWithMaps.Templates"
             xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
             xmlns:viewmodels="clr-namespace:WorkingWithMaps.ViewModels"
             x:DataType="viewmodels:PinItemsSourcePageViewModel">
    <ContentPage.Resources>
       <templates:MapItemTemplateSelector x:Key="MapItemTemplateSelector">
           <templates:MapItemTemplateSelector.DefaultTemplate>
               <DataTemplate x:DataType="models:Position">
                   <maps:Pin Location="{Binding Location}"
                             Address="{Binding Address}"
                             Label="{Binding Description}" />
               </DataTemplate>
           </templates:MapItemTemplateSelector.DefaultTemplate>
           <templates:MapItemTemplateSelector.SanFranTemplate>
               <DataTemplate x:DataType="models:Position">
                   <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 classe MapItemTemplateSelector define as propriedades DefaultTemplate e SanFranTemplateDataTemplate como diferentes modelos de dados. O método OnSelectTemplate retorna o SanFranTemplate, que exibe "Xamarin" como um rótulo quando um Pin é tocado, quando o item tem um endereço que contém "São Francisco". Quando o item não tem um endereço que contém "São Francisco", o OnSelectTemplate método retorna o DefaultTemplate.

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

Polígonos, polilinha 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ço e uma cor de preenchimento. A Polyline é uma linha que não inclui totalmente uma área. Um Circle realça uma área circular do mapa:

As Polygonclasses , Polylinee Circle derivam da MapElement classe, que expõe as seguintes propriedades associáveis:

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

Polygon polygon = new Polygon
{
    StrokeColor = Colors.Blue,
    FillColor = Color.FromArgb("#8800FF00"),
    IsVisible = true,
    ZIndex = 1
};

// Toggle visibility
polygon.IsVisible = false;

// Bring to front
polygon.ZIndex = 10;

A Polygon classe define uma propriedade associável adicional:

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

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

A Circle classe define as seguintes propriedades associá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>

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);

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

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>

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 as StrokeWidth propriedades são especificadas para definir a aparência da linha. A GeoPath propriedade contém uma lista de Location objetos que definem as coordenadas geográficas dos pontos de polilinha. Um Polyline objeto é renderizado no mapa depois que ele é 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>

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);

O local do Circle no mapa é determinado pelo valor das propriedades Center 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 propriedades StrokeColor 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 fique visível por meio do círculo. O Circle objeto é renderizado no mapa assim que é adicionado à coleção MapElements do Map.

Map map = new Map
{
    MapStyle = """
    [
        {
            "featureType": "water",
            "elementType": "geometry.fill",
            "stylers": [{ "color": "#0077be" }]
        },
        {
            "featureType": "road",
            "elementType": "geometry",
            "stylers": [{ "color": "#ffffff" }]
        }
    ]
    """
};

Geocodificação e localização geográfica

A classe Geocoding, no namespace Microsoft.Maui.Devices.Sensors, pode ser usada para codificar geografiamente uma marca de lugar para coordenadas posicionais e coordenadas de código geográfico reverso para uma marca de lugar. Para obter mais informações, consulte Geocodificação.

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

Iniciar o aplicativo de mapa nativo

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

O aplicativo 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 de mapas no Android, consulte o Guia do Desenvolvedor do Mapas e as Intenções do Google Mapas para Android no developers.android.com. Para obter informações sobre o esquema de URI de mapas em Windows, consulte Aunchar o aplicativo Mapas do Windows.

Iniciar o aplicativo de mapa em um local específico

Um local no aplicativo de mapas nativos 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 na inicialização do aplicativo de mapa nativo em cada plataforma, com o mapa centralizado em um pino que representa o local especificado.

Iniciar o aplicativo de mapa com instruções

O aplicativo de mapas nativos pode ser iniciado exibindo instruçõ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 faz com que o aplicativo de mapa nativo seja iniciado em cada plataforma, com o mapa centralizado em uma rota entre os locais especificados.