Навигация в оболочке .NET MAUI

Обзор примера

.NET Multi-Platform App UI (.NET MAUI) Shell включает интерфейс навигации, основанный на URI, который позволяет маршрутам переходить на любую страницу в приложении без строгого соблюдения иерархии навигации. Кроме того, есть возможность перемещаться в обратном направлении без обязательного посещений всех страниц в стеке навигации.

Класс Shell определяет следующие свойства, связанные с навигацией:

• BackButtonBehaviorс типом BackButtonBehavior — присоединяемое свойство, которое определяет поведение кнопки "Назад";
• CurrentItem с типом ShellItem — обозначает текущий выбранный элемент;
• CurrentPage с типом Page — обозначает текущую отображаемую страницу;
• CurrentState с типом ShellNavigationState — текущее состояние навигации для Shell;
• Current, типа Shell, предоставляющего доступ к текущей оболочке.

Свойства BackButtonBehavior, CurrentItem и CurrentState поддерживаются объектами BindableProperty, то есть эти свойства можно указывать в качестве целевых для привязки данных.

Навигация выполняется путем вызова метода GoToAsync из класса Shell. Когда навигация собирается начаться, срабатывает событие Navigating, а после завершения навигации — событие Navigated.

Маршруты

Навигация в приложении с оболочкой Shell выполняется путем указания универсального кода ресурса (URI) для перехода. URI навигации могут содержать следующие три компонента:

• Маршрут, который определяет путь к содержимому в составе визуальной иерархии оболочки Shell.
• Страница. Страницы, которые отсутствуют в визуальной иерархии оболочки Shell, можно поместить в стек навигации из любого места в приложении. Например, страница сведений отсутствует в визуальной иерархии оболочки Shell, но при необходимости может быть помещена в стек навигации.
• Один или несколько параметров запроса. Параметры запроса — это параметры, которые могут быть переданы целевой странице при навигации.

Если URI навигации содержит все три компонента, он имеет формат "//маршрут/страница?параметры".

Регистрация маршрутов

Маршруты можно определить для объектов 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

Чтобы перейти к объекту ShellContent по маршруту dogs, абсолютный URI должен выглядеть так: //animals/domestic/dogs. Аналогичным образом, чтобы перейти к объекту ShellContent для маршрута about, абсолютный URI — это //about.

Страница деталей маршрутов

В конструкторе подкласса 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, из любой части приложения. Маршруты для таких страниц называются глобальными маршрутами.

Также вы можете регистрировать страницы в другие иерархии маршрутов, если потребуется:

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

Этот пример включает контекстную навигацию по страницам, при которой переход по маршруту details со страницы маршрута monkeys отображает MonkeyDetailPage. Аналогичным образом переход по маршруту details со страницы маршрута elephants отображает ElephantDetailPage. Дополнительные сведения см. в разделе Контекстная навигация.

Выполнение навигации

Чтобы выполнить перемещение, нужно получить ссылку на подкласс Shell. Эту ссылку можно получить через Shell.Current свойство. После этого выполняется перемещение путем вызова метода GoToAsync из объекта Shell. Этот метод переходит к ShellNavigationState и возвращает Task, который будет завершён после завершения анимации перехода. Объект ShellNavigationState создается с помощью метода GoToAsync из string или Uri и для его свойства Location задается значение аргумента string или Uri.

Текущее состояние навигации для объекта Shell можно извлечь через свойство Shell.Current.CurrentState, которое содержит URI отображаемого маршрута в свойстве Location.

Абсолютные маршруты

Для навигации можно передать допустимый абсолютный URI в качестве аргумента в метод GoToAsync:

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

Этот пример переходит на страницу маршрута monkeys, причем маршрут определен в объекте ShellContent. Объект ShellContent, который представляет маршрут monkeys, является дочерним элементом объекта FlyoutItem с маршрутом animals.

Относительные маршруты

Для навигации можно также передать допустимый относительный URI в качестве аргумента в метод GoToAsync. Система маршрутизации попытается сопоставить URI с объектом ShellContent. Таким образом, если все маршруты в приложении уникальны, навигация может выполняться только путем указания уникального имени маршрута в качестве относительного URI.

В следующем примере показан переход на страницу маршрута monkeydetails.

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

В этом примере маршрут monkeyDetails ищется до тех пор, пока не будет найдена соответствующая страница. Найденная страница отправляется в стек навигации.

Контекстная навигация

Относительные маршруты позволяют организовать контекстную навигацию. Для примера рассмотрим следующую иерархию маршрутов:

monkeys
  details
bears
  details

Когда отображается страница с зарегистрированным маршрутом monkeys, переход по маршруту details отображает страницу с зарегистрированным маршрутом monkeys/details. Аналогичным образом, когда отображается страница с зарегистрированным маршрутом bears, переход по маршруту details отображает страницу с зарегистрированным маршрутом bears/details. Для получения информации о регистрации маршрутов в этом примере, см. Register page routes.

Обратная навигация

Обратную навигацию можно выполнить, указав аргумент ".." в вызове метода GoToAsync:

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

Обратную навигацию с ".." можно также объединить с маршрутом:

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

В этом примере выполняется обратная навигация, а затем осуществляется переход к указанному маршруту.

Аналогичным образом можно перемещаться назад несколько раз, а затем переходить по указанному маршруту:

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

В этом примере обратная навигация выполняется дважды, а затем осуществляется переход к указанному маршруту.

Кроме того, данные можно передавать через свойства запроса при обратной навигации.

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

В этом примере выполняется обратная навигация, и значение параметра запроса передается параметру запроса на предыдущей странице.

Дополнительные сведения о передаче данных при навигации см. в разделе Передача данных.

Недопустимые маршруты

Следующие форматы маршрутов считаются недопустимыми.

Использование этих форматов маршрутов приводит к созданию исключения Exception.

Отладка навигации

Некоторые классы Shell декорированы с помощью DebuggerDisplayAttribute, который определяет, как класс или поле отображается в отладчике. Это может помочь в отладке запросов навигации, отображая данные, связанные с запросом навигации. Например, на следующем снимке экрана показаны свойства CurrentItem и CurrentState объекта Shell.Current:

В этом примере свойство CurrentItem с типом FlyoutItem отображает название и маршрут объекта FlyoutItem. Аналогичным образом, свойство CurrentState типа ShellNavigationState отображает универсальный код ресурса (URI) отображаемого маршрута в приложении оболочки Shell.

Стек навигации

Класс Tab определяет свойство Stack типа IReadOnlyList<Page>, представляющее текущий стек навигации в пределах Tab. Класс также предоставляет следующие переопределимые методы навигации:

• 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 должны использоваться в визуальной иерархии оболочки вместо объектов Tab.

События навигации

Класс Shell определяет событие Navigating, которое возникает перед выполнением любого перехода — программного или вызванного действием пользователя. Объект ShellNavigatingEventArgs, который прилагается к событию Navigating, содержит следующие свойства:

Кроме того, класс ShellNavigatingEventArgs предоставляет метод Cancel, позволяющий отменить переход, и метод GetDeferral, возвращающий токен ShellNavigatingDeferral, который можно использовать для завершения перехода. Для получения дополнительной информации о перенаправлении навигации см. Отложенный переход.

Класс Shell также определяет событие Navigated, которое возникает при завершении навигации. Объект ShellNavigatedEventArgs, который прилагается к событию Navigated, содержит следующие свойства:

Классы ShellNavigatedEventArgs и ShellNavigatingEventArgs имеют свойства Source с типом ShellNavigationSource. Значения перечисления указаны ниже:

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

Отложенная навигация

Навигацию оболочки можно перехватить, а затем завершить или отменить в зависимости от выбора пользователя. Для этого можно переопределить метод OnNavigating в подклассе Shell и вызвать метод GetDeferral для объекта ShellNavigatingEventArgs. Этот метод возвращает токен ShellNavigatingDeferral с методом Complete, который можно использовать для завершения запроса о переходе:

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

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

        ShellNavigatingDeferral token = args.GetDeferral();

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

В этом примере отображается лист действий, приглашающий пользователя завершить запрос навигации или отменить его. Переход отменяется вызовом метода Cancel для объекта ShellNavigatingEventArgs. Переход завершается вызовом метода Complete на токене ShellNavigatingDeferral, который был получен методом GetDeferral на объекте ShellNavigatingEventArgs.

Передача данных

Примитивные данные можно передать в виде строковых параметров запроса при выполнении программной навигации на основе URI. Для этого в конец маршрута добавляется ?, а затем идентификатор параметра запроса, символ =и значение для этого параметра:

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 качестве параметра запроса.

Передача навигационных данных многократного использования на основе объектов

Множественные данные навигации, основанные на объектах, могут передаваться с перегрузкой GoToAsync, которая указывает на IDictionary<string, object> аргумент.

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 добавляется в Dictionary с ключом Bear. Затем выполняется навигация по маршруту beardetails, передавая Dictionary в качестве параметра навигации.

Все данные, передаваемые в качестве IDictionary<string, object> аргумента, хранятся в памяти в течение всего времени существования страницы и не освобождаются до тех пор, пока страница не будет удалена из стека навигации. Это может быть проблематично, как показано в следующем сценарии:

1. Page1 переходит к Page2 с использованием метода GoToAsync, передавая объект с именем MyData. Page2 затем получает в MyData качестве параметра запроса.
2. Page2 переходит к Page3 с использованием метода GoToAsync без передачи данных.
3. Page3 перемещается назад с GoToAsync помощью метода. Page2 затем снова получает MyData в качестве параметра запроса.

Хотя это желательно во многих сценариях, если это не нужно, следует использовать метод Clear, чтобы очистить аргумент IDictionary<string, object> после того, как он впервые получен страницей.

Передача навигационных данных одноразового использования на основе объектов

Навигационные данные для одноразового использования на основе объектов могут передаваться с помощью перегрузки GoToAsync, которая указывает аргумент ShellNavigationQueryParameters. 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);
}

В этом примере извлекается выбранный в данный момент медведь в CollectionViewвиде Animal добавляемого в ShellNavigationQueryParameters объект. Затем выполняется переход к beardetails маршруту с ShellNavigationQueryParameters объектом, передаваемым в качестве параметра навигации. После завершения навигации данные в объекте ShellNavigationQueryParameters очищаются.

Получение данных навигации

Существует два подхода к получению данных навигации.

1. Класс той страницы, на которую осуществляется переход, или класс BindingContext этой страницы можно дополнить атрибутом QueryPropertyAttribute для каждого параметра запроса. Дополнительные сведения об обработке данных навигации с помощью атрибутов свойств запроса см. в этом разделе.
2. Класс той страницы, на которую осуществляется переход, или класс BindingContext этой страницы может реализовать интерфейс IQueryAttributable. Дополнительные сведения об обработке данных навигации с помощью одного метода см. в этом разделе.

Обработка данных навигации с помощью атрибутов свойств запроса

Данные навигации можно получить, украшая класс-получатель QueryPropertyAttribute с помощью каждого строкового параметра запроса, объектного параметра навигации или ShellNavigationQueryParameters объекта:

[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 свойства указывает имя свойства, которое будет получать данные, с вторым аргументом, указывающим идентификатор параметра. Поэтому в приведенном выше примере указывается, QueryPropertyAttribute что Bear свойство получит данные, переданные в параметре навигации в Bear вызове GoToAsync метода.

Обработка данных навигации с помощью одного метода

Данные навигации можно получить, реализовав в принимающем классе интерфейс IQueryAttributable. Интерфейс IQueryAttributable указывает, что реализующий класс должен реализовать метод ApplyQueryAttributes. У этого метода есть аргумент query типа IDictionary<string, object>, который содержит любые данные, передаваемые в процессе навигации. Каждый ключ в словаре — это идентификатор параметра запроса с его значением, соответствующим объекту, представляющего данные. Преимущество использования этого подхода заключается в том, что данные навигации можно обрабатывать с помощью одного метода. Это может быть полезно, если у вас есть несколько элементов данных навигации, требующих обработки в целом.

В следующем примере показан класс модели представления, реализующий интерфейс 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.

Передача и обработка нескольких элементов данных

Несколько параметров запроса на основе строк можно передать, подключив их к &. Например, следующий код передает два элемента данных:

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. В обоих случаях значения параметров запросов указываются в URI в вызове метода GoToAsync.

Кроме того, данные навигации можно обрабатывать одним методом, реализовав интерфейс IQueryAttributable в классе, представляющем страницу, к которой осуществляется переход, или классе BindingContext страницы:

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 извлекает значение параметров запроса name и location из URI в вызов метода GoToAsync.

Действие кнопки "Назад"

Внешний вид и поведение кнопки "Назад" можно переопределить, присвоив присоединенное свойство BackButtonBehavior объекту BackButtonBehavior. Класс BackButtonBehavior определяет следующие свойства:

• Command с типом ICommand, который выполняется при нажатии кнопки "Назад".
• CommandParameter типа object, который передается в Command как параметр.
• IconOverride с типом ImageSource, который содержит значок для кнопки "Назад".
• IsEnabled с типом boolean, который указывает, доступна ли кнопка перехода назад. Значение по умолчанию — true.
• IsVisible, тип boolean, указывает, отображается ли кнопка "Назад". Значение по умолчанию — true.
• TextOverride, типа string, текст для кнопки "Назад".

В следующем коде показан пример переопределения внешнего вида и поведения кнопки "Назад":

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

Свойство Command установлено в ICommand, чтобы выполняться, когда нажимается кнопка "Назад", а свойство IconOverride определяет значок, используемый для кнопки "Назад":