StateContainer

La visualizzazione di una visualizzazione specifica quando l'app è in uno stato specifico è un modello comune in qualsiasi app per dispositivi mobili. Gli esempi spaziano dalla creazione di schermate di caricamento da sovrapporre allo schermo o a una sua sezione. È possibile creare visualizzazioni di stato vuote per quando non sono presenti dati da visualizzare e visualizzare le visualizzazioni dello stato degli errori quando si verifica un errore.

Come iniziare

Le StateContainer proprietà associate consentono all'utente di trasformare qualsiasi elemento di layout come VerticalStackLayout, HorizontalStackLayouto Grid in un layout compatibile con lo stato. Ogni layout consapevole dello stato contiene una raccolta di elementi derivati da View. Questi elementi possono essere usati come modelli per stati diversi definiti dall'utente. Ogni volta che la CurrentState proprietà stringa viene impostata su un valore corrispondente alla StateKey proprietà di uno degli elementi View, il relativo contenuto verrà visualizzato anziché il contenuto principale. Quando CurrentState è impostata su null o una stringa vuota, viene visualizzato il contenuto principale.

Syntax

StateContainer le proprietà possono essere usate in XAML o C#.

XAML

Inclusione del namespace XAML

Per usare il toolkit in XAML, è necessario aggiungere le informazioni seguenti xmlns nella pagina o nella visualizzazione:

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Di conseguenza:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Verrà modificato in modo da includere il xmlns come indicato di seguito:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Uso di StateContainer

Di seguito è riportato un esempio di interfaccia utente creata con XAML. Questa interfaccia utente di esempio è connessa all'oggetto ViewModel seguente, StateContainerViewModel.

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MyProject.MyStatePage"
             BindingContext="StateContainerViewModel">

    <VerticalStackLayout 
        toolkit:StateContainer.CurrentState="{Binding CurrentState}"
        toolkit:StateContainer.CanStateChange="{Binding CanStateChange}">

        <toolkit:StateContainer.StateViews>
            <VerticalStackLayout toolkit:StateView.StateKey="Loading">
                <ActivityIndicator IsRunning="True" />
                <Label Text="Loading Content..." />
            </VerticalStackLayout>
            <Label toolkit:StateView.StateKey="Success" Text="Success!" />
        </toolkit:StateContainer.StateViews>

        <Label Text="Default Content" />
        <Button Text="Change State" Command="{Binding ChangeStateCommand}" />

    </VerticalStackLayout>

</ContentPage>

Linguaggio di markup C#

Di seguito è riportata la stessa interfaccia utente del codice XAML, precedentemente creata con markup C#.

Questa interfaccia utente di esempio è connessa all'oggetto ViewModel seguente, StateContainerViewModel.

using CommunityToolkit.Maui.Layouts;
using CommunityToolkit.Maui.Markup;

BindingContext = new StateContainerViewModel();

Content = new VerticalStackLayout()
{
    new Label()
        .Text("Default Content"),
    
    new Button()
        .Text("Change State")
        .Bind(
            Button.CommandProperty,
            static (StateContainerViewModel vm) => vm.ChangeStateCommand,
            mode: BindingMode.OneTime)
}.Bind(
    StateContainer.CurrentStateProperty,
    static (StateContainerViewModel vm) => vm.CurrentState,
    static (StateContainerViewModel vm, string currentState) => vm.CurrentState = currentState)
 .Bind(
    StateContainer.CanStateChangeProperty,
    static (StateContainerViewModel vm) => vm.CanStateChange,
    static (StateContainerViewModel vm, bool canStateChange) => vm.CanStateChange = canStateChange)
 .Assign(out VerticalStackLayout layout);

var stateViews = new List<View>()
{
    //States.Loading
    new VerticalStackLayout()
    {
        new ActivityIndicator() { IsRunning = true },
        new Label().Text("Loading Content")
    },

    //States.Success
    new Label().Text("Success!")
};

StateView.SetStateKey(stateViews[0], States.Loading);
StateView.SetStateKey(stateViews[1], States.Success);

StateContainer.SetStateViews(layout, stateViews);

static class States
{
    public const string Loading = nameof(Loading);
    public const string Success = nameof(Success);
}

ViewModel

Quando si usa un ICommand oggetto per modificare CurrentState (ad esempio, quando si usa Button.Command per modificare gli stati), è consigliabile usare CanStateBeChanged per ICommand.CanExecute().

Di seguito è riportato un esempio di MVVM che usa MVVM Community Toolkit:

[INotifyPropertyChanged]
public partial class StateContainerViewModel
{
    [ObservableProperty]
    [NotifyCanExecuteChangedFor(nameof(ChangeStateCommand))]
    bool canStateChange;

    [ObservableProperty]
    string currentState = States.Loading;

    [RelayCommand(CanExecute = nameof(CanStateChange))]
    void ChangeState()
    {
        CurrentState = States.Success;
    }
}

Per impostazione predefinita StateContainer cambia lo stato senza animazione. Per aggiungere un'animazione personalizzata, è possibile usare il ChangeStateWithAnimation metodo :

async Task ChangeStateWithCustomAnimation()
{
    var targetState = "TargetState";
    var currentState = StateContainer.GetCurrentState(MyBindableObject);
    if (currentState == targetState)
    {
        await StateContainer.ChangeStateWithAnimation(
            MyBindableObject,
            null,
            (element, token) => element.ScaleTo(0, 100, Easing.SpringIn).WaitAsync(token),
            (element, token) => element.ScaleTo(1, 250, Easing.SpringOut).WaitAsync(token),
            CancellationToken.None);
    }
    else
    {
        await StateContainer.ChangeStateWithAnimation(
            MyBindableObject,
            targetState,
            (element, token) => element.ScaleTo(0, 100, Easing.SpringIn).WaitAsync(token),
            (element, token) => element.ScaleTo(1, 250, Easing.SpringOut).WaitAsync(token),
            CancellationToken.None);
    }
}

Ecco come funziona in iOS:

Proprietà

StateContainer

Le proprietà StateContainer possono essere usate in qualsiasi Layout elemento che eredita.

StateView

Le proprietà StateView possono essere usate in qualsiasi View elemento che eredita.

Methods

StateContainer

Esempi

È possibile trovare un esempio di questa funzionalità in azione nell'applicazione di esempio .NET MAUI Community Toolkit.

API

È possibile trovare il codice sorgente per StateContainer nel repository .NET MAUI Community Toolkit GitHub.