Xamarin.Forms Controllo mappa

  • Articolo

Il Map controllo è una visualizzazione multipiattaforma per la visualizzazione e l'annotazione delle mappe. Usa il controllo mappa nativo per ogni piattaforma, offrendo un'esperienza di mappe veloce e familiare per gli utenti:

Screenshot del controllo mappa in iOS e Android

La Map classe definisce le proprietà seguenti che controllano l'aspetto e il comportamento della mappa:

  • IsShowingUser, di tipo bool, indica se la mappa mostra la posizione corrente dell'utente.
  • ItemsSource, di tipo IEnumerable, che specifica la raccolta di IEnumerable elementi da visualizzare.
  • ItemTemplate, di tipo DataTemplate, che specifica l'oggetto DataTemplate da applicare a ogni elemento nella raccolta di elementi visualizzati.
  • ItemTemplateSelector, di tipo DataTemplateSelector, che specifica l'oggetto DataTemplateSelector che verrà usato per scegliere un DataTemplate elemento in fase di esecuzione.
  • HasScrollEnabled, di tipo bool, determina se la mappa è autorizzata a scorrere.
  • HasZoomEnabled, di tipo bool, determina se la mappa può eseguire lo zoom.
  • MapElements, di tipo IList<MapElement>, rappresenta l'elenco di elementi sulla mappa, ad esempio poligoni e polilinee.
  • MapType, di tipo MapType, indica lo stile di visualizzazione della mappa.
  • MoveToLastRegionOnLayoutChange, di tipo bool, controlla se l'area della mappa visualizzata verrà spostata dall'area corrente all'area impostata in precedenza quando si verifica una modifica del layout.
  • Pins, di tipo IList<Pin>, rappresenta l'elenco di puntini sulla mappa.
  • TrafficEnabled, di tipo bool, indica se i dati sul traffico sono sovrapposti sulla mappa.
  • VisibleRegion, di tipo MapSpan, restituisce l'area attualmente visualizzata della mappa.

Queste proprietà, ad eccezione delle MapElementsproprietà , Pinse VisibleRegion , sono supportate da BindableProperty oggetti , il che significa che possono essere destinazioni di data binding.

La Map classe definisce anche un MapClicked evento generato quando viene toccata la mappa. L'oggetto MapClickedEventArgs che accompagna l'evento ha una singola proprietà denominata Position, di tipo Position. Quando viene generato l'evento, la Position proprietà viene impostata sulla posizione della mappa toccata. Per informazioni sullo struct, vedere Posizione e distanza della Position mappa.

Per informazioni sulle ItemsSourceproprietà , ItemTemplatee ItemTemplateSelector , vedere Visualizzare una raccolta di pin.

Visualizzare una mappa

Un Map oggetto può essere visualizzato aggiungendolo a un layout o a una pagina:

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

Nota

Per fare riferimento Xamarin.Formsai controlli .Mappe, è necessaria una definizione di spazio dei nomi aggiuntivaxmlns. Nell'esempio precedente viene fatto riferimento allo Xamarin.Forms.Maps spazio dei nomi tramite la maps parola chiave .

Il codice C# equivalente è il seguente:

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

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

Questo esempio chiama il costruttore predefinito Map , che centra la mappa su Roma:

Screenshot del controllo mappa con la posizione predefinita, in iOS e Android

In alternativa, un MapSpan argomento può essere passato a un Map costruttore per impostare il punto centrale e il livello di zoom della mappa quando viene caricato. Per altre informazioni, vedere Visualizzare una posizione specifica su una mappa.

Tipi di mappa

La Map.MapType proprietà può essere impostata su un MapType membro di enumerazione per definire lo stile di visualizzazione della mappa. L'enumerazione MapType definisce i membri seguenti:

  • Street specifica che verrà visualizzata una mappa stradale.
  • Satellite specifica che verrà visualizzata una mappa contenente immagini satellitari.
  • Hybrid specifica che verrà visualizzata una mappa che combina dati stradali e satellitari.

Per impostazione predefinita, un oggetto Map visualizzerà una mappa stradale se la MapType proprietà non è definita. In alternativa, la MapType proprietà può essere impostata su uno dei membri dell'enumerazione MapType :

<maps:Map MapType="Satellite" />

Il codice C# equivalente è il seguente:

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

Gli screenshot seguenti mostrano un Map oggetto quando la MapType proprietà è impostata su Street:

Screenshot del controllo mappa con il tipo di mappa stradale, in iOS e Android

Gli screenshot seguenti mostrano un Map oggetto quando la MapType proprietà è impostata su Satellite:

Screenshot del controllo mappa con il tipo di mappa satellite, in iOS e Android

Gli screenshot seguenti mostrano un Map oggetto quando la MapType proprietà è impostata su Hybrid:

Screenshot del controllo mappa con il tipo di mappa ibrida, in iOS e Android

Visualizzare una posizione specifica su una mappa

L'area di una mappa da visualizzare quando viene caricata una mappa può essere impostata passando un MapSpan argomento al Map costruttore:

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

Il codice C# equivalente è il seguente:

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

In questo esempio viene creato un Map oggetto che mostra l'area specificata dall'oggetto MapSpan . L'oggetto MapSpan è centrato sulla latitudine e la longitudine rappresentata da un Position oggetto e si estende su 0,01 latitudine e 0,01 gradi di longitudine. Per informazioni sullo struct, vedere Posizione e distanza della Position mappa. Per informazioni sul passaggio di argomenti in XAML, vedere Passaggio di argomenti in XAML.

Il risultato è che quando la mappa viene visualizzata, si trova al centro su una posizione specifica e si estende su un numero specifico di gradi di latitudine e longitudine:

Screenshot del controllo mappa con la posizione specificata, in iOS e Android

Creare un oggetto MapSpan

Esistono diversi approcci per la creazione MapSpan di oggetti. Un approccio comune è fornire gli argomenti necessari al MapSpan costruttore. Si tratta di una latitudine e una longitudine rappresentate da un Position oggetto e double valori che rappresentano i gradi di latitudine e longitudine che sono compresi in MapSpan. Per informazioni sullo struct, vedere Posizione e distanza della Position mappa.

In alternativa, nella MapSpan classe sono disponibili tre metodi che restituiscono nuovi MapSpan oggetti:

  1. ClampLatitude restituisce un MapSpan oggetto con lo stesso LongitudeDegrees dell'istanza della classe del metodo e un raggio definito dagli north argomenti e south .
  2. FromCenterAndRadius restituisce un oggetto MapSpan definito dai relativi Position argomenti e Distance .
  3. WithZoom restituisce un MapSpan oggetto con lo stesso centro dell'istanza della classe del metodo, ma con un raggio moltiplicato per il relativo double argomento.

Per informazioni sullo struct, vedere Posizione e distanza della Distance mappa.

Dopo aver creato un oggetto MapSpan , è possibile accedere alle proprietà seguenti per recuperare i dati su di esso:

  • Center, che rappresenta l'oggetto Position nel centro geografico dell'oggetto MapSpan.
  • LatitudeDegrees, che rappresenta i gradi di latitudine estesa dall'oggetto MapSpan.
  • LongitudeDegrees, che rappresenta i gradi di longitudine estesa da MapSpan.
  • Radius, che rappresenta il MapSpan raggio.

Spostare la mappa

Il Map.MoveToRegion metodo può essere chiamato per modificare la posizione e il livello di zoom di una mappa. Questo metodo accetta un MapSpan argomento che definisce l'area della mappa da visualizzare e il relativo livello di zoom.

Il codice seguente mostra un esempio di spostamento dell'area visualizzata su una mappa:

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

Zoom della mappa

Il livello di zoom di un Map oggetto può essere modificato senza modificarne la posizione. A tale scopo, è possibile usare l'interfaccia utente della mappa o a livello di codice chiamando il MoveToRegion metodo con un MapSpan argomento che usa la posizione corrente come Position argomento:

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

In questo esempio, il MoveToRegion metodo viene chiamato con un MapSpan argomento che specifica la posizione corrente della mappa, tramite la Map.VisibleRegion proprietà e il livello di zoom come gradi di latitudine e longitudine. Il risultato complessivo è che il livello di zoom della mappa viene modificato, ma la sua posizione non è. Un approccio alternativo per l'implementazione dello zoom su una mappa consiste nell'usare il MapSpan.WithZoom metodo per controllare il fattore di zoom.

Importante

Lo zoom di una mappa, indipendentemente dall'interfaccia utente della mappa o a livello di programmazione, richiede che la Map.HasZoomEnabled proprietà sia true. Per altre informazioni su questa proprietà, vedere Disabilitare lo zoom.

Personalizzare il comportamento della mappa

Il comportamento di un Map oggetto può essere personalizzato impostando alcune delle relative proprietà e gestendo l'evento MapClicked .

Nota

È possibile ottenere una personalizzazione aggiuntiva del comportamento della mappa creando un renderer personalizzato della mappa. Per altre informazioni, vedere Personalizzazione di una Xamarin.Forms mappa.

Visualizzare i dati sul traffico

La Map classe definisce una TrafficEnabled proprietà di tipo bool. Per impostazione predefinita, questa proprietà è false, che indica che i dati del traffico non verranno sovrapposti sulla mappa. Quando questa proprietà è impostata su true, i dati sul traffico sono sovrapposti sulla mappa. Nell'esempio seguente viene illustrata l'impostazione di questa proprietà:

<maps:Map TrafficEnabled="true" />

Il codice C# equivalente è il seguente:

Map map = new Map
{
    TrafficEnabled = true
};

Disabilita scorrimento

La Map classe definisce una HasScrollEnabled proprietà di tipo bool. Per impostazione predefinita, questa proprietà è true, che indica che la mappa è autorizzata a scorrere. Quando questa proprietà è impostata su false, la mappa non scorrerà. Nell'esempio seguente viene illustrata l'impostazione di questa proprietà:

<maps:Map HasScrollEnabled="false" />

Il codice C# equivalente è il seguente:

Map map = new Map
{
    HasScrollEnabled = false
};

Disabilita zoom

La Map classe definisce una HasZoomEnabled proprietà di tipo bool. Per impostazione predefinita, questa proprietà è true, che indica che lo zoom può essere eseguito sulla mappa. Quando questa proprietà è impostata su false, non è possibile ingrandire la mappa. Nell'esempio seguente viene illustrata l'impostazione di questa proprietà:

<maps:Map HasZoomEnabled="false" />

Il codice C# equivalente è il seguente:

Map map = new Map
{
    HasZoomEnabled = false
};

Mostra la posizione dell'utente

La Map classe definisce una IsShowingUser proprietà di tipo bool. Per impostazione predefinita, questa proprietà è false, che indica che la mappa non mostra la posizione corrente dell'utente. Quando questa proprietà è impostata su true, la mappa mostra la posizione corrente dell'utente. Nell'esempio seguente viene illustrata l'impostazione di questa proprietà:

<maps:Map IsShowingUser="true" />

Il codice C# equivalente è il seguente:

Map map = new Map
{
    IsShowingUser = true
};

Importante

In iOS, Android e il piattaforma UWP (Universal Windows Platform), per accedere alla posizione dell'utente sono necessarie autorizzazioni per la posizione per l'applicazione. Per altre informazioni, vedere Configurazione della piattaforma.

Gestire l'area della mappa in caso di modifica del layout

La Map classe definisce una MoveToLastRegionOnLayoutChange proprietà di tipo bool. Per impostazione predefinita, questa proprietà è true, che indica che l'area della mappa visualizzata passerà dall'area corrente all'area impostata in precedenza quando si verifica una modifica del layout, ad esempio nella rotazione del dispositivo. Quando questa proprietà è impostata su false, l'area della mappa visualizzata rimarrà allineata al centro quando si verifica una modifica del layout. Nell'esempio seguente viene illustrata l'impostazione di questa proprietà:

<maps:Map MoveToLastRegionOnLayoutChange="false" />

Il codice C# equivalente è il seguente:

Map map = new Map
{
    MoveToLastRegionOnLayoutChange = false
};

Clic mappa

La Map classe definisce un MapClicked evento generato quando viene toccata la mappa. L'oggetto MapClickedEventArgs che accompagna l'evento ha una singola proprietà denominata Position, di tipo Position. Quando viene generato l'evento, la Position proprietà viene impostata sulla posizione della mappa toccata. Per informazioni sullo struct, vedere Posizione e distanza della Position mappa.

L'esempio di codice seguente mostra un gestore eventi per l'evento MapClicked :

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

In questo esempio, il OnMapClicked gestore eventi restituisce la latitudine e la longitudine che rappresenta la posizione della mappa toccata. Il gestore eventi può essere registrato con l'evento MapClicked come indicato di seguito:

<maps:Map MapClicked="OnMapClicked" />

Il codice C# equivalente è il seguente:

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