Xamarin.Forms Contrôle de carte

Le contrôle Map est une vue multiplateforme permettant d’afficher et d’annoter des cartes. Il utilise le contrôle de carte natif pour chaque plateforme, offrant une expérience de cartes rapide et familière pour les utilisateurs :

La classe Map définit les propriétés suivantes qui contrôlent l’apparence et le comportement de la carte :

• IsShowingUser, de type bool, indique si la carte affiche la localisation actuelle de l’utilisateur.
• ItemsSource, de type IEnumerable, qui spécifie la collection d’éléments IEnumerable à afficher.
• ItemTemplate, de type DataTemplate, qui spécifie l’application DataTemplate à chaque élément de la collection d’éléments affichés.
• ItemTemplateSelector, de type DataTemplateSelector, qui spécifie celui DataTemplateSelector qui sera utilisé pour choisir un DataTemplate élément au moment de l’exécution.
• HasScrollEnabled, de type bool, détermine si le défilement de la carte est autorisé.
• HasZoomEnabled, de type bool, détermine si le zoom sur la carte est autorisé.
• MapElements, de type IList<MapElement>, représente la liste des éléments sur la carte, tels que les polygones et les polylignes.
• MapType, de type MapType, indique le style d’affichage de la carte.
• MoveToLastRegionOnLayoutChange, de type bool, contrôle si la région de carte affichée passe de sa région actuelle à sa région définie précédemment lorsqu’une modification de disposition se produit.
• Pins, de type IList<Pin>, représente la liste des repères sur la carte.
• TrafficEnabled, de type bool, indique si les données de trafic sont superposées sur la carte.
• VisibleRegion, de type MapSpan, retourne la région de la carte actuellement affichée.

Ces propriétés, à l’exception des propriétés MapElements, Pins et VisibleRegion, s’appuient sur des objets BindableProperty, ce qui signifie qu’elles peuvent être des cibles de liaisons de données.

La classe Map définit également un événement MapClicked déclenché lorsqu’un appui sur la carte est effectué. L’objet MapClickedEventArgs qui accompagne l’événement a une propriété unique nommée Position, de type Position. Lorsque l’événement est déclenché, la propriété Position est définie sur la localisation de la carte sur laquelle l’utilisateur a appuyé. Pour plus d’informations sur le struct, consultez Position et distance de la Position carte.

Pour plus d’informations sur les propriétés ItemsSource, ItemTemplate et ItemTemplateSelector, consultez Afficher une collection de repères.

Afficher une carte

Vous pouvez afficher un Map en l’ajoutant à une disposition ou à une page :

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

Remarque

Une définition d’espace de noms supplémentaire xmlns est requise pour référencer le Xamarin.Forms. Mappe les contrôles. Dans l’exemple précédent, l’espace Xamarin.Forms.Maps de noms est référencé via le maps mot clé.

Le code C# équivalent est :

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

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

Cet exemple appelle le constructeur par défaut Map , qui centre la carte sur Rome :

Vous pouvez également passer un argument MapSpan à un constructeur Map pour définir le point central et le niveau de zoom de la carte lorsqu’elle est chargée. Pour plus d’informations, consultez Afficher une localisation spécifique sur une carte.

Types de cartes

La propriété Map.MapType peut être définie sur un membre d’énumération MapType afin de définir le style d’affichage de la carte. L’énumération MapType définit les membres suivants :

• Street spécifie qu’un plan de rues sera affiché.
• Satellite spécifie qu’une carte représentant des images satellite sera affichée.
• Hybrid spécifie qu’une carte combinant les données de rues et d’images satellite sera affichée.

Par défaut, un Map affiche un plan de rues si la propriété MapType n’est pas définie. Vous pouvez également définir la propriété MapType sur l’un des membres d’énumération MapType :

<maps:Map MapType="Satellite" />

Le code C# équivalent est :

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

Les captures d’écran suivantes montrent une Map fois la MapType propriété définie sur Street:

Les captures d’écran suivantes montrent une Map fois la MapType propriété définie sur Satellite:

Les captures d’écran suivantes montrent une Map fois la MapType propriété définie sur Hybrid:

Afficher une localisation spécifique sur une carte

Vous pouvez définir la région d’une carte à afficher lorsqu’une carte est chargée en transmettant un argument MapSpan au constructeur Map :

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

Le code C# équivalent est :

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

Cet exemple crée un objet Map qui affiche la région spécifiée par l’objet MapSpan. L’objet MapSpan est centré sur la latitude et la longitude représentées par un objet Position, et couvre 0,01 degré de latitude et 0,01 degré de longitude. Pour plus d’informations sur le struct, consultez Position et distance de la Position carte. Pour plus d’informations sur le passage d’arguments en XAML, consultez Passage d’arguments en XAML.

Le résultat est que lorsque la carte est affichée, elle est centrée sur une localisation spécifique et couvre un nombre spécifique de degrés de latitude et de longitude :

Créer un objet MapSpan

La création d’objets MapSpan peut être abordée sous différentes approches. Une approche courante consiste à fournir les arguments requis au constructeur MapSpan. Il s’agit d’une latitude et d’une longitude représentées par un objet Position, et de valeurs double qui représentent les degrés de latitude et de longitude couverts par le MapSpan. Pour plus d’informations sur le struct, consultez Position et distance de la Position carte.

En guise d’alternative, il existe trois méthodes dans la classe MapSpan qui retournent de nouveaux objets MapSpan :

1. ClampLatitude retourne un MapSpan ayant le même LongitudeDegrees que l’instance de classe de la méthode, et un rayon défini par ses arguments north et south.
2. FromCenterAndRadius retourne un MapSpan défini par ses arguments Position et Distance.
3. WithZoom retourne un MapSpan avec le même centre que l’instance de classe de la méthode, mais avec un rayon multiplié par son argument double.

Pour plus d’informations sur le struct, consultez Position et distance de la Distance carte.

Une fois qu’un MapSpan a été créé, vous pouvez accéder aux propriétés suivantes pour récupérer des données le concernant :

• Center, qui représente le Position centre géographique du MapSpan.
• LatitudeDegrees, qui représente les degrés de latitude qui sont répartis par le MapSpan.
• LongitudeDegrees, qui représente les degrés de longitude qui sont répartis par le MapSpan.
• Radius, qui représente le MapSpan rayon.

Déplacer la carte

Vous pouvez appeler la méthode Map.MoveToRegion pour modifier la position et le niveau de zoom d’une carte. Cette méthode accepte un argument MapSpan qui définit la région de la carte à afficher et son niveau de zoom.

Le code suivant montre un exemple de déplacement de la région affichée sur une carte :

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

Faire un zoom sur la carte

Le niveau de zoom d’un Map peut être modifié sans changer sa localisation. Ceci peut être accompli par le biais de l’interface utilisateur de la carte ou par programmation en appelant la méthode MoveToRegion avec un argument MapSpan qui utilise la localisation actuelle comme argument Position :

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

Dans cet exemple, la méthode MoveToRegion est appelée avec un argument MapSpan qui spécifie la localisation actuelle de la carte, via la propriété Map.VisibleRegion, et le niveau de zoom sous forme de degrés de latitude et de longitude. Le résultat global est que le niveau de zoom de la carte est modifié, mais pas sa localisation. Une autre approche pour implémenter le zoom sur une carte consiste à utiliser la méthode MapSpan.WithZoom afin de contrôler le facteur de zoom.

Important

Un zoom avant sur une carte, que ce soit via l’interface utilisateur de la carte ou par programmation, nécessite que la propriété Map.HasZoomEnabled soit true. Pour plus d’informations sur cette propriété, consultez Désactiver le zoom.

Personnaliser le comportement de la carte

Vous pouvez personnaliser le comportement d’un Map en définissant certaines de ses propriétés et en gérant l’événement MapClicked.

Remarque

Vous pouvez obtenir une personnalisation supplémentaire du comportement de carte en créant un renderer personnalisé de carte. Pour plus d’informations, consultez Personnalisation d’une Xamarin.Forms carte.

Afficher les données du trafic

La classe Map définit une propriété TrafficEnabled de type bool. Par défaut, cette propriété est false, ce qui indique que les données de trafic ne seront pas superposées sur la carte. Lorsque cette propriété est définie truesur , les données de trafic sont superposées sur la carte. L’exemple suivant montre comment définir cette propriété :

<maps:Map TrafficEnabled="true" />

Le code C# équivalent est :

Map map = new Map
{
    TrafficEnabled = true
};

Désactiver le défilement

La classe Map définit une propriété HasScrollEnabled de type bool. Par défaut, cette propriété est true, ce qui indique que le défilement de la carte est autorisé. Lorsque cette propriété est définie falsesur , la carte ne défile pas. L’exemple suivant montre comment définir cette propriété :

<maps:Map HasScrollEnabled="false" />

Le code C# équivalent est :

Map map = new Map
{
    HasScrollEnabled = false
};

Désactiver le zoom

La classe Map définit une propriété HasZoomEnabled de type bool. Par défaut, cette propriété est true, ce qui indique qu’il est possible de zoomer sur la carte. Lorsque cette propriété est définie falsesur , la carte ne peut pas être zoomée. L’exemple suivant montre comment définir cette propriété :

<maps:Map HasZoomEnabled="false" />

Le code C# équivalent est :

Map map = new Map
{
    HasZoomEnabled = false
};

Afficher la localisation de l’utilisateur

La classe Map définit une propriété IsShowingUser de type bool. Par défaut, cette propriété est false, ce qui indique que la carte n’affiche pas la localisation actuelle de l’utilisateur. Lorsque cette propriété est définie truesur , la carte affiche l’emplacement actuel de l’utilisateur. L’exemple suivant montre comment définir cette propriété :

<maps:Map IsShowingUser="true" />

Le code C# équivalent est :

Map map = new Map
{
    IsShowingUser = true
};

Important

Sur iOS, Android et le plateforme Windows universelle, l’accès à l’emplacement de l’utilisateur nécessite des autorisations d’emplacement pour avoir été accordées à l’application. Pour plus d’informations, consultez Configuration de la plateforme.

Gérer la région de carte lors de la modification de la disposition

La classe Map définit une propriété MoveToLastRegionOnLayoutChange de type bool. Par défaut, cette propriété indique trueque la région de carte affichée passe de sa région actuelle à sa région définie précédemment lorsqu’une modification de disposition se produit, par exemple lors de la rotation de l’appareil. Lorsque cette propriété est définie falsesur , la zone de carte affichée reste centrée lorsqu’une modification de disposition se produit. L’exemple suivant montre comment définir cette propriété :

<maps:Map MoveToLastRegionOnLayoutChange="false" />

Le code C# équivalent est :

Map map = new Map
{
    MoveToLastRegionOnLayoutChange = false
};

Clics sur la carte

La classe Map définit un événement MapClicked déclenché lorsqu’un appui sur la carte est effectué. L’objet MapClickedEventArgs qui accompagne l’événement a une propriété unique nommée Position, de type Position. Lorsque l’événement est déclenché, la propriété Position est définie sur la localisation de la carte sur laquelle l’utilisateur a appuyé. Pour plus d’informations sur le struct, consultez Position et distance de la Position carte.

L’exemple de code suivant montre un gestionnaire d’événements pour l’événement MapClicked :

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

Dans cet exemple, le gestionnaire d’événements OnMapClicked génère la latitude et la longitude qui représente la localisation sur laquelle l’appui a été effectué. Le gestionnaire d’événements peut être inscrit auprès de l’événement MapClicked comme suit :

<maps:Map MapClicked="OnMapClicked" />

Le code C# équivalent est :

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

Liens connexes

• Position et distance de la carte
• Personnalisation d’une Xamarin.Forms carte
• Passage d’arguments en XAML