Stany wizualne

Menedżer stanów wizualnych .NET Multi-platform App UI (.NET MAUI) zapewnia ustrukturyzowany sposób wprowadzania zmian wizualnych w interfejsie użytkownika z kodu. W większości przypadków interfejs użytkownika aplikacji jest definiowany w języku XAML, a ten kod XAML może zawierać znaczniki opisujące, w jaki sposób program Visual State Manager wpływa na wizualizacje interfejsu użytkownika.

Program Visual State Manager wprowadza koncepcję stanów wizualizacji. Widok .NET MAUI, taki jak Button, może mieć kilka różnych wyglądów wizualnych w zależności od stanu, w jakim się znajduje — czy jest wyłączony, naciśnięty, czy ma fokus wejściowy. Są to stany przycisku. Stany wizualne są zbierane w grupach stanów wizualnych. Wszystkie stany wizualne w grupie stanów wizualnych wykluczają się wzajemnie. Zarówno stany wizualizacji, jak i grupy stanów wizualnych są identyfikowane przez proste ciągi tekstowe.

Program Visual State Manager .NET MAUI definiuje grupę stanu wizualizacji o nazwie CommonStates z następującymi stanami wizualnymi:

  • Standardowy
  • Wyłączony
  • Skupiono uwagę
  • Wybrano
  • WskaźnikNad

Stany wizualizacji Normal, Disabled, Focused i PointerOver są obsługiwane we wszystkich klasach, które pochodzą z VisualElement, klasy bazowej dla View i Page. Ponadto można również zdefiniować własne grupy stanów wizualnych i stany wizualizacji.

Zaletą używania programu Visual State Manager do definiowania wyglądu zamiast uzyskiwania dostępu do elementów wizualnych bezpośrednio z tyłu kodu jest możliwość kontrolowania sposobu, w jaki elementy wizualne reagują na inny stan w całości w języku XAML, co zapewnia cały projekt interfejsu użytkownika w jednej lokalizacji.

Uwaga / Notatka

Wyzwalacze mogą również wprowadzać zmiany w wizualizacjach w interfejsie użytkownika na podstawie zmian we właściwościach widoku lub wyzwalaniu zdarzeń. Jednak użycie wyzwalaczy do obsługi różnych kombinacji tych zmian może stać się mylące. W Visual State Manager stany wizualne w grupie stanów wizualnych zawsze wykluczają się wzajemnie. W dowolnym momencie tylko jeden stan w każdej grupie jest bieżącym stanem.

Typowe stany wizualne

Menadżer Stanu Wizualnego umożliwia dołączenie znaczników do pliku XAML, które mogą zmienić wygląd widoku, jeśli widok jest normalny, wyłączony, ma fokus wejścia, jest zaznaczony lub ma kursor myszy na sobie, ale nie jest naciśnięty. Są one znane jako wspólne stany.

Załóżmy na przykład, że masz Entry widok na stronie i chcesz, aby wygląd Entry zmienił się w następujący sposób:

  • Element Entry powinien mieć różowe tło, gdy Entry element jest wyłączony.
  • Entry powinno normalnie mieć limonkowe tło.
  • Element Entry powinien rozwinąć się do dwukrotnie większej normalnej wysokości, gdy ma fokus wejściowy.
  • Powinien Entry mieć jasnoniebieskie tło, gdy ma kursor myszy unoszący się na nim, ale nie naciśnięty.

Możesz dołączyć znacznik programu Visual State Manager do pojedynczego widoku lub zdefiniować go w stylu, jeśli ma zastosowanie do wielu widoków.

Definiuj stany wizualne w widoku

Klasa VisualStateManager definiuje dołączoną VisualStateGroups właściwość, która jest używana do dołączania stanów wizualizacji do widoku. Właściwość VisualStateGroups jest typu VisualStateGroupList, który jest kolekcją VisualStateGroup obiektów. W związku z tym element podrzędny dołączonej VisualStateManager.VisualStateGroups właściwości jest obiektem VisualStateGroup . Ten obiekt definiuje x:Name atrybut, który wskazuje nazwę grupy. Alternatywnie klasa VisualStateGroup definiuje właściwość Name, którą można zastosować. Aby uzyskać więcej informacji na temat dołączonych właściwości, zobacz Dołączone właściwości.

Klasa VisualStateGroup definiuje właściwość o nazwie States, która jest kolekcją VisualState obiektów. States jest właściwością zawartości klasy VisualStateGroups, dzięki czemu można uwzględnić obiekty VisualState jako elementy podrzędne VisualStateGroup. Każdy VisualState obiekt należy zidentyfikować przy użyciu metody x:Name lub Name.

Klasa VisualState definiuje właściwość o nazwie Setters, która jest kolekcją Setter obiektów. Są to te same Setter obiekty, których używasz w Style obiekcie. Setters nie jest właściwością zawartości VisualState, dlatego należy uwzględnić tagi elementów dla właściwości Setters. Setter obiekty powinny być wstawione jako elementy podrzędne Setters. Każdy Setter obiekt wskazuje wartość właściwości, gdy ten stan jest bieżący. Każda właściwość, do której odwołuje się obiekt Setter, musi być opisana przez powiązaną właściwość.

Ważna

Aby obiekty stanu Setter wizualizacji działały poprawnie, obiekt VisualStateGroup musi zawierać VisualState obiekt stanu Normal . Jeśli ten stan wizualizacji nie ma żadnych Setter obiektów, powinien zostać uwzględniony jako pusty stan wizualizacji (<VisualState Name="Normal" />).

W poniższym przykładzie przedstawiono wizualne stany zdefiniowane na obiekcie Entry:

<Entry FontSize="18">
    <VisualStateManager.VisualStateGroups>
        <VisualStateGroupList>
            <VisualStateGroup Name="CommonStates">
                <VisualState Name="Normal">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor" Value="Lime" />
                    </VisualState.Setters>
                </VisualState>

                <VisualState Name="Focused">
                    <VisualState.Setters>
                        <Setter Property="FontSize" Value="36" />
                    </VisualState.Setters>
                </VisualState>

                <VisualState Name="Disabled">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor" Value="Pink" />
                    </VisualState.Setters>
                </VisualState>

                <VisualState Name="PointerOver">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor" Value="LightBlue" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </VisualStateManager.VisualStateGroups>
</Entry>

Poniższy zrzut ekranu przedstawia Entry w czterech zdefiniowanych stanach wizualizacji:

Zrzut ekranu przedstawiający cztery zdefiniowane stany wizualne kontrolki Entry.

Entry Gdy jest w Normal stanie, jego tło jest koloru limonki. Gdy Entry zyska fokus wejściowy, jego rozmiar czcionki podwaja się. Entry Gdy obiekt staje się wyłączony, jego tło staje się różowe. Element Entry nie zachowuje zielonego tła, gdy zyskuje fokus. Gdy wskaźnik myszy znajduje się na Entry obiekcie, lecz nie zostaje naciśnięty, tło Entry staje się jasnoniebieskie. Gdy program Visual State Manager przełącza się między stanami wizualizacji, właściwości ustawione przez poprzedni stan nie są ustawiane. W związku z tym stany wizualne wzajemnie się wykluczają.

Jeśli chcesz, aby Entry miał tło o kolorze limonki w stanie Focused, dodaj kolejny Setter do tego stanu wizualnego.

<VisualState Name="Focused">
    <VisualState.Setters>
        <Setter Property="FontSize" Value="36" />
        <Setter Property="BackgroundColor" Value="Lime" />
    </VisualState.Setters>
</VisualState>

Definiowanie stanów wizualnych w stylu

Często konieczne jest dzielenie się tymi samymi stanami wizualnymi w co najmniej dwóch widokach. W tym scenariuszu stany wizualne można zdefiniować w obiekcie Style. Można to osiągnąć, dodając obiekt Setter dla właściwości VisualStateManager.VisualStateGroups. Właściwość content obiektu Setter to jego właściwość Value, dlatego może być określona jako element podrzędny obiektu Setter. Właściwość VisualStateGroups jest typu VisualStateGroupList, a więc element podrzędny Setter obiektu jest elementem VisualStateGroupListVisualStateGroup , do którego można dodać element zawierający VisualState obiekty.

W poniższym przykładzie przedstawiono niejawny styl elementu Entry definiujący typowe stany wizualizacji:

<Style TargetType="Entry">
    <Setter Property="FontSize" Value="18" />
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup Name="CommonStates">
                <VisualState Name="Normal">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor" Value="Lime" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState Name="Focused">
                    <VisualState.Setters>
                        <Setter Property="FontSize" Value="36" />
                        <Setter Property="BackgroundColor" Value="Lime" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState Name="Disabled">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor" Value="Pink" />
                    </VisualState.Setters>
                </VisualState>
                <VisualState Name="PointerOver">
                    <VisualState.Setters>
                        <Setter Property="BackgroundColor" Value="LightBlue" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>

Jeśli ten styl zostanie uwzględniony w słowniku zasobów na poziomie strony, Style obiekt zostanie zastosowany do wszystkich Entry obiektów na stronie. W związku z tym wszystkie Entry obiekty na stronie będą odpowiadać w taki sam sposób na swoje stany wizualne.

Stany wizualizacji w .NET MAUI

W poniższej tabeli wymieniono stany wizualizacji zdefiniowane w .NET MAUI:

Klasa States Więcej informacji
Button Pressed Stany wizualizacji przycisku
CarouselView DefaultItem, , CurrentItem, , PreviousItemNextItem Stany wizualne CarouselView
CheckBox IsChecked Stany wizualizacji CheckBox
CollectionView Selected Stany wizualizacji CollectionView
ImageButton Pressed Stany wizualizacji ImageButton
RadioButton Checked, Unchecked Stany wizualizacji RadioButton
Switch On, Off Przełączanie stanów wizualizacji
VisualElement Normal, , Disabled, , FocusedPointerOver Wspólne stany

Ustawianie stanu na wielu elementach

W poprzednich przykładach stany wizualne zostały dołączone do pojedynczych elementów i działały na nich. Istnieje jednak również możliwość utworzenia stanów wizualnych powiązanych z jednym elementem, które ustawiają właściwości na innych elementach w tym samym zakresie. Pozwala to uniknąć konieczności powtarzania stanów wizualnych na każdym elemencie, na którym działają stany.

Typ Setter ma właściwość TargetName typu string, która reprezentuje obiekt docelowy, którym będzie manipulować Setter dla stanu wizualizacji. Po zdefiniowaniu TargetNameSetter ustawia Property obiektu zdefiniowanego w TargetName elemencie na Value wartość:

<Setter TargetName="label"
        Property="Label.TextColor"
        Value="Red" />

W tym przykładzie obiekt Label o nazwie label będzie miał właściwość TextColor ustawioną na Red. Przy ustawianiu właściwości TargetName należy określić pełną ścieżkę do właściwości w Property. Aby ustawić właściwość TextColor na Label, Property jest określony jako Label.TextColor.

Uwaga / Notatka

Każda właściwość, do której odwołuje się obiekt Setter, musi być opisana przez powiązaną właściwość.

W poniższym przykładzie pokazano, jak ustawić stan na wielu obiektach z jednej grupy stanu wizualizacji:

<StackLayout>
    <Label Text="What is the capital of France?" />
    <Entry x:Name="entry"
           Placeholder="Enter answer" />
    <Button Text="Reveal answer">
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup Name="CommonStates">
                <VisualState Name="Normal" />
                <VisualState Name="Pressed">
                    <VisualState.Setters>
                        <Setter Property="Scale"
                                Value="0.8" />
                        <Setter TargetName="entry"
                                Property="Entry.Text"
                                Value="Paris" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>
    </Button>
</StackLayout>

W tym przykładzie stan Normal jest aktywny, gdy Button nie jest naciśnięty, a odpowiedź może zostać wprowadzona do Entry. Stan Pressed staje się aktywny po naciśnięciu Button i określa, że jego Scale właściwość zostanie zmieniona z wartości domyślnej 1 do 0,8. Ponadto nazwana Entryentry będzie miała swoją Text właściwość ustawioną na Paryż. W związku z tym wynik jest taki, że po naciśnięciu Button jest on nieco zmniejszany, a na Entry wyświetla się Paryż.

Zrzut ekranu przedstawiający stan wciśnięty przycisku.

Następnie, gdy Button element zostanie wydany, zostanie ponownie przeskalowany do wartości domyślnej 1, a Entry element wyświetla dowolny wcześniej wprowadzony tekst.

Ważna

Ścieżki właściwości nie są obsługiwane w Setter elementach określających TargetName właściwość.

Definiowanie stanów wizualizacji niestandardowych

Niestandardowe stany wizualizacji można zaimplementować, definiując je tak, jak można zdefiniować stany wizualne dla typowych stanów, ale z wybranymi nazwami, a następnie wywołując VisualStateManager.GoToState metodę w celu aktywowania stanu.

W poniższym przykładzie pokazano, jak używać programu Visual State Manager do sprawdzania poprawności danych wejściowych:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="VsmDemos.VsmValidationPage"
             Title="VSM Validation">
    <StackLayout x:Name="stackLayout"
                 Padding="10, 10">
            <VisualStateManager.VisualStateGroups>
                <VisualStateGroup Name="ValidityStates">
                    <VisualState Name="Valid">
                        <VisualState.Setters>
                            <Setter TargetName="helpLabel"
                                    Property="Label.TextColor"
                                    Value="Transparent" />
                            <Setter TargetName="entry"
                                    Property="Entry.BackgroundColor"
                                    Value="Lime" />
                        </VisualState.Setters>
                    </VisualState>
                    <VisualState Name="Invalid">
                        <VisualState.Setters>
                            <Setter TargetName="entry"
                                    Property="Entry.BackgroundColor"
                                    Value="Pink" />
                            <Setter TargetName="submitButton"
                                    Property="Button.IsEnabled"
                                    Value="False" />
                        </VisualState.Setters>
                    </VisualState>
                </VisualStateGroup>
            </VisualStateManager.VisualStateGroups>
        <Label Text="Enter a U.S. phone number:"
               FontSize="18" />
        <Entry x:Name="entry"
               Placeholder="555-555-5555"
               FontSize="18"
               Margin="30, 0, 0, 0"
               TextChanged="OnTextChanged" />
        <Label x:Name="helpLabel"
               Text="Phone number must be of the form 555-555-5555, and not begin with a 0 or 1" />
        <Button x:Name="submitButton"
                Text="Submit"
                FontSize="18"
                Margin="0, 20"
                VerticalOptions="Center"
                HorizontalOptions="Center" />
    </StackLayout>
</ContentPage>

W tym przykładzie do StackLayout są dołączone wizualne stany, a dwa z nich, o nazwach Valid i Invalid, są wzajemnie wykluczające się. Jeśli parametr Entry nie zawiera prawidłowego numeru telefonu, obecny stan to Invalid, a więc Entry ma różowe tło, drugi Label jest widoczny, a właściwość Button jest wyłączona. Po wprowadzeniu prawidłowego numeru telefonu bieżący stan zmieni się na Valid. Entry ma teraz tło w kolorze limonki, drugi Label znika, a Button jest teraz włączone.

Zrzut ekranu z przykładu weryfikacji stanu wizualnego.

Plik związany z kodem jest odpowiedzialny za obsługę zdarzenia TextChanged z Entry. Procedura obsługi używa wyrażenia regularnego, aby określić, czy ciąg wejściowy jest prawidłowy, czy nie. Metoda GoToState w pliku kodu zaplecza wywołuje statyczną metodę VisualStateManager.GoToState na obiekcie StackLayout:

public partial class VsmValidationPage : ContentPage
{
    public VsmValidationPage()
    {
        InitializeComponent();

        GoToState(false);
    }

    void OnTextChanged(object sender, TextChangedEventArgs args)
    {
        bool isValid = Regex.IsMatch(args.NewTextValue, @"^[2-9]\d{2}-\d{3}-\d{4}$");
        GoToState(isValid);
    }

    void GoToState(bool isValid)
    {
        string visualState = isValid ? "Valid" : "Invalid";
        VisualStateManager.GoToState(stackLayout, visualState);
    }
}

W tym przykładzie metoda GoToState jest wywoływana z konstruktora w celu zainicjowania stanu. Zawsze powinien istnieć bieżący stan. Następnie plik code-behind wywołuje VisualStateManager.GoToState z nazwą stanu na obiekcie, który definiuje stany wizualne.

Wyzwalacze stanu wizualnego

Stany wizualne obsługują wyzwalacze stanu, które są wyspecjalizowaną grupą wyzwalaczy definiujących warunki, w których VisualState należy zastosować.

Wyzwalacze stanu są dodawane do StateTriggers kolekcji elementu VisualState. Ta kolekcja może zawierać jeden wyzwalacz stanu lub wiele wyzwalaczy stanu. Element VisualState zostanie zastosowany, gdy wszystkie wyzwalacze stanu w kolekcji są aktywne.

W przypadku używania wyzwalaczy stanu do kontrolowania stanów wizualnych .NET MAUI używa następujących reguł pierwszeństwa w celu określenia, który wyzwalacz (i odpowiednie VisualState) będzie aktywny:

  1. Każdy wyzwalacz pochodzący z elementu StateTriggerBase.
  2. Aktywowano AdaptiveTrigger ze względu na spełnienie warunku MinWindowWidth.
  3. Aktywowano AdaptiveTrigger ze względu na spełnienie warunku MinWindowHeight.

Jeśli wiele wyzwalaczy jest jednocześnie aktywnych (na przykład dwa wyzwalacze niestandardowe), pierwszy wyzwalacz zadeklarowany w znaczniku ma pierwszeństwo.

Aby uzyskać więcej informacji na temat wyzwalaczy stanu, zobacz Wyzwalacze stanu.

Unieważnianie i ponowne zastosowanie stanów wizualnych

Kiedy modyfikujesz wartości setterów w VisualState w czasie wykonywania, odpowiednia kontrolka nie odzwierciedla zmian automatycznie. Metoda InvalidateVisualStates(VisualElement) powoduje, że VisualElement przestaje stosować, a następnie ponownie stosuje ustawienia dla bieżącego stanu we wszystkich grupach stanów wizualnych, co powoduje, że zaktualizowane wartości wchodzą w życie.

Poniższy przykład modyfikuje wartość ustawiacza stanu wizualnego, a następnie wywołuje metodę InvalidateVisualStates w celu odświeżenia kontrolki.

// Locate the "Pressed" visual state defined on the button.
var groups = VisualStateManager.GetVisualStateGroups(myButton);
var pressedState = groups
    .SelectMany(g => g.States)
    .First(s => s.Name == "Pressed");

// Modify a setter value in-place.
pressedState.Setters[0].Value = Colors.Orange;

// Force the control to reapply the current state's setters.
VisualStateManager.InvalidateVisualStates(myButton);

Uwaga / Notatka

InvalidateVisualStates jest interfejsem API sterowanym obiektem wywołującym — .NET MAUI nie wykrywa automatycznie, gdy wartości ustawiające stan wizualizacji zmieniają się. Należy wywołać tę metodę dla każdego elementu, który powinien odzwierciedlać zaktualizowany stan wizualizacji.

  • Ostatnia aktualizacja o