VisualState Klasse

Referenz

Definition

Namespace:: Microsoft.UI.Xaml

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Bearbeiten

Stellt die visuelle Darstellung eines UI-Elements dar, wenn es sich in einem bestimmten Zustand befindet. Visuelle Zustände verwenden Setter oder ein Storyboard , um Ui-Eigenschaften innerhalb von Seiten oder Steuerelementvorlagen festzulegen, in denen die VisualState definiert ist.

public ref class VisualState sealed : DependencyObject

/// [Microsoft.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualState final : DependencyObject

[Microsoft.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class VisualState : DependencyObject

Public NotInheritable Class VisualState
Inherits DependencyObject

<VisualState x:Name="stateName" />
-or-
<VisualState x:Name="stateName">
  singleStoryboard
</VisualState>
-or-
<VisualState x:Name="stateName">
  <VisualState.Setters>
    oneOrMoreSetters
  </VisualState.Setters>
  [optional]singleStoryboard
</VisualState>
-or-
<VisualState x:Name="stateName">
  <VisualState.StateTriggers>
    oneOrMoreTriggers
  </VisualState.StateTriggers>  
  <VisualState.Setters>
    oneOrMoreSetters
  </VisualState.Setters>
  [optional]singleStoryboard
</VisualState>

Vererbung: Object Platform::Object IInspectable DependencyObject VisualState

Attribute: ContentPropertyAttribute ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Beispiele

In diesem Beispiel wird eine VisualStateGroup in der ControlTemplate einer Schaltfläche namens "CommonStates" erstellt und Objekte für die Zustände "Normal", "Pressed" und "PointerOver" hinzugefügt VisualState . Der Button definiert auch einen Zustand namens "Disabled", der sich in "CommonStates" mit dem Namen VisualStateGroup befindet, aber im Beispiel wird er aus Gründen der Kürze weggelassen.

<ControlTemplate TargetType="Button">
  <Border x:Name="RootElement">

    <VisualStateManager.VisualStateGroups>

      <!--Define the states for the common states.
          The states in the VisualStateGroup are mutually exclusive to
          each other.-->
      <VisualStateGroup x:Name="CommonStates">

        <!--The Normal state is the state the button is in
            when it is not in another state from this VisualStateGroup.-->
        <VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, BorderBrush, to red when the
            Pointer is over the button.-->
        <VisualState x:Name="PointerOver">
          <Storyboard>
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Red" />

          </Storyboard>

        </VisualState>

        <!--Change the SolidColorBrush, BorderBrush, to Transparent when the
            button is pressed.-->
        <VisualState x:Name="Pressed">
          <Storyboard >
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Transparent"/>
          </Storyboard>
        </VisualState>
          <!--The Disabled state is omitted for brevity.-->
        </VisualStateGroup>
  
    </VisualStateManager.VisualStateGroups>
    

    <Border.Background>
      <SolidColorBrush x:Name="BorderBrush" Color="Black"/>
    </Border.Background>

    <Grid Background="{TemplateBinding Background}" Margin="4">
      <ContentPresenter
        HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
        VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
        Margin="4,5,4,4" />

    </Grid>


  </Border>
</ControlTemplate>

<Page>
    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState>
                    <VisualState.StateTriggers>
                        <!-- VisualState to be triggered when window width is >=720 effective pixels -->
                        <AdaptiveTrigger MinWindowWidth="720"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="myPanel.Orientation" Value="Horizontal"/>
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>
        <StackPanel x:Name="myPanel" Orientation="Vertical">
            <TextBlock x:Name="myTextBlock" MaxLines="5" Style="{ThemeResource BodyTextBlockStyle}"/>
        </StackPanel>
    </Grid>
</Page>

Hinweise

Ein VisualState Element muss immer in einem übergeordneten VisualStateGroup-Element im XAML-Markup enthalten sein. Die VisualStateGroup verfügt über eine implizite Auflistungseigenschaft States, sodass Sie jedes VisualState als unmittelbar untergeordnetes Element des VisualStateGroup übergeordneten Elements platzieren können. Beispiel:

<VisualStateGroup x:Name="CommonStates">
   <VisualState x:Name="Normal"/>
   <VisualState x:Name="PointerOver">...</VisualState>
<!-- do not need explicit VisualStateGroups.States property element, States is the XAML content property-->
</VisualStateGroup>

Wenn Sie StateTriggers verwenden, stellen Sie sicher, dass visualStateGroup unter dem ersten untergeordneten Element des Stammes deklariert ist, damit die Trigger automatisch wirksam werden.

Standardstatus

Es ist legal und üblich, ein VisualState zu definieren, das über ein x:Name-Attribut verfügt, aber nichts im Storyboard angibt. Dies ist nützlich, da eine VisualState solche Werte verwendet, die in der Standardvorlage vorhanden sind. Sie können dann den leeren Zustand gezielt von einem GoToState-Aufruf anfordern. Wenn ein leerer Zustand zum aktuellen Zustand wird, werden alle Änderungen an Vorlageneigenschaften abgebrochen, die von einem vorherigen visuellen Zustand aus derselben VisualStateGroup vorgenommen wurden.

Wenn Sie StateTriggers verwenden, müssen Sie nicht mehr ein leeres VisualState erstellen, um GoToState aufzurufen. Wenn die Bedingungen für einen StateTrigger nicht mehr erfüllt sind, werden alle änderungen an den Eigenschaften, die vom entsprechenden VisualState vorgenommen wurden, automatisch entfernt, und die im Standardmarkup angegebenen Werte werden wirksam.

VisualState und x:Name

Die GoToState-Methode (die in der Regel aus Steuerelementcode aufgerufen wird) erfordert einen stateName Parameter, um visualStateManager darüber zu informieren, welcher Zustand als aktueller Zustand verwendet werden soll. Geben Sie ein x:Name-Attribut für jedes VisualState an, das manuell mithilfe eines Aufrufs GoToState von Code angewendet werden muss. Wenn Sie StateTriggers verwenden, um ein VisualState Markup automatisch auszulösen, müssen Sie kein x:Name-Attribut für diesen VisualState angeben.

Wenn Sie visuelle Übergänge verwenden, wird der x:Name-Attributwert eines VisualState auch durch die From - oder To-Werte einer VisualTransition referenziert. In diesem Fall gibt der Name den Zustand oder die Zustände an, zwischen denen die VisualTransition Zwischenwerte bereitgestellt werden.

Der x:Name-Attributwert , den Sie für einen VisualState angeben, muss innerhalb des XAML-Steuerelements eindeutig sein, in dem der VisualState vorhanden ist. Der Bereich für Zustandsnamen ist nicht nur für jede VisualStateGroup festgelegt, er ist auf alle visuellen Zustände in der Vorlage ausgerichtet. Beispielsweise können Sie nicht zwei unterschiedliche Zustände mit dem Namen "Fokussiert" in derselben Vorlagen-XAML definieren, auch wenn sie sich in unterschiedlichen Gruppen befinden.

Sie müssen das x:Name-Attribut verwenden, um einen visuellen Zustand oder eine Visuals-Statusgruppe zu benennen. das nicht eingestellte Attribut "Name" funktioniert nicht. VisualState und VisualStateGroup verfügen jeweils über eine Name Eigenschaft, die jedoch schreibgeschützt ist. Diese Name Eigenschaft ist für erweiterte Szenarien vorhanden, in denen Code verwendet wird, um den Inhalt einer Steuerelementvorlage zur Laufzeit zu untersuchen, nicht für die Einstellung über XAML.

Ersetzen der Steuerelementvorlage eines vorhandenen Steuerelements

Wenn Sie ein App-Entwickler sind, der ein Steuerelement in Ihrer App-Benutzeroberfläche verwendet, können Sie die Steuerelementvorlage ersetzen, indem Sie die Control.Template-Eigenschaft auf einen anderen Wert festlegen. Alternativ können Sie die Vorlage ersetzen, indem Sie eine neue Formatvorlage deklarieren, die den impliziten Stilschlüssel für dieses Steuerelement verwendet. Weitere Informationen zu diesen Konzepten finden Sie unter XAML-Steuerelementvorlagen.

Wenn Sie eine Steuerelementvorlage ersetzen, ist es wichtig, dass Sie alle vorhandenen benannten VisualState Elemente aus dem Inhalt der ursprünglichen Steuerelementvorlage VisualStateManager.VisualStateGroups in XAML reproduzieren. Der Steuerelementcode (den Sie nicht ändern) ruft GoToState auf. Zustände mit diesen Namen müssen in der Steuerelementvorlage vorhanden sein. Eine Anforderung für einen Fehlenden VisualState löst keine Ausnahmen aus, aber häufig bleibt das Steuerelement in einem visuellen Zustand, der für den Benutzer verwirrend ist. Wenn Sie beispielsweise für ein VisualStateCheckBox-Steuerelement kein "Überprüft" angeben, wird kein visuelles Feedback angezeigt, wenn der Benutzer das Steuerelement auswählt. Der Benutzer erwartet, dass es visuell etwas anderes gibt, um ein aktiviertes CheckBox von einem deaktivierten CheckBoxzu unterscheiden. Ein Fehler beim Reproduzieren der visuellen Zustände seitens des App-Entwicklers führt also dazu, dass das Steuerelement für den Benutzer fehlerhaft erscheint.

Wenn Sie eine IDE wie Microsoft Visual Studio verwenden, bieten die Aktionen, die Sie zum Ersetzen einer Steuerelementvorlage verwenden, die Option, mit einer Kopie des ursprünglichen VORLAGEN-XAML zu beginnen, sodass Sie alle ursprünglichen benannten VisualState Elemente und andere Steuerelementkompositionen sehen können, die Sie ersetzen. Es ist am besten, mit Vorlagenkopien zu beginnen und diese dann zu ändern, damit Sie nicht versehentlich einen erwarteten visuellen Zustand aus Der neuen Vorlage weglassen.

Attributieren der benannten visuellen Zustände eines benutzerdefinierten Steuerelements

Wenn Sie ein benutzerdefiniertes Steuerelement definieren, das visuelle Zustände im XAML-Code der Steuerelementvorlage aufweist, empfiehlt es sich, die Steuerelementklasse zu attributieren, um steuerelementbasierten Consumern anzugeben, welche visuellen Zustände verfügbar sind. Wenden Sie hierzu mindestens ein TemplateVisualState-Attribut auf der Klassenebene Ihres Steuerelementdefinitionscodes an. Jedes Attribut sollte das x:Name-Attribut des Zustands angeben. Dabei handelt es sich um den Wert, den stateName ein Steuerelement consumer in einem GoToState-Aufruf übergeben würde, um diesen visuellen Zustand zu verwenden. Wenn der VisualState Teil einer VisualStateGroup ist, sollte dies auch in Ihren Attributwerten angegeben werden.

Konstruktoren

VisualState()

Initialisiert eine neue instance der VisualState-Klasse.

Eigenschaften

Dispatcher	Gibt immer in einer Windows App SDK-App zurück`null`. Verwenden Sie stattdessen DispatcherQueue . (Geerbt von DependencyObject)
DispatcherQueue	Ruft den `DispatcherQueue` ab, dem dieses Objekt zugeordnet ist. Stellt `DispatcherQueue` eine Funktion dar, die auf den `DependencyObject` im UI-Thread zugreifen kann, auch wenn der Code von einem Nicht-UI-Thread initiiert wird. (Geerbt von DependencyObject)
Name	Ruft den Namen des VisualState ab.
Setters	Ruft eine Auflistung von Setter-Objekten ab, die diskrete Eigenschaftswerte definieren, die die Darstellung von UIElements steuern, wenn dieser VisualState angewendet wird.
StateTriggers	Ruft eine Auflistung von StateTriggerBase-Objekten ab, die angeben, wann dieser VisualState angewendet werden soll. Wenn (nicht alle) der Trigger aktiv sind, wird der `VisualState` angewendet.
Storyboard	Ruft ein Storyboard ab , das zustandsspezifische Eigenschaftswerte und die Darstellung des Steuerelements definiert, wenn es diesen visuellen Zustand verwendet, oder legt dieses fest.

Methoden

ClearValue(DependencyProperty)	Löscht den lokalen Wert einer Abhängigkeitseigenschaft. (Geerbt von DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Gibt einen beliebigen Basiswert zurück, der für eine Abhängigkeitseigenschaft festgelegt wurde, was in Fällen gilt, in denen eine Animation nicht aktiv ist. (Geerbt von DependencyObject)
GetValue(DependencyProperty)	Gibt den aktuellen effektiven Wert einer Abhängigkeitseigenschaft aus einem DependencyObject zurück. (Geerbt von DependencyObject)
ReadLocalValue(DependencyProperty)	Gibt den lokalen Wert einer Abhängigkeitseigenschaft zurück, wenn ein lokaler Wert festgelegt ist. (Geerbt von DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registriert eine Benachrichtigungsfunktion zum Lauschen auf Änderungen an einer bestimmten DependencyProperty für dieses DependencyObject-instance. (Geerbt von DependencyObject)
SetValue(DependencyProperty, Object)	Legt den lokalen Wert einer Abhängigkeitseigenschaft für ein DependencyObject fest. (Geerbt von DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Bricht eine Änderungsbenachrichtigung ab, die zuvor registriert wurde, indem RegisterPropertyChangedCallback aufgerufen wurde. (Geerbt von DependencyObject)

Gilt für: