.NET MAUI Shell 탐색

아티클
10/08/2024

.NET MAUI(.NET 다중 플랫폼 앱 UI) Shell에는 설정된 탐색 계층 구조를 따르지 않고도 경로를 사용하여 앱의 모든 페이지로 이동하는 URI 기반 탐색 환경이 포함되어 있습니다. 또한 탐색 스택의 모든 페이지를 방문하지 않고도 뒤로 이동할 수 있는 기능을 제공합니다.

Shell 클래스는 다음과 같은 탐색 관련 속성을 정의합니다.

BackButtonBehavior 형식의 BackButtonBehavior - [뒤로] 단추의 동작을 정의하는 연결된 속성입니다.
ShellItem 형식의 CurrentItem - 현재 선택된 항목입니다.
Page 형식의 CurrentPage - 현재 표시된 페이지입니다.
ShellNavigationState 형식의 CurrentState - Shell의 현재 탐색 상태입니다.
Shell 형식의 Current - Application.Current.MainPage의 형식 캐스팅된 별칭입니다.

BackButtonBehavior, CurrentItem, CurrentState 속성은 BindableProperty 개체에서 지원되며 이러한 속성이 데이터 바인딩의 대상일 수 있음을 의미합니다.

Shell 클래스에서 GoToAsync 메서드를 호출하여 탐색을 수행합니다. 탐색을 수행하려고 하면 Navigating 이벤트가 발생하고 탐색이 완료되면 Navigated 이벤트가 발생합니다.

참고 항목

속성을 사용하여 셸 앱의 페이지 간에 탐색을 Navigation 계속 수행할 수 있습니다. 자세한 내용은 모덜리스 탐색 수행을 참조 하세요.

경로

탐색은 탐색할 URI를 지정하여 Shell 앱에서 수행됩니다. 탐색 URI에는 세 가지 구성 요소가 포함될 수 있습니다.

경로 - 셸 시각적 계층 구조의 일부로 존재하는 콘텐츠의 경로를 정의합니다.
페이지. Shell 시각적 계층 구조에 없는 페이지는 Shell 앱 내의 어디에서나 탐색 스택으로 푸시할 수 있습니다. 예를 들어 세부 정보 페이지는 Shell 시각적 계층 구조에 정의되지 않지만, 필요에 따라 탐색 스택으로 푸시할 수 있습니다.
하나 이상의 쿼리 매개 변수. 쿼리 매개 변수는 탐색하는 동안 대상 페이지에 전달할 수 있는 매개 변수입니다.

탐색 URI에 세 가지 구성 요소가 모두 포함되는 경우 구조체는 //route/page?queryParameters입니다.

경로 등록

경로는 FlyoutItem, TabBar, Tab 및 ShellContent 개체에서 해당 Route 속성을 통해 정의할 수 있습니다.

<Shell ...>
    <FlyoutItem ...
                Route="animals">
        <Tab ...
             Route="domestic">
            <ShellContent ...
                          Route="cats" />
            <ShellContent ...
                          Route="dogs" />
        </Tab>
        <ShellContent ...
                      Route="monkeys" />
        <ShellContent ...
                      Route="elephants" />  
        <ShellContent ...
                      Route="bears" />
    </FlyoutItem>
    <ShellContent ...
                  Route="about" />                  
    ...
</Shell>

참고 항목

셸 계층 구조의 모든 항목에는 연결된 경로가 있습니다. 경로를 설정하지 않으면 런타임에 생성됩니다. 그러나 생성된 경로가 서로 다른 앱 세션에서 일관성을 보장하지는 않습니다.

위 예제에서는 프로그래밍 방식 탐색에 사용할 수 있는 다음 경로 계층 구조를 만듭니다.

animals
  domestic
    cats
    dogs
  monkeys
  elephants
  bears
about

dogs 경로의 ShellContent 개체로 이동하려면 절대 경로 URI는 //animals/domestic/dogs입니다. 마찬가지로, about 경로의 ShellContent 개체로 이동하려면 절대 경로 URI는 //about입니다.

Warning

ArgumentException 중복 경로가 검색되면 앱 시작 시 throw됩니다. 이 예외는 계층 구조의 동일한 수준에 있는 두 개 이상의 경로가 경로 이름을 공유하는 경우에도 throw됩니다.

세부 정보 페이지 경로 등록

Shell 서브클래스 생성자 또는 경로가 호출되기 전에 실행되는 다른 위치에서는 Shell 시각적 계층 구조에 표시되지 않는 모든 세부 정보 페이지에 대해 추가 경로를 명시적으로 등록할 수 있습니다. 이렇게 하려면 Routing.RegisterRoute 메서드를 사용합니다.

Routing.RegisterRoute("monkeydetails", typeof(MonkeyDetailPage));
Routing.RegisterRoute("beardetails", typeof(BearDetailPage));
Routing.RegisterRoute("catdetails", typeof(CatDetailPage));
Routing.RegisterRoute("dogdetails", typeof(DogDetailPage));
Routing.RegisterRoute("elephantdetails", typeof(ElephantDetailPage));

이 예제에서는 Shell 서브클래스에 정의되지 않은 세부 정보 페이지를 경로로 등록합니다. 그런 다음 이러한 세부 정보 페이지를 앱 내의 어디에서나 URI 기반 탐색을 사용하여 탐색할 수 있습니다. 이러한 페이지의 경로를 전역 경로라고 합니다.

Warning

Routing.RegisterRoute 메서드가 둘 이상의 다른 형식에 대해 동일한 경로를 등록하려고 하면 ArgumentException이 throw됩니다.

또는 필요한 경우 다른 경로 계층 구조에서 페이지를 등록할 수 있습니다.

Routing.RegisterRoute("monkeys/details", typeof(MonkeyDetailPage));
Routing.RegisterRoute("bears/details", typeof(BearDetailPage));
Routing.RegisterRoute("cats/details", typeof(CatDetailPage));
Routing.RegisterRoute("dogs/details", typeof(DogDetailPage));
Routing.RegisterRoute("elephants/details", typeof(ElephantDetailPage));

이 예제에서는 monkeys 경로에 대한 페이지에서 details 경로로 이동하면 MonkeyDetailPage가 표시되는 상황별 페이지 탐색을 사용하도록 설정합니다. 마찬가지로, elephants 경로에 대한 페이지에서 details 경로로 이동하면 ElephantDetailPage가 표시됩니다. 자세한 내용은 상황별 탐색을 참조하세요.

참고 항목

Routing.RegisterRoute 메서드를 사용하여 경로를 등록한 페이지는 필요한 경우 Routing.UnRegisterRoute 메서드를 사용하여 등록을 취소할 수 있습니다.

탐색을 수행하려면 먼저 Shell 서브클래스에 대한 참조를 가져와야 합니다. 이 참조는 App.Current.MainPage 속성을 Shell 개체에 캐스팅하거나 Shell.Current 속성을 통해 가져올 수 있습니다. 그런 다음 Shell 개체에서 GoToAsync 메서드를 호출하여 탐색을 수행할 수 있습니다. 이 메서드는 ShellNavigationState로 이동하여 탐색 애니메이션이 완료된 후 완료될 Task를 반환합니다. ShellNavigationState 개체는 string 또는 Uri에서 GoToAsync 메서드를 통해 생성되고 해당 Location 속성이 string 또는 Uri 인수로 설정되어 있습니다.

Important

셸 시각적 계층 구조의 경로로 이동하면 탐색 스택이 생성되지 않습니다. 그러나 셸 시각적 계층 구조에 없는 페이지로 이동하면 탐색 스택이 생성됩니다.

Shell 개체의 현재 탐색 상태는 표시된 경로의 URI를 Location 속성에 포함하는 Shell.Current.CurrentState 속성을 통해 검색할 수 있습니다.

절대 경로

유효한 절대 URI를 GoToAsync 메서드의 인수로 지정하여 탐색을 수행할 수 있습니다.

await Shell.Current.GoToAsync("//animals/monkeys");

이 예제에서는 monkeys 경로에 대한 페이지로 이동하며 경로는 ShellContent 개체에 정의됩니다. monkeys 경로를 나타내는 ShellContent 개체는 경로가 animals인 FlyoutItem 개체의 자식입니다.

상대 경로

유효한 상대 URI를 GoToAsync 메서드의 인수로 지정하여 탐색을 수행할 수도 있습니다. 라우팅 시스템은 URI를 ShellContent 개체와 일치시키려고 합니다. 따라서 앱의 모든 경로가 고유한 경우 고유한 경로 이름을 상대 URI로 지정하여 탐색을 수행할 수 있습니다.

다음 상대 경로 형식이 지원됩니다.

서식	설명
route	지정된 경로에 대한 경로 계층 구조가 현재 위치에서 위쪽으로 검색됩니다. 일치하는 페이지가 탐색 스택에 푸시됩니다.
/route	지정된 경로에서 경로 계층 구조가 현재 위치에서 아래쪽으로 검색됩니다. 일치하는 페이지가 탐색 스택에 푸시됩니다.
//route	지정된 경로에 대한 경로 계층 구조가 현재 위치에서 위쪽으로 검색됩니다. 일치하는 페이지가 탐색 스택을 대체합니다.
///route	지정된 경로에 대한 경로 계층 구조가 현재 위치에서 아래쪽으로 검색됩니다. 일치하는 페이지가 탐색 스택을 대체합니다.

다음 예제에서는 monkeydetails 경로에 대한 페이지로 이동합니다.

await Shell.Current.GoToAsync("monkeydetails");

이 예제에서는 일치 페이지가 발견될 때까지 monkeyDetails 경로가 계층 구조 위쪽으로 검색됩니다. 찾은 페이지는 탐색 스택에 푸시됩니다.

상대 경로를 사용하여 상황별 탐색을 수행할 수 있습니다. 예를 들어 다음 경로 계층 구조를 고려합니다.

monkeys
  details
bears
  details

monkeys 경로의 등록된 페이지가 표시될 때 details 경로로 이동하면 monkeys/details 경로의 등록된 페이지가 표시됩니다. 마찬가지로, bears 경로의 등록된 페이지가 표시될 때 details 경로로 이동하면 bears/details 경로의 등록된 페이지가 표시됩니다. 이 예제에서 경로를 등록하는 방법에 대한 자세한 내용은 페이지 경로 등록을 참조하세요.

뒤로 탐색은 GoToAsync 메서드의 인수로 ".."를 지정하여 수행할 수 있습니다.

await Shell.Current.GoToAsync("..");

“..”를 사용한 뒤로 탐색은 경로와 결합할 수도 있습니다.

await Shell.Current.GoToAsync("../route");

이 예제에서는 뒤로 탐색을 수행한 다음 지정된 경로로 이동합니다.

Important

지정된 경로로 이동하기 위해 뒤로 탐색이 경로 계층 구조의 현재 위치에 있는 경우에만 뒤로 탐색 및 지정된 경로로 탐색을 수행할 수 있습니다.

마찬가지로 여러 번 뒤로 이동한 다음, 지정된 경로로 이동할 수 있습니다.

await Shell.Current.GoToAsync("../../route");

이 예제에서는 뒤로 탐색을 두 번 수행한 다음 지정된 경로로 이동합니다.

또한 뒤로 탐색할 때 쿼리 속성을 통해 데이터를 전달할 수 있습니다.

await Shell.Current.GoToAsync($"..?parameterToPassBack={parameterValueToPassBack}");

이 예에서는 뒤로 탐색을 수행하고 쿼리 매개 변수 값을 이전 페이지의 쿼리 매개 변수에 전달합니다.

참고 항목

쿼리 매개 변수는 뒤로 탐색 요청에 추가할 수 있습니다.

탐색할 때 데이터를 전달하는 방법에 대한 자세한 내용은 데이터 전달을 참조하세요.

잘못된 경로

다음 경로 형식은 유효하지 않습니다.

형식	설명
//page 또는 ///page	현재는 전역 경로가 탐색 스택의 유일한 페이지가 될 수 없습니다. 따라서 전역 경로에 대한 절대 라우팅은 지원되지 않습니다.

이러한 경로 형식을 사용하면 Exception이 throw됩니다.

Warning

존재하지 않는 경로로 이동하려고 하면 ArgumentException 예외가 throw됩니다.

일부 셸 클래스는 디버거에서 클래스나 필드를 표시하는 방식을 지정하는 DebuggerDisplayAttribute로 데코레이팅됩니다. 이 특성을 사용하면 탐색 요청에 관련된 데이터를 표시하여 탐색 요청을 디버그할 수 있습니다. 예를 들어 다음 스크린샷은 Shell.Current 개체의 CurrentItem 및 CurrentState 속성을 보여 줍니다.

디버거의 스크린샷.

이 예제에서 FlyoutItem 형식의 CurrentItem 속성은 FlyoutItem 개체의 제목 및 경로를 표시합니다. 마찬가지로 CurrentState 형식 ShellNavigationState의 속성은 셸 앱 내에 표시된 경로의 URI를 표시합니다.

클래스 내에서 Tab 현재 탐색 스택Tab을 Stack 나타내는 형식IReadOnlyList<Page>의 속성을 정의 합니다. 또한 클래스는 다음과 같은 재정의 가능한 탐색 메서드를 제공합니다.

GetNavigationStack, 현재 탐색 스택을 반환 IReadOnlyList<Page>합니다.
OnInsertPageBefore - INavigation.InsertPageBefore가 호출될 때 호출됩니다.
OnPopAsync - Task<Page>를 반환하고 INavigation.PopAsync가 호출될 때 호출됩니다.
OnPopToRootAsync - Task를 반환하고 INavigation.OnPopToRootAsync가 호출될 때 호출됩니다.
OnPushAsync - Task를 반환하고 INavigation.PushAsync가 호출될 때 호출됩니다.
OnRemovePage - INavigation.RemovePage가 호출될 때 호출됩니다.

다음 예제에서는 OnRemovePage 메서드를 재정의하는 방법을 보여 줍니다.

public class MyTab : Tab
{
    protected override void OnRemovePage(Page page)
    {
        base.OnRemovePage(page);

        // Custom logic
    }
}

이 예제에서 MyTab 개체는 Shell 시각적 계층 구조에서 Tab 개체 대신 사용됩니다.

Shell 클래스는 프로그래밍 방식 탐색이나 사용자 조직으로 인해 탐색이 수행되려고 할 때 발생하는 Navigating 이벤트를 정의합니다. Navigating 이벤트와 함께 제공되는 ShellNavigatingEventArgs 개체는 다음 속성을 제공합니다.

속성	Type	설명
`Current`	`ShellNavigationState`	현재 페이지의 URI입니다.
`Source`	`ShellNavigationSource`	발생한 탐색의 형식입니다.
`Target`	`ShellNavigationState`	탐색의 목적지를 나타내는 URI입니다.
`CanCancel`	`bool`	탐색을 취소할 수 있는지 여부를 나타내는 값입니다.
`Cancelled`	`bool`	탐색이 취소되었는지를 나타내는 값입니다.

또한 ShellNavigatingEventArgs 클래스는 탐색을 취소하는 데 사용할 수 있는 Cancel 메서드와 탐색을 완료하는 데 사용할 수 있는 ShellNavigatingDeferral 토큰을 반환하는 GetDeferral 메서드를 제공합니다. 탐색 지연에 대한 자세한 내용은 탐색 지연을 참조하세요.

Shell 클래스는 탐색이 완료될 때 발생하는 Navigated 이벤트도 정의합니다. Navigated 이벤트와 함께 제공되는 ShellNavigatedEventArgs 개체는 다음 속성을 제공합니다.

속성	Type	설명
`Current`	`ShellNavigationState`	현재 페이지의 URI입니다.
`Previous`	`ShellNavigationState`	이전 페이지의 URI입니다.
`Source`	`ShellNavigationSource`	발생한 탐색의 형식입니다.

Important

OnNavigating 메서드는 Navigating 이벤트가 발생할 때 호출됩니다. 마찬가지로 OnNavigated 메서드는 Navigated 이벤트가 발생할 때 호출됩니다. 두 메서드 모두 Shell 서브클래스에서 재정의하여 탐색 요청을 가로챌 수 있습니다.

ShellNavigatedEventArgs 및 ShellNavigatingEventArgs 클래스에는 둘 다 ShellNavigationSource 형식의 Source 속성이 있습니다. 이 열거형은 다음 값을 제공합니다.

Unknown
Push
Pop
PopToRoot
Insert
Remove
ShellItemChanged
ShellSectionChanged
ShellContentChanged

따라서 OnNavigating 재정의에서 탐색을 가로채고 탐색 소스에 따라 작업을 수행할 수 있습니다. 예를 들어 다음 코드는 페이지의 데이터가 저장되지 않은 경우 역방향 탐색을 취소하는 방법을 보여 줍니다.

protected override void OnNavigating(ShellNavigatingEventArgs args)
{
    base.OnNavigating(args);

    // Cancel any back navigation.
    if (args.Source == ShellNavigationSource.Pop)
    {
        args.Cancel();
    }
}

셸 탐색은 가로챌 수 있고 사용자 선택에 따라 완료 또는 취소할 수 있습니다. 이렇게 하려면 Shell 서브클래스에서 OnNavigating 메서드를 재정의하고 ShellNavigatingEventArgs 개체에서 GetDeferral 메서드를 호출합니다. 이 메서드는 탐색 요청을 완료하는 데 사용할 수 있는 Complete 메서드가 있는 ShellNavigatingDeferral 토큰을 반환합니다.

public MyShell : Shell
{
    // ...
    protected override async void OnNavigating(ShellNavigatingEventArgs args)
    {
        base.OnNavigating(args);

        ShellNavigatingDeferral token = args.GetDeferral();

        var result = await DisplayActionSheet("Navigate?", "Cancel", "Yes", "No");
        if (result != "Yes")
        {
            args.Cancel();
        }
        token.Complete();
    }    
}

이 예제에서는 사용자에게 탐색 요청을 완료하거나 취소하라고 안내하는 작업 시트가 표시됩니다. 탐색을 취소하려면 ShellNavigatingEventArgs 개체에서 Cancel 메서드를 호출합니다. 탐색은 ShellNavigatingEventArgs 개체의 GetDeferral 메서드에 의해 검색된 ShellNavigatingDeferral 토큰에서 Complete 메서드를 호출하여 완료합니다.

Warning

GoToAsync 메서드는 보류 중인 탐색 지연이 있을 때 사용자가 탐색하려고 하면 InvalidOperationException을 throw합니다.

데이터 전달

URI 기반 프로그래밍 방식 탐색을 수행하는 경우 기본 데이터를 문자열 기반 쿼리 매개 변수로 전달할 수 있습니다. 이는 ?를 경로 뒤에 추가한 다음, 쿼리 매개 변수 ID, = 및 값을 차례로 추가하여 수행됩니다.

async void OnCollectionViewSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    string elephantName = (e.CurrentSelection.FirstOrDefault() as Animal).Name;
    await Shell.Current.GoToAsync($"elephantdetails?name={elephantName}");
}

이 예제에서는 현재 선택한 코끼리를 CollectionView검색하고 경로로 이동하여 elephantdetails 쿼리 매개 변수로 전달 elephantName 합니다.

인수를 지정 IDictionary<string, object> 하는 오버로드를 GoToAsync 사용하여 다중 사용 개체 기반 탐색 데이터를 전달할 수 있습니다.

async void OnCollectionViewSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    Animal animal = e.CurrentSelection.FirstOrDefault() as Animal;
    var navigationParameter = new Dictionary<string, object>
    {
        { "Bear", animal }
    };
    await Shell.Current.GoToAsync($"beardetails", navigationParameter);
}

다음은 현재 선택한 곰 CollectionView을 검색하는 예제입니다 Animal. 개체가 Animal 키Bear와 Dictionary 함께 추가됩니다. 그런 다음 경로에 대한 beardetails 탐색이 수행 Dictionary 되고 탐색 매개 변수로 전달됩니다.

인수로 IDictionary<string, object> 전달된 모든 데이터는 페이지의 수명 동안 메모리에 유지되며 페이지가 탐색 스택에서 제거될 때까지 해제되지 않습니다. 다음 시나리오와 같이 문제가 될 수 있습니다.

Page1 는 Page2 메서드를 사용하여 GoToAsync >라는 MyData개체를 전달합니다. Page2 는 쿼리 매개 변수로 수신됩니다 MyData .
Page2 는 Page3 데이터를 전달하지 않고 메서드를 사용하도록 GoToAsync 이동합니다.
Page3 는 메서드를 사용하여 GoToAsync 뒤로 이동합니다. Page2 는 쿼리 매개 변수로 다시 수신됩니다 MyData .

이는 많은 시나리오에서 바람직하지만 원하지 않는 경우 페이지에서 인수를 처음 받은 후 메서드를 Clear 사용하여 인수를 지워 IDictionary<string, object> 야 합니다.

인수를 지정 ShellNavigationQueryParameters 하는 오버로드를 GoToAsync 사용하여 단일 사용 개체 기반 탐색 데이터를 전달할 수 있습니다. ShellNavigationQueryParameters 개체는 탐색이 발생한 후 지워지는 단일 사용 탐색 데이터를 위한 것입니다. 다음 예제에서는 일회용 데이터를 전달하는 동안 탐색하는 방법을 보여 주며,

async void OnCollectionViewSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    Animal animal = e.CurrentSelection.FirstOrDefault() as Animal;
    var navigationParameter = new ShellNavigationQueryParameters
    {
        { "Bear", animal }
    };
    await Shell.Current.GoToAsync($"beardetails", navigationParameter);
}

이 예제에서는 개체에 추가 ShellNavigationQueryParameters 된 것으로 Animal 현재 선택된 곰CollectionView을 검색합니다. 그런 다음 개체를 beardetails 탐색 매개 변수로 ShellNavigationQueryParameters 전달하여 경로 탐색을 수행합니다. 탐색이 발생한 후 개체의 ShellNavigationQueryParameters 데이터가 지워집니다.

아래의 두 가지 방법으로 탐색 데이터를 수신할 수 있습니다.

탐색 중인 페이지를 나타내는 클래스 또는 페이지의 BindingContext에 대한 클래스를 각 쿼리 매개 변수에 대해 QueryPropertyAttribute로 데코레이트할 수 있습니다. 자세한 내용은 쿼리 속성 특성을 사용하여 탐색 데이터 처리를 참조하세요.
탐색 중인 페이지를 나타내는 클래스 또는 페이지의 BindingContext에 대한 클래스는 IQueryAttributable 인터페이스를 구현할 수 있습니다. 자세한 내용은 단일 메서드를 사용하여 탐색 데이터 처리를 참조하세요.

각 문자열 기반 쿼리 매개 변수, 개체 기반 탐색 매개 변수 또는 ShellNavigationQueryParameters 개체에 대해 수신 클래스를 QueryPropertyAttribute 데코레이팅하여 탐색 데이터를 받을 수 있습니다.

[QueryProperty(nameof(Bear), "Bear")]
public partial class BearDetailPage : ContentPage
{
    Animal bear;
    public Animal Bear
    {
        get => bear;
        set
        {
            bear = value;
            OnPropertyChanged();
        }
    }

    public BearDetailPage()
    {
        InitializeComponent();
        BindingContext = this;
    }
}

이 예제에서 첫 번째 인수는 QueryPropertyAttribute 데이터를 받을 속성의 이름을 지정하고 두 번째 인수는 매개 변수 ID를 지정합니다. 따라서 QueryPropertyAttribute 위의 예제에서는 속성이 메서드 호출의 Bear 탐색 매개 변수 GoToAsync 에 Bear 전달된 데이터를 받도록 지정합니다.

Important

이 값을 통해 QueryPropertyAttribute 수신되는 문자열 기반 쿼리 매개 변수 값은 자동으로 URL 디코딩됩니다.

Warning

이 옵션을 사용하여 QueryPropertyAttribute 탐색 데이터를 수신하는 것은 안전하지 않으며 전체 트리밍 또는 NativeAOT와 함께 사용하면 안 됩니다. 대신 쿼리 매개 변수를 IQueryAttributable 수락해야 하는 형식에 대한 인터페이스를 구현해야 합니다. 자세한 내용은 단일 메서드를 사용하여 탐색 데이터 처리, .NET MAUI 앱 트리밍 및 네이티브 AOT 배포를 참조하세요.

수신 클래스에서 IQueryAttributable 인터페이스를 구현하여 탐색 데이터를 받을 수 있습니다. IQueryAttributable 인터페이스는 구현하는 클래스가 ApplyQueryAttributes 메서드를 구현하도록 지정합니다. 이 메서드에는 탐색 중에 전달된 데이터를 포함하는 IDictionary<string, object> 형식의 query 인수가 있습니다. 사전의 각 키는 데이터를 나타내는 개체에 해당하는 값을 가진 쿼리 매개 변수 ID입니다. 이 접근 방식을 사용하는 경우의 이점은 단일 메서드를 사용하여 탐색 데이터를 처리할 수 있다는 것입니다. 이는 일률적으로 처리해야 하는 여러 개의 탐색 데이터 항목이 있는 경우에 유용할 수 있습니다.

다음 예제는 IQueryAttributable 인터페이스를 구현하는 뷰 모델 클래스를 보여 줍니다.

public class MonkeyDetailViewModel : IQueryAttributable, INotifyPropertyChanged
{
    public Animal Monkey { get; private set; }

    public void ApplyQueryAttributes(IDictionary<string, object> query)
    {
        Monkey = query["Monkey"] as Animal;
        OnPropertyChanged("Monkey");
    }
    ...
}

이 예제에서 메서드는 ApplyQueryAttributes 메서드 호출에 Monkey 인수로 전달된 사전의 query 키에 해당하는 개체를 GoToAsync 검색합니다.

Important

인터페이스를 통해 IQueryAttributable 수신되는 문자열 기반 쿼리 매개 변수 값은 자동으로 URL 디코딩되지 않습니다.

여러 데이터 항목 전달 및 처리

여러 문자열 기반 쿼리 매개 변수를 .에 연결하여 &전달할 수 있습니다. 예를 들어 다음 코드는 두 데이터 항목을 전달합니다.

async void OnCollectionViewSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    string elephantName = (e.CurrentSelection.FirstOrDefault() as Animal).Name;
    string elephantLocation = (e.CurrentSelection.FirstOrDefault() as Animal).Location;
    await Shell.Current.GoToAsync($"elephantdetails?name={elephantName}&location={elephantLocation}");
}

이 코드 예제는 CollectionView에서 현재 선택된 코끼리를 검색하고 elephantdetails 경로로 이동하여 elephantName 및 elephantLocation을 쿼리 매개 변수로 전달합니다.

여러 데이터 항목을 받으려면 탐색 중인 페이지를 나타내는 클래스 또는 페이지의 BindingContext클래스를 각 문자열 기반 쿼리 매개 변수에 대해 데코레이팅 QueryPropertyAttribute 할 수 있습니다.

[QueryProperty(nameof(Name), "name")]
[QueryProperty(nameof(Location), "location")]
public partial class ElephantDetailPage : ContentPage
{
    public string Name
    {
        set
        {
            // Custom logic
        }
    }

    public string Location
    {
        set
        {
            // Custom logic
        }
    }
    ...    
}

이 예제에서 클래스는 각 쿼리 매개 변수에 대해 QueryPropertyAttribute로 데코레이트됩니다. 첫 번째 QueryPropertyAttribute는 Name 속성이 name 쿼리 매개 변수에 전달된 데이터를 수신하도록 지정하고 두 번째 QueryPropertyAttribute는 Location 속성이 location 쿼리 매개 변수에 전달된 데이터를 수신하도록 지정합니다. 두 경우 모두 쿼리 매개 변수 값은 GoToAsync 메서드 호출의 URI에 지정됩니다.

Warning

이 옵션을 사용하여 QueryPropertyAttribute 탐색 데이터를 수신하는 것은 안전하지 않으며 전체 트리밍 또는 NativeAOT와 함께 사용하면 안 됩니다. 대신 쿼리 매개 변수를 IQueryAttributable 수락해야 하는 형식에 대한 인터페이스를 구현해야 합니다. 자세한 내용은 .NET MAUI 앱 및 네이티브 AOT 배포 트리밍을 참조하세요.

또는 탐색 중인 페이지를 나타내는 클래스 또는 페이지의 BindingContext에 대한 클래스에서 IQueryAttributable 인터페이스를 구현함으로써 단일 메서드로 탐색 데이터를 처리할 수 있습니다.

public class ElephantDetailViewModel : IQueryAttributable, INotifyPropertyChanged
{
    public Animal Elephant { get; private set; }

    public void ApplyQueryAttributes(IDictionary<string, object> query)
    {
        string name = HttpUtility.UrlDecode(query["name"].ToString());
        string location = HttpUtility.UrlDecode(query["location"].ToString());
        ...        
    }
    ...
}

이 예제에서 ApplyQueryAttributes 메서드는 GoToAsync 메서드 호출의 URI에서 name 및 location 쿼리 매개 변수의 값을 검색합니다.

참고 항목

경로 기반 탐색을 수행할 때 문자열 기반 쿼리 매개 변수 및 개체 기반 탐색 매개 변수를 동시에 전달할 수 있습니다.

뒤로 단추 동작

뒤로 단추 모양과 동작은 BackButtonBehavior 연결된 속성을 BackButtonBehavior 개체로 설정하여 재정의할 수 있습니다. BackButtonBehavior 클래스는 다음 속성을 정의합니다.

ICommand 형식의 Command - 뒤로 단추를 누를 때 실행됩니다.
object 형식의 CommandParameter - Command에 전달되는 매개 변수입니다.
ImageSource 형식의 IconOverride - 뒤로 단추에 사용되는 아이콘입니다.
boolean 형식의 IsEnabled - 뒤로 단추를 사용할 수 있는지를 나타냅니다. 기본값은 true입니다.
IsVisible형식 boolean은 뒤로 단추가 표시되는지 여부를 나타냅니다. 기본값은 true입니다.
string 형식의 TextOverride - 뒤로 단추에 사용되는 텍스트입니다.

이 모든 속성은 BindableProperty 개체에서 지원되며, 이는 속성이 데이터 바인딩의 대상이 될 수 있음을 의미합니다. 각각 BindableProperty 에는 OneTime 바인딩 모드가 있습니다. 즉, 데이터가 원본에서 대상으로 전송되지만 변경되는 BindingContext 경우에만 해당됩니다.

이 모든 속성은 BindableProperty 개체에서 지원되며, 이는 속성이 데이터 바인딩의 대상이 될 수 있음을 의미합니다. , , 및 BindableProperty 개체에는 CommandOneTime 바인딩 모드가 있습니다. 즉, 데이터가 원본에서 대상으로 전송되지만 변경되는 BindingContext 경우에만 해당됩니다.TextOveride IconOverideCommandParameter 및 IsVisible BindableProperty 개체에는 IsEnabled OneWay 바인딩 모드가 있습니다. 즉, 데이터가 원본에서 대상으로 이동합니다.

다음 코드에서는 뒤로 단추 모양 및 동작을 재정의하는 예제를 보여 줍니다.

<ContentPage ...>    
    <Shell.BackButtonBehavior>
        <BackButtonBehavior Command="{Binding BackCommand}"
                            IconOverride="back.png" />   
    </Shell.BackButtonBehavior>
    ...
</ContentPage>

Command 속성은 뒤로 단추를 누를 때 실행될 ICommand로 설정되고 IconOverride 속성은 뒤로 단추에 사용되는 아이콘으로 설정됩니다.

다음을 통해 공유

경로

경로 등록

세부 정보 페이지 경로 등록

탐색 수행

절대 경로

상대 경로

상황별 탐색

뒤로 탐색

잘못된 경로

탐색 디버그

탐색 스택

탐색 이벤트

탐색 지연

데이터 전달

다중 사용 개체 기반 탐색 데이터 전달

단일 사용 개체 기반 탐색 데이터 전달

탐색 데이터 받기

쿼리 속성 특성을 사용하여 탐색 데이터 처리

단일 메서드를 사용하여 탐색 데이터 처리

여러 데이터 항목 전달 및 처리

뒤로 단추 동작

추가 리소스