Map

Lihat sampel

Kontrol .NET Multi-platform App UI (.NET MAUI) Map adalah tampilan lintas platform untuk menampilkan dan menganotasi peta. Kontrol Map menggunakan kontrol peta asli pada setiap platform, dan disediakan oleh paket Microsoft.Maui.Controls.Maps NuGet.

Penting

Pada Windows, Map kontrol menggunakan WinUI 3 MapControl, yang didukung oleh Azure Maps. Untuk menampilkan peta di Windows, konfigurasikan kunci langganan Azure Maps.

Pengaturan

Kontrol ini Map menggunakan kontrol peta asli pada setiap platform. Ini memberikan pengalaman peta yang cepat dan akrab bagi pengguna, tetapi berarti bahwa beberapa langkah konfigurasi diperlukan untuk mematuhi persyaratan API setiap platform.

Inisialisasi peta

Kontrol Map disediakan oleh paket Microsoft.Maui.Controls.Maps NuGet, yang harus ditambahkan ke proyek aplikasi .NET MAUI Anda.

Setelah menginstal paket NuGet, paket tersebut harus diinisialisasi di aplikasi Anda dengan memanggil UseMauiMaps metode pada MauiAppBuilder objek dalam CreateMauiApp metode kelas Anda 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();
    }
}

Setelah paket NuGet ditambahkan dan diinisialisasi, Map API dapat digunakan dalam proyek Anda.

Nota

Map dapat bertentangan dengan Map (yang menyediakan Map.OpenAsync untuk meluncurkan aplikasi peta asli). Kedua jenis biasanya tersedia melalui penggunaan implisit, dan menggunakan Map dalam kode dapat menghasilkan error CS0104: 'Map' is an ambiguous reference kesalahan kompilator. Untuk mengatasi hal ini, tambahkan alias namespace di file C# apa pun yang terjadi konflik.

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

Anda kemudian dapat menggunakan Map untuk merujuk ke peta kontrol di seluruh file tersebut.

Konfigurasi platform

Konfigurasi tambahan diperlukan di Android dan Windows sebelum peta akan ditampilkan. Selain itu, di iOS, Android, dan Mac Catalyst, mengakses lokasi pengguna memerlukan izin lokasi untuk diberikan ke aplikasi Anda.

iOS dan Mac Catalyst

Menampilkan dan berinteraksi dengan peta di iOS dan Mac Catalyst tidak memerlukan konfigurasi tambahan apa pun. Namun, untuk mengakses layanan lokasi, Anda harus mengatur permintaan layanan lokasi yang diperlukan di Info.plist. Ini biasanya akan menjadi satu atau beberapa hal berikut:

• NSLocationAlwaysAndWhenInUseUsageDescription – untuk menggunakan layanan lokasi setiap saat.
• NSLocationWhenInUseUsageDescription – untuk menggunakan layanan lokasi saat aplikasi sedang digunakan.

Untuk informasi selengkapnya, lihat Memilih otorisasi layanan lokasi untuk diminta di developer.apple.com.

Representasi XML untuk kunci ini di Info.plist ditunjukkan di bawah ini. Anda harus memperbarui string nilai untuk mencerminkan bagaimana aplikasi Anda menggunakan informasi lokasi:

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

Perintah kemudian ditampilkan saat aplikasi Anda mencoba mengakses lokasi pengguna, meminta akses:

Android

Proses konfigurasi untuk menampilkan dan berinteraksi dengan peta di Android adalah dengan:

1. Dapatkan kunci Google Maps API dan tambahkan ke manifes aplikasi Anda.
2. Tentukan nomor versi layanan Google Play dalam manifes.
3. [opsional] Tentukan izin lokasi dalam manifes.
4. [opsional] Tentukan izin WRITE_EXTERNAL_STORAGE dalam manifes.

Mendapatkan kunci GOOGLE Maps API

Untuk menggunakan Map kontrol pada Android, Anda harus membuat kunci API, yang akan digunakan oleh Google Maps SDK yang menjadi dependensi kontrol Map pada Android. Untuk melakukannya, ikuti petunjuk di Menyiapkan di Google Cloud Console dan Menggunakan Kunci API di developers.google.com.

Setelah Anda mendapatkan kunci API, kunci API harus ditambahkan dalam <application> elemen file Platforms/Android/AndroidManifest.xml Anda, dengan menentukannya sebagai nilai com.google.android.geo.API_KEY metadata:

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

Ini menyematkan kunci API ke dalam manifes. Tanpa kunci Map API yang valid, kontrol akan menampilkan kisi kosong.

Nota

com.google.android.geo.API_KEY adalah nama metadata yang direkomendasikan untuk kunci API. Kunci dengan nama ini dapat digunakan untuk mengautentikasi ke beberapa API berbasis Google Maps di Android. Untuk kompatibilitas mundur, com.google.android.maps.v2.API_KEY nama metadata dapat digunakan, tetapi hanya mengizinkan autentikasi ke Android Maps API v2. Aplikasi hanya dapat menentukan salah satu nama metadata kunci API.

Tentukan nomor versi layanan Google Play

Tambahkan deklarasi berikut dalam <application> elemen AndroidManifest.xml:

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

Ini menyematkan versi layanan Google Play yang digunakan oleh aplikasi saat dikompilasi ke dalam manifes.

Tentukan izin lokasi

Jika aplikasi Anda perlu mengakses lokasi pengguna, Anda harus meminta izin dengan menambahkan ACCESS_COARSE_LOCATION izin atau ACCESS_FINE_LOCATION (atau keduanya) ke manifes, sebagai turunan elemen <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>

Izin ini ACCESS_COARSE_LOCATION memungkinkan API untuk menggunakan WiFi atau data seluler, atau keduanya, untuk menentukan lokasi perangkat. Izin ini ACCESS_FINE_LOCATION memungkinkan API untuk menggunakan Global Positioning System (GPS), WiFi, atau data seluler untuk menentukan lokasi setepat mungkin.

Perintah kemudian ditampilkan saat aplikasi Anda mencoba mengakses lokasi pengguna, meminta akses:

Atau, izin ini dapat diaktifkan di editor manifes Android Visual Studio.

Tetapkan izin WRITE_EXTERNAL_STORAGE

Jika aplikasi Anda menargetkan API 22 atau yang lebih rendah, perlu menambahkan WRITE_EXTERNAL_STORAGE izin ke manifes, sebagai turunan elemen <manifest> :

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

Ini tidak diperlukan jika aplikasi Anda menargetkan API 23 atau yang lebih tinggi.

Windows

Pada Windows, Map kontrol menggunakan WinUI 3 MapControl, yang didukung oleh Azure Maps. Untuk menampilkan data peta, buat akun Azure Maps dan konfigurasikan aplikasi Anda dengan kunci langganan Azure Maps:

builder
    .UseMauiApp<App>()
    .UseMauiMaps();

builder.ConfigureEssentials(essentials =>
{
    essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY");
});

Tanpa kunci langganan Azure Maps yang valid, kontrol peta Windows tidak dapat mengautentikasi dengan Azure Maps dan tidak akan menampilkan data peta.

Anda dapat mengambil kunci langganan dari akun Azure Maps Anda di portal Azure. Untuk informasi selengkapnya, lihat Mengelola autentikasi di Azure Maps.

Implementasi Windows mendukung:

• Memindahkan wilayah peta secara terprogram dengan MoveToRegion.
• Jenis peta jalan, satelit, dan hibrid.
• Data lalu lintas.
• Menggulir dan memperbesar tampilan.
• Pin.

Karena keterbatasan WinUI 3MapControl, fitur berikut tidak didukung pada Windows dan tidak berpengaruh:

• Menampilkan lokasi pengguna dengan IsShowingUser.
• Menampilkan poligon, poliline, dan lingkaran dari koleksi MapElements.
• Sematkan label dan info windows (perilaku jendela info yang dijelaskan nanti dalam artikel ini tidak tersedia di Windows).
• Peristiwa MapClicked saat mengetuk latar belakang peta (peristiwa yang dijelaskan nanti dalam artikel ini tidak dipicu di Windows).

Pengendalian peta

Kelas Map menentukan properti berikut yang mengontrol tampilan dan perilaku peta:

• IsShowingUser, dari jenis bool, menunjukkan apakah peta menunjukkan lokasi pengguna saat ini.
• ItemsSource, dari jenis IEnumerable, yang menentukan kumpulan IEnumerable item pin yang akan ditampilkan.
• ItemTemplate, dari jenis DataTemplate, yang menentukan DataTemplate untuk diterapkan ke setiap item dalam kumpulan pin yang ditampilkan.
• ItemTemplateSelector, bertipe DataTemplateSelector, yang menentukan DataTemplateSelector yang akan digunakan untuk memilih DataTemplate pin pada waktu runtime.
• IsScrollEnabled, dari jenis bool, menentukan apakah peta diizinkan untuk menggulir.
• IsTrafficEnabled, bertipe bool, menunjukkan apakah data lalu lintas ditampilkan pada peta.
• IsZoomEnabled, dari jenis bool, menentukan apakah peta diizinkan untuk memperbesar tampilan.
• MapElements, dari jenis IList<MapElement>, mewakili daftar elemen di peta, seperti poligon dan poliline.
• MapType, dari jenis MapType, menunjukkan gaya tampilan peta.
• Pins, dari jenis IList<Pin>, mewakili daftar pin di peta.
• VisibleRegion, dari jenis MapSpan, mengembalikan wilayah peta yang saat ini ditampilkan.

Properti ini, dengan pengecualian properti MapElements, Pins, dan VisibleRegion, didukung oleh objek BindableProperty, yang berarti mereka dapat menjadi target pengikatan data.

Kelas Map juga mendefinisikan event MapClicked yang dipicu saat peta diketuk. Objek MapClickedEventArgs yang menyertai peristiwa memiliki satu properti bernama Location, dari jenis Location. Saat event diaktifkan, properti Location diatur ke lokasi peta yang diketuk. Untuk informasi tentang Location kelas, lihat Lokasi dan jarak.

Untuk informasi tentang properti ItemsSource, ItemTemplate, dan ItemTemplateSelector, lihat Menampilkan koleksi pin.

Menampilkan peta

Map Dapat ditampilkan dengan menambahkannya ke tata letak atau halaman:

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

Kode C# yang setara adalah:

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

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

Contoh ini memanggil konstruktor default Map , yang memusatkan peta di Maui, Hawaii::

Atau, MapSpan argumen dapat diteruskan ke Map konstruktor untuk mengatur titik tengah dan tingkat perbesar tampilan peta saat dimuat. Untuk informasi selengkapnya, lihat Menampilkan lokasi tertentu di peta.

Penting

.NET MAUI memiliki dua jenis Map - Microsoft.Maui.Controls.Maps.Map dan Microsoft.Maui.ApplicationModel.Map. Karena namespace adalah salah satu direktif dari .NET MAUI, saat menggunakan kontrol dari kode, Anda harus sepenuhnya memenuhi syarat penggunaan Anda atau menggunakan alias .

Jenis peta

Properti Map.MapType dapat diatur ke MapType anggota enumerasi untuk menentukan gaya tampilan peta. Enumerasi MapType menentukan anggota berikut:

• Street menentukan bahwa peta jalan akan ditampilkan.
• Satellite menentukan bahwa peta yang berisi citra satelit akan ditampilkan.
• Hybrid menentukan bahwa peta yang menggabungkan data jalan dan satelit akan ditampilkan.

Secara default, Map akan menampilkan peta jalan jika MapType properti tidak terdefinisi. Atau, properti MapType dapat diatur menjadi salah satu anggota MapType enumerasi:

<maps:Map MapType="Satellite" />

Kode C# yang setara adalah:

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

Menampilkan lokasi tertentu di peta

Wilayah peta yang akan ditampilkan saat peta dimuat dapat diatur dengan meneruskan MapSpan argumen ke Map konstruktor:

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

Kode C# yang setara adalah:

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

Contoh ini membuat Map objek yang memperlihatkan wilayah yang ditentukan oleh MapSpan objek. Objek MapSpan berpusat pada garis lintang dan garis bujur yang diwakili oleh Location objek, dan mencakup 0,01 garis lintang dan 0,01 derajat garis bujur. Untuk informasi tentang Location kelas, lihat Lokasi dan jarak. Untuk informasi tentang meneruskan argumen di XAML, lihat Meneruskan argumen di XAML.

Hasilnya adalah bahwa ketika peta ditampilkan, peta berpusat pada lokasi tertentu, dan mencakup sejumlah derajat lintang dan garis bujur tertentu:

Membuat objek MapSpan

Ada sejumlah pendekatan untuk membuat MapSpan objek. Pendekatan umum adalah menyediakan argumen yang diperlukan ke MapSpan konstruktor. Ini adalah garis lintang dan garis bujur yang diwakili oleh objek Location, dan nilai double yang mewakili derajat garis lintang dan garis bujur yang terbentang oleh MapSpan. Untuk informasi tentang Location kelas, lihat Lokasi dan jarak.

Atau, ada tiga metode di MapSpan kelas yang mengembalikan objek baru MapSpan :

1. ClampLatitude mengembalikan MapSpan dengan LongitudeDegrees yang sama seperti instance kelas dari metode tersebut, dan radius didefinisikan oleh argumen north dan south.
2. FromCenterAndRadius mengembalikan MapSpan yang didefinisikan oleh argumen Location dan Distance.
3. WithZoom mengembalikan sebuah MapSpan yang memiliki pusat yang sama dengan instans kelas dari metode ini, tetapi dengan radius yang dikalikan dengan argumen double.

Untuk informasi tentang Distance struktur, lihat Lokasi dan jarak.

MapSpan Setelah dibuat, properti berikut dapat diakses untuk mengambil data tentang hal itu:

• Center, dari jenis Location, yang mewakili lokasi di pusat geografis dari MapSpan.
• LatitudeDegrees, dari jenis double, yang mewakili derajat lintang yang terbentang oleh MapSpan.
• LongitudeDegrees, dengan tipe double, yang mewakili derajat bujur yang terbentang oleh MapSpan.
• Radius, dari jenis Distance, yang mewakili MapSpan radius.

Memindahkan peta

Metode Map.MoveToRegion ini dapat dipanggil untuk mengubah posisi dan tingkat perbesar tampilan peta. Metode ini menerima MapSpan argumen yang menentukan wilayah peta yang akan ditampilkan, dan tingkat pembesarannya.

Kode berikut menunjukkan contoh pemindahan wilayah yang ditampilkan pada peta:

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

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

Memperbesar peta

Tingkat Map perbesar tampilan dapat diubah tanpa mengubah lokasinya. Ini dapat dicapai menggunakan UI peta, atau secara terprogram dengan memanggil MoveToRegion metode dengan MapSpan argumen yang menggunakan lokasi saat ini sebagai Location argumen:

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

Dalam contoh ini, metode MoveToRegion dipanggil dengan argumen MapSpan yang menentukan lokasi peta saat ini, melalui properti Map.VisibleRegion, dan tingkat zoom dalam derajat garis lintang dan bujur. Hasil keseluruhan adalah bahwa tingkat perbesar tampilan peta diubah, tetapi lokasinya tidak. Pendekatan alternatif untuk menerapkan zoom pada peta adalah dengan menggunakan MapSpan.WithZoom metode untuk mengontrol faktor zoom.

Penting

Memperbesar tampilan peta, baik dari UI peta atau secara terprogram, mengharuskan bahwa properti Map.IsZoomEnabled adalah true. Untuk informasi selengkapnya tentang properti ini, lihat Menonaktifkan zoom.

Menyesuaikan perilaku peta

Perilaku Map dapat disesuaikan dengan mengatur beberapa dari propertinya dan menangani acara MapClicked.

Nota

Penyesuaian perilaku peta tambahan dapat dicapai dengan menyesuaikan handler-nya. Untuk informasi selengkapnya, lihat Menyesuaikan kontrol dengan handler.

Menunjukkan data lalu lintas

Kelas Map mendefinisikan IsTrafficEnabled properti jenis bool. Secara default properti ini adalah false, yang menunjukkan bahwa data lalu lintas tidak akan dilapisi di peta. Ketika properti ini diatur ke true, data lalu lintas dilapisi pada peta:

<maps:Map IsTrafficEnabled="true" />

Kode C# yang setara adalah:

Map map = new Map
{
    IsTrafficEnabled = true
};

Nonaktifkan gulir

Kelas Map mendefinisikan IsScrollEnabled properti jenis bool. Secara default properti ini adalah true, yang menunjukkan bahwa peta diizinkan untuk menggulir. Ketika properti ini diatur ke false, peta tidak akan menggulir:

<maps:Map IsScrollEnabled="false" />

Kode C# yang setara adalah:

Map map = new Map
{
    IsScrollEnabled = false
};

Nonaktifkan perbesar tampilan

Kelas Map mendefinisikan IsZoomEnabled properti jenis bool. Secara default properti ini adalah true, yang menunjukkan bahwa zoom dapat dilakukan di peta. Ketika properti ini diatur ke false, peta tidak dapat diperbesar:

<maps:Map IsZoomEnabled="false" />

Kode C# yang setara adalah:

Map map = new Map
{
    IsZoomEnabled = false
};

Perlihatkan lokasi pengguna

Kelas Map mendefinisikan IsShowingUser properti jenis bool. Secara default properti ini adalah false, yang menunjukkan bahwa peta tidak menampilkan lokasi pengguna saat ini. Ketika properti ini diatur ke true, peta menunjukkan lokasi pengguna saat ini:

<maps:Map IsShowingUser="true" />

Kode C# yang setara adalah:

Map map = new Map
{
    IsShowingUser = true
};

Penting

Mengakses lokasi pengguna memerlukan izin lokasi yang telah diberikan ke aplikasi. Untuk informasi selengkapnya, lihat Konfigurasi platform.

Klik peta

Kelas Map mendefinisikan MapClicked event yang dipicu saat peta diketuk. Objek MapClickedEventArgs yang menyertai peristiwa memiliki satu properti bernama Location, dari jenis Location. Saat event diaktifkan, properti Location diatur ke lokasi peta yang diketuk. Untuk informasi tentang Location kelas, lihat Lokasi dan jarak.

Contoh kode berikut menunjukkan penanganan aktivitas untuk peristiwa:MapClicked

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

Dalam contoh ini, pengendali acara OnMapClicked menampilkan garis lintang dan bujur yang mewakili lokasi peta yang diketuk. Pengelola kejadian harus didaftarkan dengan kejadian MapClicked.

<maps:Map MapClicked="OnMapClicked" />

Kode C# yang setara adalah:

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

Lokasi dan jarak

Namespace Microsoft.Maui.Devices.Sensors berisi kelas Location yang biasanya digunakan saat memposisikan peta dan pinnya. Namespace Microsoft.Maui.Maps berisi struct Distance yang dapat digunakan secara opsional saat memosisikan peta.

Lokasi

Kelas Location merangkum lokasi yang disimpan sebagai nilai garis lintang dan bujur. Kelas ini mendefinisikan properti berikut:

• Accuracy, dari jenis double?, yang mewakili akurasi Locationhorizontal , dalam meter.
• Altitude, jenis double?, yang mewakili ketinggian dalam meter pada sistem referensi yang ditentukan melalui properti AltitudeReferenceSystem.
• AltitudeReferenceSystem, dari jenis AltitudeReferenceSystem, yang menentukan sistem referensi tempat nilai ketinggian disediakan.
• Course, dari jenis double?, yang menunjukkan nilai derajat relatif terhadap utara sejati.
• IsFromMockProvider, dari jenis bool, yang menunjukkan apakah lokasi berasal dari GPS atau dari penyedia lokasi tiruan.
• Latitude, dari jenis double, yang mewakili garis lintang lokasi dalam derajat desimal.
• Longitude, dari jenis double, yang mewakili bujur lokasi dalam derajat desimal.
• Speed, dari jenis double?, yang mewakili kecepatan dalam meter per detik.
• Timestamp, dari jenis DateTimeOffset, yang mewakili tanda waktu saat Location dibuat.
• VerticalAccuracy, dari jenis double?, yang menentukan akurasi vertikal Location, dalam meter.

Location objek dibuat dengan salah satu overload konstruktor Location, yang biasanya memerlukan setidaknya argumen garis lintang dan bujur yang ditentukan sebagai nilai double.

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

Saat membuat Location objek, nilai garis lintang akan dijepit antara -90,0 dan 90,0, dan nilai bujur akan dijepit antara -180,0 dan 180,0.

Nota

Kelas GeographyUtils ini memiliki ToRadians metode ekstensi yang mengonversi double nilai dari derajat ke radian, dan ToDegrees metode ekstensi yang mengonversi double nilai dari radian ke derajat.

Kelas ini Location juga memiliki CalculateDistance metode yang menghitung jarak antara dua lokasi.

Jarak

Struktur Distance merangkum jarak yang disimpan sebagai double nilai, yang mewakili jarak dalam meter. Struktur ini mendefinisikan tiga properti baca-saja:

• Kilometers, tipe double, yang mewakili jarak dalam kilometer yang diliputi oleh Distance.
• Meters, dari jenis double, yang mewakili jarak dalam meter yang dicakup oleh Distance.
• Miles, dari jenis double, yang mewakili jarak dalam mil yang terbentang oleh Distance.

Distance objek dapat dibuat dengan Distance konstruktor, yang memerlukan argumen meter yang ditentukan sebagai double:

Distance distance = new Distance(1450.5);

Atau, Distance objek dapat dibuat dengan FromKilometersmetode pabrik , , FromMetersFromMiles, dan 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);

Pins

Fitur Map memungkinkan lokasi untuk ditandai dengan objek Pin. Pin adalah penanda peta yang membuka jendela informasi saat diketuk:

Pin Ketika sebuah objek ditambahkan ke Map.Pins kumpulan, pin akan ditampilkan di peta.

Kelas Pin memiliki properti berikut:

• Address, dari jenis string, yang biasanya mewakili alamat untuk lokasi pin. Namun, itu bisa menjadi konten apa pun string , bukan hanya alamat.
• Label, dari jenis string, yang biasanya mewakili judul pin.
• Location, dari jenis Location, yang mewakili garis lintang dan bujur pin.
• Type, dari jenis PinType, yang mewakili jenis pin.

Properti ini didukung oleh BindableProperty objek, yang berarti Pin dapat menjadi target pengikatan data. Untuk informasi selengkapnya tentang objek pengikatan Pin data, lihat Menampilkan kumpulan pin.

Selain itu, Pin kelas mendefinisikan MarkerClicked dan InfoWindowClicked event. Peristiwa MarkerClicked dipicu saat pin diketuk, dan peristiwa InfoWindowClicked dipicu saat jendela informasi diketuk. Objek PinClickedEventArgs yang menyertai kedua peristiwa memiliki satu HideInfoWindow properti, dari jenis bool.

Menampilkan pin

Pin Dapat ditambahkan ke Map dalam 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>

XAML ini membuat Map objek yang menunjukkan wilayah yang ditentukan oleh MapSpan objek. Objek MapSpan berpusat pada garis lintang dan garis bujur yang diwakili oleh objek Location, yang memanjang 0,01 derajat lintang dan bujur. Objek Pin ditambahkan ke dalam koleksi Map.Pins, dan ditampilkan pada Map di lokasi yang ditetapkan oleh properti Location-nya. Untuk informasi tentang Location kelas, lihat Lokasi dan jarak. Untuk informasi tentang meneruskan argumen di XAML ke objek yang tidak memiliki konstruktor default, lihat Meneruskan argumen di XAML.

Kode C# yang setara adalah:

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

Contoh kode ini menghasilkan satu pin yang dirender di peta:

Berinteraksi dengan pin

Secara default, ketika Pin diketuk, jendela informasinya akan ditampilkan.

Mengetuk di tempat lain di peta menutup jendela informasi.

Kelas Pin mendefinisikan event MarkerClicked, yang dijalankan saat Pin diketuk. Tidak perlu mengelola acara ini untuk menampilkan jendela informasi. Sebaliknya, peristiwa ini harus ditangani ketika ada kebutuhan untuk diberi tahu bahwa pin tertentu telah diketuk.

Kelas Pin juga menentukan InfoWindowClicked event yang ditembakkan saat jendela informasi diketuk. Kejadian ini harus ditangani ketika ada persyaratan untuk diberi tahu bahwa jendela informasi tertentu telah diketuk.

Kode berikut menunjukkan contoh penanganan peristiwa ini:

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

Objek PinClickedEventArgs yang menyertai kedua peristiwa memiliki satu HideInfoWindow properti, dari jenis bool. Ketika properti ini diatur ke true dalam penanganan aktivitas, jendela informasi akan disembunyikan.

Jenis pin

Objek Pin menyertakan sebuah properti bernama Type, bertipe PinType, yang mewakili jenis pin. Enumerasi PinType menentukan anggota berikut:

• Generic, mewakili pin generik.
• Place, mewakili pin untuk suatu tempat.
• SavedPin, mewakili pin untuk lokasi yang disimpan.
• SearchResult, mewakili pin untuk hasil pencarian.

Namun, menetapkan properti Pin.Type ke anggota mana pun dari PinType tidak mengubah tampilan pin yang dirender. Sebagai gantinya, sesuaikan Pin handler tersebut untuk mengatur tampilan pin. Untuk informasi selengkapnya tentang penyesuaian handler, lihat Menyesuaikan kontrol dengan handler.

Menampilkan koleksi pin

Kelas Map menentukan properti yang dapat diikat berikut:

• ItemsSource, dari jenis IEnumerable, yang menentukan kumpulan IEnumerable item pin yang akan ditampilkan.
• ItemTemplate, dari jenis DataTemplate, yang menentukan DataTemplate untuk diterapkan ke setiap item dalam kumpulan pin yang ditampilkan.
• ItemTemplateSelector, bertipe DataTemplateSelector, yang menentukan DataTemplateSelector yang akan digunakan untuk memilih DataTemplate pin pada waktu runtime.

Penting

Properti ItemTemplate lebih diutamakan ketika properti ItemTemplate dan ItemTemplateSelector telah diatur.

Map dapat diisi dengan pin menggunakan pengikatan data agar propertinya terikat ke koleksi ItemsSource.

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

Data properti ItemsSource ini mengikat ke properti Positions pada viewmodel yang terhubung, yang mengembalikan ObservableCollection dari objek Position, yang merupakan tipe kustom. Setiap objek Position menentukan properti Address dan Description dengan jenis string, serta properti Location dengan jenis Location.

Tampilan setiap item dalam koleksi IEnumerable ditentukan dengan mengatur properti ItemTemplate ke sebuah DataTemplate yang berisi objek Pin yang mengikat data ke properti yang sesuai.

Cuplikan layar berikut menunjukkan Map yang menampilkan koleksi Pin dengan menggunakan pemautan data.

Pilih tampilan item saat runtime

Tampilan setiap item dalam koleksi IEnumerable dapat dipilih pada waktu run-time, berdasarkan nilai dari item tersebut, dengan mengatur properti ItemTemplateSelector ke 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>

Contoh berikut menunjukkan kelas 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;
    }
}

Kelas MapItemTemplateSelector menentukan DefaultTemplate dan SanFranTemplateDataTemplate properti yang diatur ke templat data yang berbeda. Metode OnSelectTemplate mengembalikan SanFranTemplate, yang menampilkan "Xamarin" sebagai label saat Pin diketuk, ketika item memiliki alamat yang berisi "San Francisco". Ketika item tidak memiliki alamat yang berisi "San Francisco", OnSelectTemplate metode mengembalikan DefaultTemplate.

Nota

Salah satu cara penggunaan dari fungsionalitas ini adalah mengaitkan properti dari objek subkelas Pin dengan properti yang berbeda, berdasarkan subjenis Pin.

Untuk informasi selengkapnya tentang pemilih templat data, lihat Membuat DataTemplateSelector.

Poligon, poliline, dan lingkaran

Polygonelemen , Polyline, dan Circle memungkinkan Anda untuk menyoroti area tertentu di peta. Sebuah Polygon adalah bentuk yang tertutup sepenuhnya yang dapat memiliki garis tepi dan warna isian. Sebuah Polyline adalah garis yang tidak sepenuhnya menutup area. Menyoroti Circle sebuah area melingkar dari peta:

Kelas Polygon, Polyline, dan Circle berasal dari MapElement kelas , yang mengekspos properti yang dapat diikat berikut:

• StrokeColor adalah Color objek yang menentukan warna garis.
• StrokeWidth adalah float objek yang menentukan lebar garis.

Kelas Polygon menentukan properti tambahan yang dapat diikat:

• FillColor adalah Color objek yang menentukan warna latar belakang poligon.

Selain itu, Polygon dan Polyline kelas keduanya mendefinisikan properti GeoPath, yang merupakan daftar objek Location yang menentukan titik bentuk.

Kelas Circle menentukan properti yang dapat diikat berikut:

• Center adalah Location objek yang mendefinisikan pusat lingkaran, dalam garis lintang dan bujur.
• Radius adalah Distance objek yang mendefinisikan radius lingkaran dalam meter, kilometer, atau mil.
• FillColor adalah Color properti yang menentukan warna dalam perimeter lingkaran.

Membuat poligon

Objek Polygon dapat ditambahkan ke peta dengan membuat instans dan menambahkannya ke koleksi peta 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>

Kode C# yang setara adalah:

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

Properti StrokeColor dan StrokeWidth ditentukan untuk mengatur kerangka poligon. Dalam contoh ini, nilai properti FillColor cocok dengan nilai properti StrokeColor tetapi memiliki nilai alfa yang ditentukan untuk membuatnya transparan, memungkinkan peta di bawahnya terlihat melalui bentuk tersebut. Properti GeoPath berisi daftar Location objek yang menentukan koordinat geografis titik poligon. Objek Polygon dirender pada peta setelah ditambahkan ke MapElements koleksi Map.

Nota

Polygon adalah bentuk yang tertutup sepenuhnya. Poin pertama dan terakhir akan terhubung secara otomatis jika tidak cocok.

Membuat poliline

Objek Polyline dapat ditambahkan ke peta dengan membuat instans dan menambahkannya ke koleksi peta 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>

Kode C# yang setara adalah:

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

Properti StrokeColor dan StrokeWidth ditentukan untuk mengatur tampilan baris. Properti GeoPath berisi daftar Location objek yang menentukan koordinat geografis titik poliline. Objek Polyline dirender pada peta setelah ditambahkan ke MapElements koleksi Map.

Membuat lingkaran

Objek Circle dapat ditambahkan ke peta dengan membuat instans dan menambahkannya ke koleksi peta 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>

Kode C# yang setara adalah:

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

Lokasi Circle pada Peta ditentukan oleh nilai dari properti Center dan Radius. Properti Center mendefinisikan pusat lingkaran, dalam garis lintang dan bujur, sementara Radius properti menentukan radius lingkaran dalam meter. Properti StrokeColor dan StrokeWidth ditentukan untuk mengatur kerangka lingkaran. Nilai FillColor properti menentukan warna dalam perimeter lingkaran. Dalam contoh ini, kedua nilai warna menentukan saluran alfa, memungkinkan peta yang mendasarinya terlihat melalui lingkaran. Objek Circle akan dirender pada peta setelah ditambahkan ke koleksi MapElements dari Map.

Nota

Kelas GeographyUtils memiliki ToCircumferencePositions metode ekstensi yang mengonversi Circle objek (yang menentukan Center nilai Radius properti) ke daftar Location objek yang membentuk koordinat garis lintang dan bujur dari perimeter lingkaran.

Geocoding dan geolokasi

Kelas Geocoding, di namespace Microsoft.Maui.Devices.Sensors, dapat digunakan untuk mengubah sebuah placemark menjadi koordinat posisi dan mengubah koordinat menjadi sebuah placemark. Untuk informasi selengkapnya, lihat Geocoding.

Kelas Geolocation, di namespace Microsoft.Maui.Devices.Sensors, dapat digunakan untuk mengambil koordinat geolokasi perangkat saat ini. Untuk informasi selengkapnya, lihat Geolokasi.

Meluncurkan aplikasi peta asli

Aplikasi peta asli di setiap platform dapat diluncurkan dari aplikasi .NET MAUI oleh kelas Launcher. Kelas ini memungkinkan aplikasi untuk membuka aplikasi lain melalui skema URI kustomnya. Fungsionalitas peluncur dapat dipanggil dengan metode OpenAsync, meneruskan argumen string atau Uri yang mewakili skema URL kustom untuk dibuka. Untuk informasi selengkapnya tentang Launcher kelas, lihat Peluncur.

Nota

Alternatif untuk menggunakan kelas Launcher adalah menggunakan kelas Map dari namespace Microsoft.Maui.ApplicationModel. Untuk informasi selengkapnya, lihat Peta.

Aplikasi peta di setiap platform menggunakan skema URI kustom yang unik. Untuk informasi tentang skema URI peta di iOS, lihat Memetakan Tautan di developer.apple.com. Untuk informasi tentang skema URI peta di Android, lihat Panduan Pengembang Maps dan Niat Google Maps untuk Android di developers.android.com. Untuk informasi tentang skema URI peta di Windows, lihat Launch aplikasi Peta Windows.

Luncurkan aplikasi peta di lokasi tertentu

Lokasi di aplikasi peta asli dapat dibuka dengan menambahkan parameter kueri yang sesuai ke skema URI kustom untuk setiap aplikasi peta:

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

Contoh kode ini menghasilkan aplikasi peta asli yang diluncurkan di setiap platform, dengan peta yang dipusatkan pada pin yang mewakili lokasi yang ditentukan.

Luncurkan aplikasi peta dengan petunjuk arah

Aplikasi peta asli dapat diluncurkan menampilkan petunjuk arah, dengan menambahkan parameter kueri yang sesuai ke skema URI kustom untuk setiap aplikasi peta:

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

Contoh kode ini menghasilkan aplikasi peta asli yang diluncurkan di setiap platform, dengan peta berpusat pada rute antara lokasi yang ditentukan.