지도

샘플 찾아보기

.NET 다중 플랫폼 앱 UI(.NET MAUI) Map 컨트롤은 지도를 표시하고 주석을 추가하기 위한 플랫폼 간 보기입니다. 컨트롤은 Map 각 플랫폼에서 네이티브 맵 컨트롤을 사용하며 Microsoft.Maui.Controls.지도 NuGet 패키지.

Important

Map WinUI에서 지도 컨트롤이 없기 때문에 Windows에서는 컨트롤이 지원되지 않습니다. 그러나 CommunityToolkit.Maui.지도 NuGet 패키지는 Windows에서 Bing 지도 WebView 대한 액세스를 제공합니다. 자세한 내용은 시작하기를 참조하세요.

설정

컨트롤은 Map 각 플랫폼에서 네이티브 맵 컨트롤을 사용합니다. 이는 사용자에게 빠르고 친숙한 맵 환경을 제공하지만 각 플랫폼 API 요구 사항을 준수하기 위해 일부 구성 단계가 필요하다는 것을 의미합니다.

지도 초기화

컨트롤은 MapMicrosoft.Maui.Controls.지도 .NET MAUI 앱 프로젝트에 추가해야 하는 NuGet 패키지입니다.

NuGet 패키지를 설치한 후에는 클래스의 메서드에서 개체의 MauiAppBuilder 메서드를 호출 UseMauiMap 하여 앱에서 CreateMauiAppMauiProgram 초기화해야 합니다.

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

NuGet 패키지가 추가되고 초기화 Map 되면 프로젝트에서 API를 사용할 수 있습니다.

플랫폼 구성

지도가 표시되기 전에 Android에서 추가 구성이 필요합니다. 또한 iOS, Android 및 Mac Catalyst에서 사용자의 위치에 액세스하려면 앱에 위치 권한이 부여되어야 합니다.

iOS 및 Mac Catalyst

iOS 및 Mac Catalyst에서 지도를 표시하고 상호 작용할 때는 추가 구성이 필요하지 않습니다. 그러나 위치 서비스에 액세스하려면 Info.plist에서 필요한 위치 서비스 요청을 설정해야 합니다. 일반적으로 다음 중 하나 이상이 됩니다.

• NSLocationAlwaysAndWhenInUseUsageDescription – 항상 위치 서비스를 사용하기 위한 것입니다.
• NSLocationWhenInUseUsageDescription – 앱이 사용 중일 때 위치 서비스를 사용하기 위한 것입니다.

자세한 내용은 developer.apple.com 요청할 위치 서비스 권한 부여 선택을 참조하세요.

Info.plist에서 이러한 키에 대한 XML 표현은 다음과 같습니다. 앱에서 string 위치 정보를 사용하는 방식을 반영하도록 값을 업데이트해야 합니다.

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

그러면 앱이 사용자의 위치에 액세스하려고 할 때 액세스 권한을 요청하는 프롬프트가 표시됩니다.

Android

Android에서 지도를 표시하고 상호 작용하기 위한 구성 프로세스는 다음과 같습니다.

1. Google 지도 API 키를 가져와 앱 매니페스트에 추가합니다.
2. 매니페스트에서 Google Play 서비스 버전 번호를 지정합니다.
3. [선택 사항] 매니페스트에서 위치 권한을 지정합니다.
4. [선택 사항] 매니페스트에서 WRITE_EXTERNAL_STORAGE 권한을 지정합니다.

Google 지도 API 키 가져오기

Android에서 컨트롤을 Map 사용하려면 컨트롤이 Android에 의존하는 Google 지도 SDK에서 Map 사용하는 API 키를 생성해야 합니다. 이렇게 하려면 Google 클라우드 콘솔에서 설정의 지침을 따르고 developers.google.com API 키를 사용합니다.

API 키를 가져온 후에는 메타데이터 값으로 지정하여 Platforms/Android/AndroidManifest.xml 파일의 com.google.android.geo.API_KEY 요소 내에 <application> 추가해야 합니다.

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

그러면 API 키가 매니페스트에 포함됩니다. 유효한 API 키가 없으면 컨트롤에 Map 빈 표가 표시됩니다.

참고 항목

com.google.android.geo.API_KEY 는 API 키에 권장되는 메타데이터 이름입니다. 이 이름의 키를 사용하여 Android에서 여러 Google 지도 기반 API에 인증할 수 있습니다. 이전 버전과의 호환성을 com.google.android.maps.v2.API_KEY 위해 메타데이터 이름을 사용할 수 있지만 Android 지도 API v2에 대한 인증만 허용합니다. 앱은 API 키 메타데이터 이름 중 하나만 지정할 수 있습니다.

Google Play 서비스 버전 번호 지정

AndroidManifest.xml 요소 내에 다음 선언을 <application> 추가합니다.

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

이렇게 하면 앱이 컴파일된 Google Play 서비스 버전이 매니페스트에 포함됩니다.

위치 권한 지정

앱이 사용자의 위치에 액세스해야 하는 경우 매니페스트에 요소의 자식 <manifest> 으로 사용 권한(ACCESS_FINE_LOCATION또는 둘 다)을 추가하여 ACCESS_COARSE_LOCATION 사용 권한을 요청해야 합니다.

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

이 권한을 통해 API는 ACCESS_COARSE_LOCATION WiFi 또는 모바일 데이터 또는 둘 다를 사용하여 디바이스의 위치를 확인할 수 있습니다. 이 권한을 통해 API는 ACCESS_FINE_LOCATION GPS(Global Positioning System), WiFi 또는 모바일 데이터를 사용하여 가능한 한 정확한 위치를 결정할 수 있습니다.

그러면 앱이 사용자의 위치에 액세스하려고 할 때 액세스 권한을 요청하는 프롬프트가 표시됩니다.

또는 Visual Studio의 Android 매니페스트 편집기에서 이러한 권한을 사용하도록 설정할 수 있습니다.

WRITE_EXTERNAL_STORAGE 권한 지정

앱이 API 22 이하를 대상으로 하는 경우 요소의 <manifest> 자식으로 매니페스트에 권한을 추가 WRITE_EXTERNAL_STORAGE 해야 합니다.

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

앱이 API 23을 대상으로 하는 경우에는 필요하지 않습니다.

맵 컨트롤

클래스는 Map 맵 모양 및 동작을 제어하는 다음 속성을 정의합니다.

• IsShowingUser형식 bool의 맵에 사용자의 현재 위치가 표시되는지 여부를 나타냅니다.
• ItemsSource- 표시할 핀 항목의 컬렉션을 지정하는 형식 IEnumerable입니다 IEnumerable .
• ItemTemplate- 표시된 핀 컬렉션의 각 항목에 적용할 항목을 지정 DataTemplate 하는 형식DataTemplate입니다.
• ItemTemplateSelector- DataTemplateSelector런타임에 핀을 DataTemplateSelector 선택하는 DataTemplate 데 사용할 형식을 지정합니다.
• IsScrollEnabled형식 bool의 맵을 스크롤할 수 있는지 여부를 결정합니다.
• IsTrafficEnabled형식 bool의 트래픽 데이터가 맵에 오버레이되는지 여부를 나타냅니다.
• IsZoomEnabled형식 bool의 맵을 확대/축소할 수 있는지 여부를 결정합니다.
• MapElements형식 IList<MapElement>의 다각형 및 다각형과 같은 맵의 요소 목록을 나타냅니다.
• MapType형식 MapType의 맵의 표시 스타일을 나타냅니다.
• Pins형식 IList<Pin>의 맵에 있는 핀 목록을 나타냅니다.
• VisibleRegion형식 MapSpan의 맵은 현재 표시된 맵 영역을 반환합니다.

및 속성을 제외한 MapElementsPinsVisibleRegion 이러한 속성은 개체에 의해 BindableProperty 지원되므로 데이터 바인딩의 대상이 될 수 있습니다.

또한 클래스는 Map 맵을 MapClicked 탭할 때 발생하는 이벤트를 정의합니다. MapClickedEventArgs 이벤트와 함께 제공되는 개체에는 형식Location의 단일 속성이 있습니다Location. 이벤트가 발생하면 Location 속성이 탭된 지도 위치로 설정됩니다. 클래스에 Location 대한 자세한 내용은 위치 및 거리를 참조하세요.

및 ItemTemplateItemTemplateSelector 속성에 ItemsSource대한 자세한 내용은 핀 컬렉션 표시를 참조하세요.

지도 표시

A Map 는 레이아웃 또는 페이지에 추가하여 표시할 수 있습니다.

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

해당하는 C# 코드는 다음과 같습니다.

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

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

이 예제에서는 하와이 마우이의 지도를 중심으로 하는 기본 Map 생성자를 호출합니다.

또는 인수를 MapSpan 생성자에 전달하여 Map 로드될 때 지도의 중심점 및 확대/축소 수준을 설정할 수 있습니다. 자세한 내용은 지도에 특정 위치 표시를 참조하세요.

Important

.NET MAUI에는 두 Map 가지 형식이 Microsoft.Maui.Controls.Maps.Map 있습니다 Microsoft.Maui.ApplicationModel.Map. Microsoft.Maui.ApplicationModel 네임스페이스는 .NET MAUI의 global using 지시문 중 하나이므로 코드에서 컨트롤을 Microsoft.Maui.Controls.Maps.Map 사용하는 경우 사용량을 정규화 Map 하거나 사용 별칭을 사용해야 합니다.

맵 유형

속성을 Map.MapType 열거형 멤버로 MapType 설정하여 지도의 표시 스타일을 정의할 수 있습니다. MapType 열거형은 다음 멤버를 정의합니다.

• Street 는 거리 지도가 표시되도록 지정합니다.
• Satellite 는 위성 이미지가 포함된 맵이 표시되도록 지정합니다.
• Hybrid 는 거리 및 위성 데이터를 결합한 지도가 표시되도록 지정합니다.

기본적으로 속성이 Map 정의되지 않은 경우 거리 맵이 MapType 표시됩니다. MapType 또는 이 속성을 열거형 멤버 중 MapType 하나로 설정할 수 있습니다.

<maps:Map MapType="Satellite" />

해당하는 C# 코드는 다음과 같습니다.

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

지도에 특정 위치 표시

맵이 로드될 때 표시할 맵의 영역은 생성자에 인수 Map 를 MapSpan 전달하여 설정할 수 있습니다.

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

해당하는 C# 코드는 다음과 같습니다.

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

이 예제에서는 개체에 Map 의해 지정 된 영역을 보여 주는 개체를 MapSpan 만듭니다. 개체는 MapSpan 개체가 나타내는 Location 위도 및 경도를 중심으로 하며 0.01 위도 및 0.01 경도에 걸쳐 있습니다. 클래스에 Location 대한 자세한 내용은 위치 및 거리를 참조하세요. XAML에서 인수를 전달하는 방법에 대한 자세한 내용은 XAML에서 인수 전달을 참조하세요.

그 결과 지도가 표시되면 특정 위치의 중심이 되며 특정 수의 위도 및 경도에 걸쳐 있습니다.

MapSpan 개체 만들기

개체를 만드는 MapSpan 방법에는 여러 가지가 있습니다. 일반적인 방법은 생성자에 필요한 인수를 MapSpan 제공하는 것입니다. 개체로 표현되는 Location 위도 및 경도 및 위도 및 double 경도를 나타내는 값입니다 MapSpan. 클래스에 Location 대한 자세한 내용은 위치 및 거리를 참조하세요.

또는 클래스에 새 MapSpan 개체를 MapSpan 반환하는 세 가지 메서드가 있습니다.

1. ClampLatitudeMapSpan 는 메서드의 클래스 인스턴스와 동일 LongitudeDegrees 하고 해당 및 인수로 정의된 반지름을 northsouth 반환합니다.
2. FromCenterAndRadiusMapSpan 는 해당 인수와 인수로 Location 정의된 값을 반환합니다Distance.
3. WithZoomMapSpan 는 메서드의 클래스 인스턴스와 중심이 같지만 반경에는 인수 double 를 곱한 값을 반환합니다.

구조체에 Distance 대한 자세한 내용은 위치 및 거리를 참조하세요.

만든 MapSpan 후에는 다음 속성에 액세스하여 해당 데이터를 검색할 수 있습니다.

• Center의 지리적 중심에 있는 위치를 나타내는 형식 Location의 MapSpan.
• LatitudeDegrees에 의해 확장되는 위도의 정도를 나타내는 형식 double의 MapSpan/a0>입니다.
• LongitudeDegrees에 의해 MapSpan스팬되는 경도의 정도를 나타내는 형식double의
• Radius- 반경을 나타내는 형식 Distance입니다 MapSpan .

맵 이동

메서드를 Map.MoveToRegion 호출하여 지도의 위치 및 확대/축소 수준을 변경할 수 있습니다. 이 메서드는 MapSpan 표시할 지도의 영역과 확대/축소 수준을 정의하는 인수를 허용합니다.

다음 코드는 지도에서 표시된 지역을 이동하는 예제를 보여줍니다.

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

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

지도 확대/축소

위치를 변경하지 않고 확대 Map /축소 수준을 변경할 수 있습니다. 이 작업은 맵 UI를 사용하거나 현재 위치를 인수로 Location 사용하는 인수를 사용하여 메서드를 MapSpan 호출 MoveToRegion 하여 프로그래밍 방식으로 수행할 수 있습니다.

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

이 예제 MoveToRegion 에서는 속성을 통해 Map.VisibleRegion 맵의 현재 위치를 지정하는 인수와 위도 및 경도의 각도로 확대/축소 수준을 지정하는 인수를 사용하여 메서드를 호출 MapSpan 합니다. 전체 결과는 지도의 확대/축소 수준이 변경되지만 위치는 변경되지 않습니다. 맵에서 확대/축소를 구현하는 다른 방법은 이 메서드를 MapSpan.WithZoom 사용하여 확대/축소 요소를 제어하는 것입니다.

Important

지도 UI를 통해 또는 프로그래밍 방식으로 맵을 확대하려면 속성true이 Map.IsZoomEnabled 필요합니다. 이 속성에 대한 자세한 내용은 확대/축소 사용 안 함을 참조 하세요.

지도 동작 사용자 지정

Map 일부 속성을 설정하고 이벤트를 처리하여 동작을 사용자 지정할 수 있습니다MapClicked.

참고 항목

처리기를 사용자 지정하여 추가 맵 동작 사용자 지정을 수행할 수 있습니다. 자세한 내용은 처리기를 사용하여 컨트롤 사용자 지정을 참조 하세요.

트래픽 데이터 표시

클래스는 Map 형식bool의 속성을 정의합니다IsTrafficEnabled. 기본적으로 이 속성은 false트래픽 데이터가 맵에 오버레이되지 않음을 나타냅니다. 이 속성을 설정 true하면 트래픽 데이터가 맵에 오버레이됩니다.

<maps:Map IsTrafficEnabled="true" />

해당하는 C# 코드는 다음과 같습니다.

Map map = new Map
{
    IsTrafficEnabled = true
};

스크롤 사용 안 함

클래스는 Map 형식bool의 속성을 정의합니다IsScrollEnabled. 기본적으로 이 속성은 true맵을 스크롤할 수 있음을 나타냅니다. 이 속성을 설정 false하면 맵이 스크롤되지 않습니다.

<maps:Map IsScrollEnabled="false" />

해당하는 C# 코드는 다음과 같습니다.

Map map = new Map
{
    IsScrollEnabled = false
};

확대/축소 사용 안 함

클래스는 Map 형식bool의 속성을 정의합니다IsZoomEnabled. 기본적으로 이 속성은 true지도에서 확대/축소를 수행할 수 있음을 나타냅니다. 이 속성을 설정 false하면 맵을 확대/축소할 수 없습니다.

<maps:Map IsZoomEnabled="false" />

해당하는 C# 코드는 다음과 같습니다.

Map map = new Map
{
    IsZoomEnabled = false
};

사용자의 위치 표시

클래스는 Map 형식bool의 속성을 정의합니다IsShowingUser. 기본적으로 이 속성은 false맵에 사용자의 현재 위치가 표시되지 않음을 나타냅니다. 이 속성을 설정 true하면 맵에 사용자의 현재 위치가 표시됩니다.

<maps:Map IsShowingUser="true" />

해당하는 C# 코드는 다음과 같습니다.

Map map = new Map
{
    IsShowingUser = true
};

Important

사용자의 위치에 액세스하려면 애플리케이션에 위치 권한이 부여되어야 합니다. 자세한 내용은 플랫폼 구성을 참조하세요.

맵 클릭

클래스는 Map 맵을 MapClicked 탭할 때 발생하는 이벤트를 정의합니다. MapClickedEventArgs 이벤트와 함께 제공되는 개체에는 형식Location의 단일 속성이 있습니다Location. 이벤트가 발생하면 Location 속성이 탭된 지도 위치로 설정됩니다. 클래스에 Location 대한 자세한 내용은 위치 및 거리를 참조하세요.

다음 코드 예제에서는 이벤트에 대한 MapClicked 이벤트 처리기를 보여줍니다.

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

이 예제 OnMapClicked 에서 이벤트 처리기는 탭된 맵 위치를 나타내는 위도 및 경도를 출력합니다. 이벤트 처리기를 이벤트에 등록 MapClicked 해야 합니다.

<maps:Map MapClicked="OnMapClicked" />

해당하는 C# 코드는 다음과 같습니다.

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

위치 및 거리

네임스페이스에 Location 는 Microsoft.Maui.Devices.Sensors 맵 및 해당 핀을 배치할 때 일반적으로 사용되는 클래스가 포함되어 있습니다. 네임스페이스에는 Microsoft.Maui.Maps 맵을 Distance 배치할 때 선택적으로 사용할 수 있는 구조체가 포함되어 있습니다.

위치

클래스는 Location 위도 및 경도 값으로 저장된 위치를 캡슐화합니다. 이 클래스는 다음과 같은 속성을 정의합니다.

• Accuracy의 수평 정확도를 나타내는 형식 double?(미터)입니다 Location.
• Altitude- 속성에 지정된 AltitudeReferenceSystem 참조 시스템의 고도(미터)를 나타내는 형식double?입니다.
• AltitudeReferenceSystem- 고도 값이 제공되는 참조 시스템을 지정하는 형식 AltitudeReferenceSystem입니다.
• Course- true 북쪽을 기준으로 하는 각도 값을 나타내는 형식 double?입니다.
• IsFromMockProvider위치가 GPS 또는 모의 위치 공급자에서 온 것인지 여부를 나타내는 형식 bool의 입니다.
• Latitude- 위치의 위도를 10진수 단위로 나타내는 형식 double의 입니다.
• Longitude위치의 경도를 10진수로 나타내는 형식 double의 입니다.
• Speed- 초당 미터 단위의 속도를 나타내는 형식 double?입니다.
• Timestamp- 생성되었을 때 타임스탬프를 나타내는 형식 DateTimeOffset입니다 Location .
• VerticalAccuracy- 미터 단위의 세로 정확도를 지정하는 형식 double?의 Location/>입니다.

Location 개체는 생성자 오버로드 중 Location 하나를 사용하여 생성되며, 일반적으로 값으로 double 지정된 최소 위도 및 경도 인수가 필요합니다.

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

개체를 Location 만들 때 위도 값은 -90.0에서 90.0 사이로 고정되고 경도 값은 -180.0에서 180.0 사이로 고정됩니다.

참고 항목

클래스에는 GeographyUtilsToRadians 값을 도에서 라디안으로 변환 double 하는 확장 메서드와 ToDegrees 값을 라디안에서 도로 변환 double 하는 확장 메서드가 있습니다.

클래스에는 LocationCalculateDistance 두 위치 사이의 거리를 계산하는 메서드도 있습니다.

거리

구조체는 Distance 거리(미터)를 나타내는 값으로 double 저장된 거리를 캡슐화합니다. 이 구조체는 세 가지 읽기 전용 속성을 정의합니다.

• Kilometers에 의해 Distance스패닝되는 킬로미터의 거리를 나타내는 형식double의
• Meters에 의해 스팬되는 미터 단위의 거리를 나타내는 형식 double의 Distance입니다.
• Miles에 의해 스팬되는 마일 단위의 거리를 나타내는 형식 double의 Distance입니다.

Distance 개체는 생성자를 사용하여 Distance 만들 수 있으며, 다음으로 지정된 미터 인수가 double필요합니다.

Distance distance = new Distance(1450.5);

Distance 또는 , FromMeters및 FromMilesBetweenPositions 팩터리 메서드를 FromKilometers사용하여 개체를 만들 수 있습니다.

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

핀

컨트롤 Map 을 사용하면 위치를 개체로 Pin 표시할 수 있습니다. A Pin 는 탭할 때 정보 창을 여는 지도 표식입니다.

개체가 Pin 컬렉션에 Map.Pins 추가되면 핀이 지도에 렌더링됩니다.

클래스에는 Pin 다음과 같은 속성이 있습니다.

• Address- 일반적으로 핀 위치의 주소를 나타내는 형식 string입니다. 그러나 주소뿐만 아니라 모든 string 콘텐츠일 수 있습니다.
• Label일반적으로 핀 제목을 나타내는 형식 string의 입니다.
• Location- 핀의 위도 및 경도를 나타내는 형식 Location입니다.
• Type- 핀의 형식을 나타내는 형식 PinType입니다.

이러한 속성은 개체에 의해 BindableProperty 지원됩니다. 즉 Pin , 데이터 바인딩의 대상이 될 수 있습니다. 데이터 바인딩 Pin 개체에 대한 자세한 내용은 핀 컬렉션 표시를 참조 하세요.

또한 클래스는 Pin 정의 및 InfoWindowClicked 이벤트를 정의합니다MarkerClicked. 이벤트는 MarkerClicked 핀을 탭할 때 발생하며 InfoWindowClicked 정보 창을 탭할 때 이벤트가 발생합니다. PinClickedEventArgs 두 이벤트를 함께 사용하는 개체에는 형식bool의 단일 HideInfoWindow 속성이 있습니다.

핀 표시

XAML에서 A Pin 를 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: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은 개체에 Map 의해 지정된 영역을 보여 주는 개체를 MapSpan 만듭니다. 개체는 MapSpan 0.01 위도 및 경도도를 확장하는 개체가 Location 나타내는 위도 및 경도를 중심으로 합니다. Pin 개체가 컬렉션에 Map.Pins 추가되고 해당 속성으로 지정된 Location 위치에 그려집니다Map. 클래스에 Location 대한 자세한 내용은 위치 및 거리를 참조하세요. 기본 생성자가 없는 개체에 XAML의 인수를 전달하는 방법에 대한 자세한 내용은 XAML에서 인수 전달을 참조하세요.

해당하는 C# 코드는 다음과 같습니다.

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

이 예제 코드는 맵에서 단일 핀이 렌더링됩니다.

핀과 상호 작용

기본적으로 Pin 탭하면 정보 창이 표시됩니다.

지도의 다른 곳을 탭하면 정보 창이 닫힙니다.

클래스는 Pin 이벤트를 정의합니다 MarkerClicked . 이 이벤트는 탭될 때 Pin 발생합니다. 정보 창을 표시하기 위해 이 이벤트를 처리할 필요는 없습니다. 대신 특정 핀을 탭했다는 알림을 받아야 하는 요구 사항이 있을 때 이 이벤트를 처리해야 합니다.

또한 이 클래스는 Pin 정보 창을 탭할 때 발생하는 이벤트를 정의 InfoWindowClicked 합니다. 특정 정보 창을 탭했다는 알림을 받아야 하는 요구 사항이 있는 경우 이 이벤트를 처리해야 합니다.

다음 코드는 이러한 이벤트를 처리하는 예제를 보여 줍니다.

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

PinClickedEventArgs 두 이벤트를 함께 사용하는 개체에는 형식bool의 단일 HideInfoWindow 속성이 있습니다. 이 속성이 이벤트 처리기 내부로 true 설정되면 정보 창이 숨겨집니다.

고정 형식

Pin개체에는 핀 유형을 나타내는 형식PinType의 속성이 포함 Type 됩니다. PinType 열거형은 다음 멤버를 정의합니다.

• Generic제네릭 핀을 나타냅니다.
• Place은 장소의 핀을 나타냅니다.
• SavedPin는 저장된 위치에 대한 핀을 나타냅니다.
• SearchResult는 검색 결과의 핀을 나타냅니다.

그러나 속성을 멤버로 Pin.TypePinType 설정해도 렌더링된 핀의 모양은 변경되지 않습니다. 대신 핀 모양을 사용자 지정하려면 처리기를 사용자 지정 Pin 해야 합니다. 처리기 사용자 지정에 대한 자세한 내용은 처리기를 사용하여 컨트롤 사용자 지정을 참조 하세요.

고정 컬렉션 표시

클래스는 Map 다음 바인딩 가능한 속성을 정의합니다.

• ItemsSource- 표시할 핀 항목의 컬렉션을 지정하는 형식 IEnumerable입니다 IEnumerable .
• ItemTemplate- 표시된 핀 컬렉션의 각 항목에 적용할 항목을 지정 DataTemplate 하는 형식DataTemplate입니다.
• ItemTemplateSelector- DataTemplateSelector런타임에 핀을 DataTemplateSelector 선택하는 DataTemplate 데 사용할 형식을 지정합니다.

Important

속성과 ItemTemplateItemTemplateSelector 속성이 모두 설정되면 속성이 ItemTemplate 우선합니다.

A Map 는 데이터 바인딩을 사용하여 해당 ItemsSource 속성을 컬렉션에 바인딩하여 핀으로 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 속성 데이터는 연결된 viewmodel의 속성에 바인딩 Positions 됩니다. 이 속성은 사용자 지정 형식인 ObservableCollection 개체를 Position 반환합니다. 각 Position 개체는 Address 형식의 속성과 Description 형식string의 속성을 Location정의합니다Location.

컬렉션에서 IEnumerable 각 항목의 모양은 데이터가 적절한 속성 DataTemplate 에 바인딩하는 개체를 포함하는 Pin 속성으로 설정 ItemTemplate 하여 정의됩니다.

다음 스크린샷은 데이터 바인딩을 Pin 사용하여 컬렉션을 표시하는 것을 보여줍니다Map.

런타임에 항목 모양 선택

속성을 다음으로 설정 ItemTemplateSelectorDataTemplateSelector하여 런타임에 컬렉션에 있는 IEnumerable 각 항목의 모양을 항목 값에 따라 선택할 수 있습니다.

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

다음 예제에서는 클래스를 보여줍니다.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;
    }
}

클래스는 MapItemTemplateSelectorDefaultTemplateSanFranTemplateDataTemplate 다른 데이터 템플릿으로 설정된 속성을 정의합니다. 메서드는 OnSelectTemplate 항목에 SanFranTemplate"San Francisco"가 포함된 주소가 있을 때 Pin "Xamarin"을 탭할 때 레이블로 표시하는 "Xamarin"을 반환합니다. 항목에 "San Francisco"가 포함된 주소가 없으면 메서드가 OnSelectTemplate 반환됩니다 DefaultTemplate.

참고 항목

이 기능의 사용 사례는 하위 형식에 따라 서브클래스된 Pin 개체의 속성을 다른 속성에 바인딩하는 Pin 것입니다.

데이터 템플릿 선택기에 대한 자세한 내용은 DataTemplateSelector 만들기를 참조하세요.

다각형, 다각형 및 원

Polygon, Polyline및 Circle 요소를 사용하면 지도의 특정 영역을 강조 표시할 수 있습니다. A Polygon 는 스트로크와 채우기 색을 가질 수 있는 완전히 묶인 도형입니다. A Polyline 는 영역을 완전히 묶지 않는 선입니다. 지도 Circle 의 원형 영역을 강조 표시합니다.

, Polyline및 Circle 클래스는 Polygon다음 바인딩 가능한 속성을 노출하는 클래스에서 MapElement 파생됩니다.

• StrokeColor 는 Color 선 색을 결정하는 개체입니다.
• StrokeWidth 는 float 선 너비를 결정하는 개체입니다.

클래스는 Polygon 추가 바인딩 가능한 속성을 정의합니다.

• FillColor 는 Color 다각형의 배경색을 결정하는 개체입니다.

또한 Polygon 클래스와 Polyline 클래스는 셰이프의 Location 점을 지정하는 개체 목록인 속성을 정의 GeoPath 합니다.

클래스는 Circle 다음 바인딩 가능한 속성을 정의합니다.

• CenterLocation 는 위도 및 경도로 원의 중심을 정의하는 개체입니다.
• RadiusDistance 는 원의 반경을 미터, 킬로미터 또는 마일 단위로 정의하는 개체입니다.
• FillColor 는 Color 원 경계 내의 색을 결정하는 속성입니다.

다각형 만들기

Polygon 개체를 인스턴스화하고 맵의 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>

해당하는 C# 코드는 다음과 같습니다.

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

Map map = new Map();

// Instantiate a polygon
Polygon polygon = new Polygon
{
    StrokeWidth = 8,
    StrokeColor = Color.FromArgb("#1BA1E2"),
    FillColor = Color.FromArgb("#881BA1E2"),
    Geopath =
    {
        new Location(47.6368678, -122.137305),
        new Location(47.6368894, -122.134655),
        ...
    }
};

// Add the polygon to the map's MapElements collection
map.MapElements.Add(polygon);

StrokeColor 및 StrokeWidth 속성은 다각형의 윤곽선을 설정하도록 지정됩니다. 이 예제 FillColor 에서 속성 값은 속성 값과 일치 StrokeColor 하지만 투명하게 지정한 알파 값을 사용하여 셰이프를 통해 기본 맵을 볼 수 있습니다. 이 속성에는 GeoPath 다각형 점의 Location 지리적 좌표를 정의하는 개체 목록이 포함되어 있습니다. Polygon 개체가 컬렉션Map에 추가되면 맵에서 MapElements 렌더링됩니다.

참고 항목

A Polygon 는 완전히 묶인 도형입니다. 첫 번째 점과 마지막 지점이 일치하지 않으면 자동으로 연결됩니다.

폴리라인 만들기

Polyline 개체를 인스턴스화하고 맵의 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>

해당하는 C# 코드는 다음과 같습니다.

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

StrokeColor 및 StrokeWidth 속성은 선 모양을 설정하도록 지정됩니다. 이 속성에는 GeoPath 폴리라인 점의 Location 지리적 좌표를 정의하는 개체 목록이 포함되어 있습니다. Polyline 개체가 컬렉션Map에 추가되면 맵에서 MapElements 렌더링됩니다.

원 만들기

Circle 개체를 인스턴스화하고 맵의 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>

해당하는 C# 코드는 다음과 같습니다.

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

지도의 Circle 위치는 속성 및 Radius 값에 Center 따라 결정됩니다. 이 속성은 Center 원의 중심을 위도 및 경도로 정의하고 속성은 Radius 원의 반지름을 미터로 정의합니다. StrokeColor 및 StrokeWidth 속성은 원의 윤곽선을 설정하도록 지정됩니다. 속성 값은 FillColor 원 경계 내의 색을 지정합니다. 이 예제에서 두 색 값은 모두 알파 채널을 지정하여 원을 통해 기본 맵을 볼 수 있도록 합니다. Circle 개체가 컬렉션Map에 추가되면 맵에서 MapElements 렌더링됩니다.

참고 항목

클래스에는 GeographyUtilsToCircumferencePositions 개체(정의 Center 및 속성 값)를 원 경계의 Location 위도 및 Radius 경도 좌표를 구성하는 개체 목록으로 변환 Circle 하는 확장 메서드가 있습니다.

지오코딩 및 지리적 위치

네임스페이 Microsoft.Maui.Devices.Sensors 스에서 클래스를 Geocoding 사용하여 위치 좌표로 자리 표시를 지오코딩하고 지오코드 좌표를 자리 표시로 역방향으로 지정할 수 있습니다. 자세한 내용은 지오코딩을 참조 하세요.

Geolocation 네임스페이 Microsoft.Maui.Devices.Sensors 스의 클래스를 사용하여 디바이스의 현재 지리적 위치 좌표를 검색할 수 있습니다. 자세한 내용은 지리적 위치를 참조 하세요.

네이티브 맵 앱 시작

클래스에서 .NET MAUI 앱에서 각 플랫폼의 Launcher 네이티브 맵 앱을 시작할 수 있습니다. 이 클래스를 사용하면 앱이 사용자 지정 URI 체계를 통해 다른 앱을 열 수 있습니다. 시작 관리자 기능은 열려는 사용자 지정 URL 체계를 나타내는 인수 또는 Uri 인수를 string 전달하여 메서드를 사용하여 호출 OpenAsync 할 수 있습니다. 클래스에 대한 Launcher 자세한 내용은 시작 관리자 참조하세요.

참고 항목

클래스를 사용하는 Launcher 대신 네임스페이스의 클래스를 사용하는 Map 것이 Microsoft.Maui.ApplicationModel 좋습니다. 자세한 내용은 맵을 참조하세요.

각 플랫폼의 지도 앱은 고유한 사용자 지정 URI 체계를 사용합니다. iOS의 지도 URI 체계에 대한 자세한 내용은 developer.apple.com 지도 링크를 참조하세요. Android의 지도 URI 체계에 대한 자세한 내용은 지도 개발자 가이드 및 developers.android.com Android용 Google 지도 의도를 참조하세요. Windows의 지도 URI 스키마에 대한 자세한 내용은 Windows 지도 앱 시작을 참조하세요.

특정 위치에서 지도 앱 시작

네이티브 맵 앱의 위치는 각 지도 앱에 대한 사용자 지정 URI 체계에 적절한 쿼리 매개 변수를 추가하여 열 수 있습니다.

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

이 예제 코드는 네이티브 맵 앱이 각 플랫폼에서 시작되고 지정된 위치를 나타내는 핀 가운데에 지도가 배치됩니다.

지침에 따라 지도 앱 시작

각 지도 앱에 대한 사용자 지정 URI 체계에 적절한 쿼리 매개 변수를 추가하여 방향을 표시하는 네이티브 맵 앱을 시작할 수 있습니다.

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

이 예제 코드는 각 플랫폼에서 네이티브 맵 앱이 시작되고 지도는 지정된 위치 사이의 경로를 중심으로 시작됩니다.