Mapovat

Článek
08/30/2024

Ovládací prvek .NET Multi-Platform App UI (.NET MAUI) Map je zobrazení pro různé platformy pro zobrazení a přidávání poznámek k mapě. Ovládací Map prvek používá nativní ovládací prvek mapy na každé platformě a je poskytován balíčkem NuGet Microsoft.Maui.Controls.Maps.

Důležité

Ovládací Map prvek není ve Windows podporovaný kvůli nedostatku ovládacího prvku mapy ve WinUI. Balíček NuGet CommunityToolkit.Maui.Maps však poskytuje přístup k Mapám Bing prostřednictvím windowsWebView. Další informace najdete v tématu Začínáme.

Nastavení

Ovládací Map prvek používá nativní ovládací prvek mapy na každé platformě. To poskytuje uživatelům rychlé a známé prostředí map, ale znamená to, že některé kroky konfigurace jsou potřeba k dodržování požadavků rozhraní API jednotlivých platforem.

Inicializace mapy

Tento Map ovládací prvek poskytuje balíček NuGet Microsoft.Maui.Controls.Maps, který by se měl přidat do projektu aplikace .NET MAUI.

Po instalaci balíčku NuGet musí být inicializován v aplikaci voláním UseMauiMap metody na MauiAppBuilder objekt v CreateMauiApp metodě vaší MauiProgram třídy:

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

Po přidání a inicializaci Map balíčku NuGet je možné v projektu použít rozhraní API.

Konfigurace platformy

Před zobrazením mapy se v Androidu vyžaduje další konfigurace. Kromě toho v iOSu, Androidu a Mac Catalystu přístup k poloze uživatele vyžaduje, aby vaší aplikaci byla udělena oprávnění k poloze.

iOS a Mac Catalyst

Zobrazení a interakce s mapou v systémech iOS a Mac Catalyst nevyžaduje žádnou další konfiguraci. Pokud ale chcete získat přístup ke službám zjišťování polohy, měli byste nastavit požadované žádosti o služby zjišťování polohy v souboru Info.plist. Obvykle se jedná o jednu nebo více z následujících možností:

NSLocationAlwaysAndWhenInUseUsageDescription – pro používání služeb zjišťování polohy za všech okolností.
NSLocationWhenInUseUsageDescription – pro používání služeb zjišťování polohy, když je aplikace používána.

Další informace najdete v tématu Volba autorizace služby zjišťování polohy, která se má vyžádat na developer.apple.com.

Reprezentace XML pro tyto klíče v souboru Info.plist je zobrazena níže. Hodnoty byste měli aktualizovat string tak, aby odrážely způsob, jakým vaše aplikace používá informace o poloze:

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

Zobrazí se výzva, když se vaše aplikace pokusí o přístup k umístění uživatele a požádá o přístup:

Android

Proces konfigurace pro zobrazení a interakci s mapou v Androidu je následující:

Získejte klíč rozhraní API Služby Google Maps a přidejte ho do manifestu aplikace.
Zadejte číslo verze služeb Google Play v manifestu.
[volitelné] Zadejte oprávnění k umístění v manifestu.
[volitelné] Zadejte oprávnění WRITE_EXTERNAL_STORAGE v manifestu.

Získání klíče rozhraní API Služby Google Maps

Pokud chcete ovládací prvek používat na Androidu Map , musíte vygenerovat klíč rozhraní API, který bude využívat sada Google Maps SDK , na které Map ovládací prvek spoléhá na Android. Postupujte podle pokynů v části Nastavení v konzole Google Cloud Console a použijte klíče rozhraní API na developers.google.com.

Jakmile získáte klíč rozhraní API, musí se přidat do <application> elementu vašeho souboru Platforms/Android/AndroidManifest.xml tak, že ho com.google.android.geo.API_KEY zadáte jako hodnotu metadat:

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

Tím se do manifestu vloží klíč rozhraní API. Bez platného klíče rozhraní API ovládací Map prvek zobrazí prázdnou mřížku.

Poznámka:

com.google.android.geo.API_KEY je doporučený název metadat pro klíč rozhraní API. Klíč s tímto názvem se dá použít k ověření v několika rozhraních API založených na Google Maps na Androidu. Pro zpětnou kompatibilitu com.google.android.maps.v2.API_KEY je možné použít název metadat, ale umožňuje ověřování pouze v rozhraní API Služby Mapy Pro Android v2. Aplikace může zadat pouze jeden z názvů klíčových metadat rozhraní API.

Zadejte číslo verze služeb Google Play.

Do prvku AndroidManifest.xml přidejte následující deklaraci<application>:

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

Tím se do manifestu vloží verze služeb Google Play, se kterými byla aplikace zkompilována.

Zadání oprávnění k umístění

Pokud vaše aplikace potřebuje přístup k umístění uživatele, musíte požádat o oprávnění přidáním ACCESS_COARSE_LOCATION nebo ACCESS_FINE_LOCATION oprávnění (nebo obojího) do manifestu jako podřízeného <manifest> prvku:

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

Oprávnění ACCESS_COARSE_LOCATION umožňuje rozhraní API používat Wi-Fi nebo mobilní data nebo obojí k určení polohy zařízení. Oprávnění ACCESS_FINE_LOCATION umožňují rozhraní API používat globální polohovací systém (GPS), WiFi nebo mobilní data k určení přesného umístění.

Zobrazí se výzva, když se vaše aplikace pokusí o přístup k umístění uživatele a požádá o přístup:

Případně můžete tato oprávnění povolit v editoru manifestu androidu sady Visual Studio.

Zadání oprávnění WRITE_EXTERNAL_STORAGE

Pokud vaše aplikace cílí na rozhraní API 22 nebo nižší, bude nutné přidat WRITE_EXTERNAL_STORAGE oprávnění k manifestu <manifest> jako podřízený prvek:

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

To se nevyžaduje, pokud vaše aplikace cílí na rozhraní API 23 nebo vyšší.

Ovládací prvek Mapa

Třída Map definuje následující vlastnosti, které řídí vzhled a chování mapy:

IsShowingUser, typu booloznačuje, zda mapa zobrazuje aktuální umístění uživatele.
ItemsSource, typu IEnumerable, který určuje kolekci IEnumerable položek připnutí, které se mají zobrazit.
ItemTemplate, typu DataTemplate, který určuje DataTemplate , že se má použít pro každou položku v kolekci zobrazených špendlíků.
ItemTemplateSelector, typu DataTemplateSelector, který určuje DataTemplateSelector , že se použije k výběru DataTemplate špendlíku za běhu.
IsScrollEnabled, typu bool, určuje, zda je mapa povolena posouvání.
IsTrafficEnabled, typu booloznačuje, zda jsou na mapě překryvná data provozu.
IsZoomEnabled, typu bool, určuje, zda je mapa povolena lupa.
MapElements, typu IList<MapElement>, představuje seznam prvků na mapě, jako jsou mnohoúhelníky a lomené čáry.
MapType, typu MapTypeoznačuje styl zobrazení mapy.
Pins, typu IList<Pin>, představuje seznam špendlíků na mapě.
VisibleRegion, typu MapSpan, vrátí aktuálně zobrazenou oblast mapy.

Tyto vlastnosti, s výjimkou MapElements, Pinsa VisibleRegion vlastnosti, jsou podporovány BindableProperty objekty, což znamená, že mohou být cílem datových vazeb.

Třída Map také definuje MapClicked událost, která se aktivuje při klepnutí na mapu. Objekt MapClickedEventArgs , který doprovází událost má jednu vlastnost s názvem Location, typu Location. Při spuštění Location události se vlastnost nastaví na umístění mapy, na které jste klepli. Informace o Location třídě naleznete v tématu Umístění a vzdálenost.

Informace o objektu ItemsSource, ItemTemplatea ItemTemplateSelector vlastnosti naleznete v tématu Zobrazení kolekce připnutí.

Zobrazení mapy

Můžete Map ho zobrazit tak, že ho přidáte do rozložení nebo stránky:

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

Ekvivalentní kód jazyka C# je:

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

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

Tento příklad volá výchozí Map konstruktor, který zacentruje mapu na Maui, Havaj::

Snímek obrazovky ovládacího prvku mapy s výchozím umístěním

Případně můžete konstruktoru Map předat argument, MapSpan který nastaví středový bod a úroveň přiblížení mapy při načtení. Další informace naleznete v tématu Zobrazení konkrétního umístění na mapě.

Důležité

.NET MAUI má dva Map typy – Microsoft.Maui.Controls.Maps.Map a Microsoft.Maui.ApplicationModel.Map. Microsoft.Maui.ApplicationModel Protože obor názvů je jedním z direktiv .NET MAUIglobal using, při použití Microsoft.Maui.Controls.Maps.Map ovládacího prvku z kódu budete muset plně kvalifikovat využití Map nebo použít alias using.

Typy map

Vlastnost Map.MapType lze nastavit na člen výčtu MapType definující styl zobrazení mapy. Výčet MapType definuje následující členy:

Street určuje, že se zobrazí mapa ulic.
Satellite určuje, že se zobrazí mapa obsahující satelitní snímky.
Hybrid určuje, že se zobrazí mapování, které kombinuje street a satelitní data.

Ve výchozím nastavení Map se při nedefinované vlastnosti zobrazí mapa MapType ulic. Alternativně MapType lze vlastnost nastavit na jeden ze členů výčtu MapType :

<maps:Map MapType="Satellite" />

Ekvivalentní kód jazyka C# je:

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

Zobrazení konkrétního umístění na mapě

Oblast mapy, která se má zobrazit při načtení mapy, lze nastavit předáním MapSpan argumentu konstruktoru Map :

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

Ekvivalentní kód jazyka C# je:

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

Tento příklad vytvoří Map objekt, který zobrazuje oblast určenou objektem MapSpan . Objekt MapSpan je za středem na zeměpisnou šířku a délku Location reprezentovanou objektem a zahrnuje 0,01 zeměpisné šířky a 0,01 stupňů délky. Informace o Location třídě naleznete v tématu Umístění a vzdálenost. Informace o předávání argumentů v jazyce XAML naleznete v tématu Předávání argumentů v jazyce XAML.

Výsledkem je, že když se mapa zobrazí, zacentruje se na konkrétní místo a zahrnuje určitý počet stupňů zeměpisné šířky a délky:

Snímek obrazovky ovládacího prvku mapy se zadaným umístěním

Vytvoření objektu MapSpan

Existuje řada přístupů k vytváření MapSpan objektů. Běžným přístupem je zadání požadovaných argumentů konstruktoru MapSpan . Jedná se o zeměpisnou šířku a délku reprezentovanou objektem Location a double hodnoty, které představují stupně zeměpisné šířky a délky, které jsou rozloženy objektem MapSpan. Informace o Location třídě naleznete v tématu Umístění a vzdálenost.

Alternativně existují tři metody ve MapSpan třídě, které vracejí nové MapSpan objekty:

ClampLatitude vrátí hodnotu se MapSpan stejnou LongitudeDegrees hodnotou jako instance třídy metody a poloměr definovaný jeho north a south argumenty.
FromCenterAndRadius vrátí hodnotu MapSpan , která je definována jeho Location a Distance argumenty.
WithZoom vrátí hodnotu se stejným středem MapSpan jako instance třídy metody, ale s poloměrem vynásobeným argumentem double .

Informace o struktuře Distance naleznete v tématu Umístění a vzdálenost.

MapSpan Po vytvoření se k datům o něm dají získat následující vlastnosti:

Center, typu Location, který představuje umístění v zeměpisném středu MapSpan.
LatitudeDegrees, typu double, který představuje stupně zeměpisné šířky, které jsou rozloženy MapSpan.
LongitudeDegrees, typu double, který představuje stupně délky, které jsou rozloženy MapSpan.
Radius, typu Distance, který představuje MapSpan poloměr.

Přesunutí mapy

Metodu Map.MoveToRegion lze volat, aby se změnila pozice a úroveň přiblížení mapy. Tato metoda přijímá MapSpan argument, který definuje oblast mapy, která se má zobrazit, a úroveň přiblížení.

Následující kód ukazuje příklad přesunutí zobrazené oblasti na mapě:

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

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

Zvětšení mapy

Úroveň přiblížení objektu Map lze změnit beze změny jeho umístění. Toho lze dosáhnout pomocí uživatelského rozhraní mapy nebo programově voláním MoveToRegion metody s argumentem MapSpan , který jako argument používá aktuální umístění 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));
}

V tomto příkladu MoveToRegion je volána metoda s argumentem MapSpan , který určuje aktuální umístění mapy, přes Map.VisibleRegion vlastnost a úroveň přiblížení jako stupně zeměpisné šířky a délky. Celkový výsledek je, že se změní úroveň přiblížení mapy, ale její umístění není. Alternativním přístupem k implementaci přiblížení na mapě je použití MapSpan.WithZoom metody k řízení faktoru přiblížení.

Důležité

Přiblížení mapy, ať už prostřednictvím uživatelského rozhraní mapy, nebo programově, vyžaduje, aby Map.IsZoomEnabled vlastnost je true. Další informace o této vlastnosti naleznete v tématu Zakázání lupy.

Přizpůsobení chování mapy

Chování objektu Map lze přizpůsobit nastavením některých jeho vlastností a zpracováním MapClicked události.

Poznámka:

Další přizpůsobení chování mapování lze dosáhnout přizpůsobením jeho obslužné rutiny. Další informace naleznete v tématu Přizpůsobení ovládacích prvků pomocí obslužných rutin.

Zobrazení provozních dat

Třída Map definuje IsTrafficEnabled vlastnost typu bool. Ve výchozím nastavení tato vlastnost znamená false, že data provozu nebudou na mapě překryvná. Pokud je tato vlastnost nastavená na true, překryjí se data provozu na mapě:

<maps:Map IsTrafficEnabled="true" />

Ekvivalentní kód jazyka C# je:

Map map = new Map
{
    IsTrafficEnabled = true
};

Zakázat posouvání

Třída Map definuje IsScrollEnabled vlastnost typu bool. Ve výchozím nastavení je truetato vlastnost , která označuje, že mapování je povoleno posouvání. Pokud je tato vlastnost nastavena na false, mapa se nebude posouvat:

<maps:Map IsScrollEnabled="false" />

Ekvivalentní kód jazyka C# je:

Map map = new Map
{
    IsScrollEnabled = false
};

Zakázání lupy

Třída Map definuje IsZoomEnabled vlastnost typu bool. Ve výchozím nastavení je truetato vlastnost , která označuje, že přiblížení lze provést na mapě. Pokud je tato vlastnost nastavená na false, nelze mapu přiblížit:

<maps:Map IsZoomEnabled="false" />

Ekvivalentní kód jazyka C# je:

Map map = new Map
{
    IsZoomEnabled = false
};

Zobrazit umístění uživatele

Třída Map definuje IsShowingUser vlastnost typu bool. Ve výchozím nastavení tato vlastnost znamená false, že mapa nezobrazuje aktuální umístění uživatele. Pokud je tato vlastnost nastavena na true, mapa zobrazuje aktuální umístění uživatele:

<maps:Map IsShowingUser="true" />

Ekvivalentní kód jazyka C# je:

Map map = new Map
{
    IsShowingUser = true
};

Důležité

Přístup k umístění uživatele vyžaduje, aby aplikaci byla udělena oprávnění k umístění. Další informace najdete v tématu Konfigurace platformy.

Kliknutí na mapu

Třída Map definuje MapClicked událost, která se aktivuje při klepnutí na mapu. Objekt MapClickedEventArgs , který doprovází událost má jednu vlastnost s názvem Location, typu Location. Při spuštění Location události se vlastnost nastaví na umístění mapy, na které jste klepli. Informace o Location třídě naleznete v tématu Umístění a vzdálenost.

Následující příklad kódu ukazuje obslužnou rutinu MapClicked události pro událost:

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

V tomto příkladu obslužná OnMapClicked rutina události vypíše zeměpisnou šířku a délku, která představuje umístění namapované klepnutím. Obslužná rutina události musí být zaregistrována s událostí MapClicked :

<maps:Map MapClicked="OnMapClicked" />

Ekvivalentní kód jazyka C# je:

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

Poloha a vzdálenost

Obor Microsoft.Maui.Devices.Sensors názvů obsahuje Location třídu, která se obvykle používá při umístění mapy a jeho špendlíků. Obor Microsoft.Maui.Maps názvů obsahuje Distance strukturu, kterou lze volitelně použít při umístění mapy.

Umístění

Třída Location zapouzdřuje umístění uložené jako hodnoty zeměpisné šířky a délky. Tato třída definuje následující vlastnosti:

Accuracy, typu double?, který představuje vodorovnou přesnost , v metrech Location.
Altitude, typu double?, který představuje výšku v metrech v referenčním systému, který je určen AltitudeReferenceSystem vlastností.
AltitudeReferenceSystem, typu AltitudeReferenceSystem, který určuje referenční systém, ve kterém je zadána hodnota výšky.
Course, typu double?, který označuje hodnotu stupňů relativní k pravému severu.
IsFromMockProvider, typu bool, který označuje, zda je umístění z GPS nebo od napodobení poskytovatele polohy.
Latitude, typu double, který představuje zeměpisnou šířku umístění v desetinných stupních.
Longitude, typu double, který představuje délku umístění v desetinných stupních.
Speed, typu double?, který představuje rychlost v metrech za sekundu.
Timestamp, typu DateTimeOffset, který představuje časové razítko při Location vytvoření.
VerticalAccuracy, typu double?, který určuje svislou přesnost , v metrech Location.

Location objekty se vytvářejí s jedním z přetížení konstruktoru Location , které obvykle vyžadují minimální argumenty zeměpisné šířky a délky zadané jako double hodnoty:

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

Při vytváření objektu Location se hodnota zeměpisné šířky uchytne mezi -90,0 a 90,0 a hodnota délky se uchytne mezi -180,0 a 180,0.

Poznámka:

Třída GeographyUtils má rozšiřující metodu ToRadians , která převádí double hodnotu ze stupňů na radiány a rozšiřující metodu ToDegrees double , která převádí hodnotu z radiánů na stupně.

Třída Location má CalculateDistance také metody, které vypočítají vzdálenost mezi dvěma umístěními.

Vzdálenost

Struktura Distance zapouzdřuje vzdálenost uloženou double jako hodnotu, která představuje vzdálenost v metrech. Tato struktura definuje tři vlastnosti jen pro čtení:

Kilometers, typu double, který představuje vzdálenost v kilometrech, které jsou rozloženy Distance.
Meters, typu double, který představuje vzdálenost v metrech, které jsou rozloženy Distance.
Miles, typu double, který představuje vzdálenost v mílích, které jsou rozloženy Distance.

Distance objekty lze vytvořit pomocí konstruktoru Distance , který vyžaduje argument měřiče zadaný jako double:

Distance distance = new Distance(1450.5);

Alternativně Distance lze objekty vytvořit pomocí FromKilometersmetod , FromMeters, FromMilesa 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);

Připínáčky

Ovládací Map prvek umožňuje, aby umístění byla označena Pin objekty. A Pin je značka mapy, která po klepnutí otevře informační okno:

Snímek obrazovky s připnutím mapy a oknem s informacemi

Pin Při přidání objektu Map.Pins do kolekce se špendlík vykreslí na mapě.

Třída Pin má následující vlastnosti:

Address, typu string, který obvykle představuje adresu pro umístění připnutí. Může to ale být jakýkoli string obsah, nejen adresa.
Label, typu string, který obvykle představuje název špendlíku.
Location, typu Location, který představuje zeměpisnou šířku a délku špendlíku.
Type, typu PinType, který představuje typ špendlíku.

Tyto vlastnosti jsou podporovány BindableProperty objekty, což znamená Pin , že může být cílem datových vazeb. Další informace o objektech datové vazby Pin naleznete v tématu Zobrazení kolekce připnutí.

Kromě toho Pin třída definuje MarkerClicked a InfoWindowClicked události. Událost MarkerClicked se aktivuje při klepnutí na špendlík a InfoWindowClicked událost se aktivuje, když se klepne na informační okno. Objekt PinClickedEventArgs , který doprovází obě události, má jednu HideInfoWindow vlastnost typu bool.

Zobrazení špendlíku

Do xaml je možné přidat Map APin:

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

Tento XAML vytvoří Map objekt, který zobrazuje oblast určenou objektem MapSpan . Objekt MapSpan je zacentrován na zeměpisnou šířku a délku Location reprezentovanou objektem, který rozšiřuje 0,01 stupňů zeměpisné šířky a délky. Objekt Pin se přidá do Map.Pins kolekce a nakreslený na Map místě určeném jeho Location vlastností. Informace o Location třídě naleznete v tématu Umístění a vzdálenost. Informace o předávání argumentů v XAML objektům, které nemají výchozí konstruktory, naleznete v tématu Předávání argumentů v XAML.

Ekvivalentní kód jazyka C# je:

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

Výsledkem tohoto ukázkového kódu je vykreslení jednoho špendlíku na mapě:

Snímek obrazovky s připnutím mapy

Interakce s špendlíkem

Ve výchozím nastavení se Pin při klepnutí na okno s informacemi zobrazí:

Snímek obrazovky s připnutím mapy a oknem s informacemi

Klepnutím na jiné místo na mapě zavřete okno s informacemi.

Třída Pin definuje MarkerClicked událost, která se aktivuje při Pin klepnutí. K zobrazení informačního okna není nutné zpracovat tuto událost. Místo toho by se tato událost měla zpracovat, když je potřeba upozornit, že došlo k klepnutí na konkrétní špendlík.

Třída Pin také definuje InfoWindowClicked událost, která se aktivuje při klepnutí na informační okno. Tato událost by se měla zpracovat, když je potřeba upozornit, že došlo k klepnutí na konkrétní okno s informacemi.

Následující kód ukazuje příklad zpracování těchto událostí:

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

Objekt PinClickedEventArgs , který doprovází obě události, má jednu HideInfoWindow vlastnost typu bool. Pokud je tato vlastnost nastavena uvnitř true obslužné rutiny události, informační okno bude skryto.

Typy připnutí

Pin objekty zahrnují Type vlastnost typu PinType, která představuje typ špendlíku. Výčet PinType definuje následující členy:

Genericpředstavuje obecný špendlík.
Placepředstavuje špendlík pro místo.
SavedPinpředstavuje špendlík pro uložené umístění.
SearchResultpředstavuje špendlík pro výsledek hledání.

Nastavení Pin.Type vlastnosti na libovolný PinType člen však nezmění vzhled vykresleného špendlíku. Místo toho je nutné přizpůsobit obslužnou rutinu Pin pro přizpůsobení vzhledu připnutí. Další informace o přizpůsobení obslužné rutiny naleznete v tématu Přizpůsobení ovládacích prvků pomocí obslužných rutin.

Zobrazení kolekce špendlíků

Třída Map definuje následující vlastnosti s možností vytvoření vazby:

ItemsSource, typu IEnumerable, který určuje kolekci IEnumerable položek připnutí, které se mají zobrazit.
ItemTemplate, typu DataTemplate, který určuje DataTemplate , že se má použít pro každou položku v kolekci zobrazených špendlíků.
ItemTemplateSelector, typu DataTemplateSelector, který určuje DataTemplateSelector , že se použije k výběru DataTemplate špendlíku za běhu.

Důležité

Vlastnost ItemTemplate má přednost, když jsou nastaveny ItemTemplate obě vlastnosti ItemTemplateSelector .

Hodnotu A Map lze naplnit špendlíky pomocí datové vazby k vytvoření vazby jeho ItemsSource vlastnosti k kolekci 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>
                    <maps:Pin Location="{Binding Location}"
                              Address="{Binding Address}"
                              Label="{Binding Description}" />
                </DataTemplate>    
            </maps:Map.ItemTemplate>
        </maps:Map>
        ...
    </Grid>
</ContentPage>

ItemsSource Data vlastnosti se sváže s Positions vlastností propojeného modelu viewmodel, který vrací ObservableCollection objektyPosition, což je vlastní typ. Každý Position objekt definuje Address a Description vlastnosti typu stringa Location vlastnost typu Location.

Vzhled každé položky v kolekci IEnumerable je definován nastavením ItemTemplate vlastnosti na DataTemplate objekt, který obsahuje Pin objekt, který data svázají s příslušnými vlastnostmi.

Následující snímek obrazovky ukazuje Map zobrazení Pin kolekce pomocí datové vazby:

Snímek obrazovky mapy s připínáky svázanými daty

Volba vzhledu položky za běhu

Vzhled každé položky v IEnumerable kolekci lze vybrat za běhu na základě hodnoty položky nastavením ItemTemplateSelector vlastnosti na 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>

Následující příklad ukazuje MapItemTemplateSelector třídu:

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

Třída MapItemTemplateSelector definuje a SanFranTemplate DataTemplate vlastnosti, které jsou nastaveny DefaultTemplate na různé šablony dat. Metoda OnSelectTemplate vrátí SanFranTemplate, který zobrazí "Xamarin" jako popisek při Pin klepnutí, když položka má adresu, která obsahuje "San Francisco". Pokud položka nemá adresu, která obsahuje "San Francisco", OnSelectTemplate metoda vrátí DefaultTemplatehodnotu .

Poznámka:

Případ použití pro tuto funkci je vazby vlastností podtříděných Pin objektů s různými vlastnostmi na základě podtypu Pin .

Další informace o selektorech šablon dat naleznete v tématu Vytvoření objektu DataTemplateSelector.

Mnohoúhelníky, lomené čáry a kruhy

Polygon, Polylinea Circle prvky umožňují zvýraznit konkrétní oblasti na mapě. A Polygon je plně uzavřený obrazec, který může mít tah a barvu výplně. A Polyline je čára, která zcela neohraničuje oblast. Zvýrazní Circle kruhovou oblast mapy:

Mnohoúhelník a lomené čáry na mapě Zakroužkuje na mapě.

Třídy Polygon, Polylinea Circle třídy odvozeny od MapElement třídy, která zveřejňuje následující bindable vlastnosti:

StrokeColorColor je objekt, který určuje barvu čáry.
StrokeWidthfloat je objekt, který určuje šířku čáry.

Třída Polygon definuje další vlastnost bindable:

FillColorColor je objekt, který určuje barvu pozadí mnohoúhelníku.

Kromě toho obě Polygon Polyline třídy definují GeoPath vlastnost, což je seznam Location objektů, které určují body obrazce.

Třída Circle definuje následující vlastnosti s možností vytvoření vazby:

CenterLocation je objekt, který definuje střed kruhu v zeměpisné šířce a délce.
RadiusDistance je objekt, který definuje poloměr kruhu v metrech, kilometrech nebo mílích.
FillColorColor je vlastnost, která určuje barvu v obvodu kruhu.

Vytvoření mnohoúhelníku

Objekt Polygon lze přidat do mapy tak, že ho vytvoříte a přidáte do kolekce mapy MapElements :

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

Ekvivalentní kód jazyka C# je:

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

Vlastnosti StrokeColor jsou StrokeWidth zadány k nastavení obrysu mnohoúhelníku. V tomto příkladu FillColor hodnota vlastnosti odpovídá StrokeColor hodnotě vlastnosti, ale má zadanou hodnotu alfa, aby byla průhledná, což umožňuje, aby podkladová mapa byla viditelná přes obrazec. Vlastnost GeoPath obsahuje seznam Location objektů definujících geografické souřadnice mnohoúhelníku. Objekt Polygon se vykreslí na mapě po jeho přidání do MapElements kolekce objektu Map.

Poznámka:

A Polygon je plně uzavřený obrazec. První a poslední body se automaticky připojí, pokud se neshodují.

Vytvoření čáry

Objekt Polyline lze přidat do mapy tak, že ho vytvoříte a přidáte do kolekce mapy MapElements :

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

Ekvivalentní kód jazyka C# je:

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

Vlastnosti StrokeColor a StrokeWidth vlastnosti jsou určeny k nastavení vzhledu čáry. Vlastnost GeoPath obsahuje seznam Location objektů definujících zeměpisné souřadnice čar. Objekt Polyline se vykreslí na mapě po jeho přidání do MapElements kolekce objektu Map.

Vytvoření kruhu

Objekt Circle lze přidat do mapy tak, že ho vytvoříte a přidáte do kolekce mapy MapElements :

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

Ekvivalentní kód jazyka C# je:

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

Umístění na Circle mapě je určeno hodnotou Center a Radius vlastnostmi. Vlastnost Center definuje střed kruhu v zeměpisné šířce a délce, zatímco Radius vlastnost definuje poloměr kruhu v metrech. Jsou zadány a StrokeColor StrokeWidth vlastnosti pro nastavení obrysu kruhu. Hodnota FillColor vlastnosti určuje barvu v obvodu kruhu. V tomto příkladu obě hodnoty barev určují alfa kanál, který umožňuje, aby podkladová mapa byla viditelná prostřednictvím kruhu. Objekt Circle se vykreslí na mapě po jeho přidání do MapElements kolekce objektu Map.

Poznámka:

GeographyUtils Třída má rozšiřující metoduToCircumferencePositions, která převádí Circle objekt (který definuje Center a Radius hodnoty vlastností) na seznam Location objektů, které tvoří souřadnice zeměpisné šířky a délky obvodu kruhu.

Geokódování a geografická poloha

Třídu Geocoding v Microsoft.Maui.Devices.Sensors oboru názvů lze použít k geografickému kódování značky místa k umístění souřadnic a zpětné souřadnice geokódu na značku místa. Další informace naleznete v tématu Geokódování.

Třídu Geolocation v Microsoft.Maui.Devices.Sensors oboru názvů lze použít k načtení aktuálních souřadnic geografické polohy zařízení. Další informace naleznete v tématu Geografické umístění.

Spuštění nativní mapové aplikace

Nativní mapovou aplikaci na každé platformě může třída spustit z aplikace Launcher .NET MAUI. Tato třída umožňuje aplikaci otevřít jinou aplikaci prostřednictvím vlastního schématu identifikátoru URI. Funkci spouštěče lze vyvolat pomocí OpenAsync metody, předání string Uri nebo argumentu, který představuje vlastní schéma adresy URL, které se má otevřít. Další informace o Launcher třídě naleznete ve spouštěči.

Poznámka:

Alternativou k použití Launcher třídy je použití Map třídy z Microsoft.Maui.ApplicationModel oboru názvů. Další informace najdete v tématu Mapa.

Aplikace mapy na každé platformě používá jedinečné vlastní schéma identifikátorů URI. Informace o schématu identifikátorů URI map v iOSu najdete v tématu Odkazy na mapy na developer.apple.com. Informace o schématu URI map v Androidu naleznete v příručce pro vývojáře Maps a záměry Google Maps pro Android v developers.android.com. Informace o schématu identifikátorů URI map ve Windows najdete v tématu Spuštění aplikace Windows Mapy.

Spuštění aplikace mapy v určitém umístění

Umístění v nativní aplikaci map lze otevřít přidáním příslušných parametrů dotazu do vlastního schématu identifikátorů URI pro každou aplikaci mapy:

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

Výsledkem tohoto ukázkového kódu je spuštění nativní mapové aplikace na jednotlivých platformách, přičemž mapa je zacentrovaná na špendlíku představujícím zadané umístění.

Spuštění aplikace mapy se směry

Nativní aplikaci mapy je možné spustit tak, že přidáte příslušné parametry dotazu do vlastního schématu identifikátorů URI pro každou mapovou aplikaci:

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

Výsledkem tohoto ukázkového kódu je spuštění nativní mapové aplikace na jednotlivých platformách, přičemž mapa je zacentrovaná na trase mezi zadanými umístěními.

Sdílet prostřednictvím

Mapovat

Nastavení

Inicializace mapy

Konfigurace platformy

iOS a Mac Catalyst

Android

Získání klíče rozhraní API Služby Google Maps

Zadejte číslo verze služeb Google Play.

Zadání oprávnění k umístění

Zadání oprávnění WRITE_EXTERNAL_STORAGE

Ovládací prvek Mapa

Zobrazení mapy

Typy map

Zobrazení konkrétního umístění na mapě

Vytvoření objektu MapSpan

Přesunutí mapy

Zvětšení mapy

Přizpůsobení chování mapy

Zobrazení provozních dat

Zakázat posouvání

Zakázání lupy

Zobrazit umístění uživatele

Kliknutí na mapu

Poloha a vzdálenost

Umístění

Vzdálenost

Připínáčky

Zobrazení špendlíku

Interakce s špendlíkem

Typy připnutí

Zobrazení kolekce špendlíků

Volba vzhledu položky za běhu

Mnohoúhelníky, lomené čáry a kruhy

Vytvoření mnohoúhelníku

Vytvoření čáry

Vytvoření kruhu

Geokódování a geografická poloha

Spuštění nativní mapové aplikace

Spuštění aplikace mapy v určitém umístění

Spuštění aplikace mapy se směry

Další materiály