VisualStateManager 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

Verwaltet visuelle Zustände und die Logik für Übergänge zwischen visuellen Zuständen für Steuerelemente. Stellt auch die Unterstützung der angefügten Eigenschaft für VisualStateManager.VisualStateGroupsbereit, wodurch Sie visuelle Zustände in XAML für eine Steuerelementvorlage definieren.

/// [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 VisualStateManager : DependencyObject

[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 class VisualStateManager : DependencyObject

Public Class VisualStateManager
Inherits DependencyObject

Vererbung: Object IInspectable DependencyObject VisualStateManager

Attribute: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Beispiele

In diesem Beispiel wird gezeigt, wie die VisualStateManager.VisualStateGroups angefügte XAML-Eigenschaft verwendet wird. Beachten Sie, dass andernfalls kein "VisualStateManager"-Tag definiert ist. Enthält vom Konzept her VisualStateManager.VisualStateGroups die visuellen Zustände für ein Steuerelement als unmittelbar untergeordnetes Tag des Vorlagenstamms in einer Steuerelementvorlage.

Der bestimmte Satz visueller Zustände enthält eine VisualStateGroup namens "CommonStates", die die VisualState-Objekte "PointerOver" und "Normal" definiert. Wenn der Benutzer den Mauszeiger über die Schaltfläche legt, ändert sich das Raster in 0,5 Sekunden von grün in rot. Wenn der Benutzer den Zeiger von der Schaltfläche weg bewegt, wechselt das Raster sofort wieder in grün.

<ControlTemplate TargetType="Button">
  <Grid >
    <VisualStateManager.VisualStateGroups>
      <VisualStateGroup x:Name="CommonStates">

        <VisualStateGroup.Transitions>

          <!--Take one half second to transition to the PointerOver state.-->
          <VisualTransition To="PointerOver" 
                              GeneratedDuration="0:0:0.5"/>
        </VisualStateGroup.Transitions>
        
        <VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, ButtonBrush, to red when the
            Pointer is over the button.-->
        <VisualState x:Name="PointerOver">
          <Storyboard>
            <ColorAnimation Storyboard.TargetName="ButtonBrush" 
                            Storyboard.TargetProperty="Color" To="Red" />
          </Storyboard>
        </VisualState>
      </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
    <Grid.Background>
      <SolidColorBrush x:Name="ButtonBrush" Color="Green"/>
    </Grid.Background>
  </Grid>
</ControlTemplate>

<common:LayoutAwarePage>
  <Grid>
...
    <VisualStateManager.VisualStateGroups>
    <!-- Visual states reflect the application's window size -->
      <VisualStateGroup>
        <VisualState x:Name="DefaultLayout">
           <Storyboard>
           </Storyboard>
        </VisualState>
        <VisualState x:Name="Below768Layout">
           <Storyboard>
             <ObjectAnimationUsingKeyFrames Storyboard.TargetProperty="(FrameworkElement.Margin)"
               Storyboard.TargetName="ContentRoot">
               <DiscreteObjectKeyFrame KeyTime="0">
                 <DiscreteObjectKeyFrame.Value>
                   <Thickness>20,20,20,20</Thickness>
                 </DiscreteObjectKeyFrame.Value>
               </DiscreteObjectKeyFrame>
             </ObjectAnimationUsingKeyFrames>
             <ObjectAnimationUsingKeyFrames Storyboard.TargetProperty="(FrameworkElement.HorizontalAlignment)"
               Storyboard.TargetName="FooterPanel">
               <DiscreteObjectKeyFrame KeyTime="0">
                 <DiscreteObjectKeyFrame.Value>
                    <HorizontalAlignment>Left</HorizontalAlignment>
                 </DiscreteObjectKeyFrame.Value>
               </DiscreteObjectKeyFrame>
             </ObjectAnimationUsingKeyFrames>
           </Storyboard>
         </VisualState>
       </VisualStateGroup>
     </VisualStateManager.VisualStateGroups>
   </Grid>
</common:LayoutAwarePage>

Der nächste Codeausschnitt ist der Code, der mit dem XAML-Code übereinstimmt und zeigt, wie eine App die Breite des App-Fensters erkennen und diese Informationen verwenden kann, um den entsprechenden visuellen Zustand aufzurufen.

String state = (Window.Current.Bounds.Width > 768) ? "DefaultLayout" : "Below768Layout";
VisualStateManager.GoToState(this, state, false); // 'this' is the LayoutAwarePage, scope is page code-behind

Hinweise

VisualStateManager unterstützt zwei wichtige Features für Steuerelementautoren und für App-Entwickler, die eine benutzerdefinierte Vorlage auf ein Steuerelement anwenden:

Steuerelementautoren oder App-Entwickler fügen visualStateGroup-Objektelemente dem Stammelement einer Steuerelementvorlagendefinition in XAML mithilfe der VisualStateManager.VisualStateGroups angefügten Eigenschaft hinzu. Innerhalb eines VisualStateGroup Elements stellt jeder VisualState einen diskreten visuellen Zustand eines Steuerelements dar. Jedes VisualState hat einen Namen, der für einen Benutzeroberflächenzustand steht, der vom Benutzer geändert oder durch Steuerelementlogik geändert werden kann. Ein VisualState besteht hauptsächlich aus einem Storyboard. Dies Storyboard zielt auf Änderungen einzelner Abhängigkeitseigenschaften ab, die angewendet werden sollen, wenn sich das Steuerelement in diesem visuellen Zustand befindet.
Steuerelementautoren oder App-Entwickler wechseln zwischen diesen Zuständen, indem sie die statische GoToState-Methode von VisualStateManageraufrufen. Steuerelementautoren tun dies, wenn die Steuerelementlogik Ereignisse verarbeitet, die auf eine Zustandsänderung hinweisen, oder die Steuerungslogik initiiert eine Zustandsänderung selbst. Es ist häufiger, dass Steuerelementdefinitionscode dies anstelle von App-Code tut, sodass alle möglichen visuellen Zustände und deren Übergänge und Triggerbedingungen standardmäßig für App-Code vorhanden sind und die Logik vom Steuerelement gekapselt wird.

Die meisten Entwickler verwenden nur zwei der VisualStateManager APIs: VisualStateManager.VisualStateGroupsund GoToState, wie oben beschrieben. Die verbleibenden APIs dienen alle zur Unterstützung von Erweiterungen und zum Erstellen eines benutzerdefinierten VisualStateManager. Weitere Informationen finden Sie im Abschnitt "Custom VisualStateManager" in diesem Thema.

Wenn Sie Kopien von Formatvorlagen bearbeiten, wie von der XAML-Entwurfsoberfläche von Microsoft Visual Studio aktiviert, werden die visuellen Zustände aus der Standardvorlage in dem XAML-Code definiert, den Sie bearbeiten. Stellen Sie sicher, dass Sie diese Zustände nicht löschen oder ihre Namen ändern, da die Steuerelementlogik erwartet, dass diese visuellen Zustände in der Vorlage vorhanden sind.

Zusätzlich zu den visuellen Zuständen umfasst das visuelle Zustandsmodell auch Übergänge. Übergänge sind Animationsaktionen, die von einem Storyboard gesteuert werden und zwischen jedem visuellen Zustand auftreten, wenn der Zustand geändert wird. Der Übergang kann für jede Kombination aus Startzustand und Endzustand unterschiedlich definiert werden, wie durch den Satz visueller Zustände Ihres Steuerelements definiert. Übergänge werden durch die Transitions-Eigenschaft von VisualStateGroupdefiniert, in XAML mithilfe der Eigenschaftenelementsyntax. Die meisten Standardsteuerelementvorlagen definieren keine Übergänge. Wenn keine speziell definierten Übergänge vorhanden sind, erfolgen die Übergänge zwischen Zuständen sofort (Nulldauer). Weitere Informationen finden Sie unter VisualTransition.

Benutzerdefinierter VisualStateManager

Wenn Sie Ihre eigene Logik für Übergänge zwischen Zuständen implementieren möchten (ein erweitertes Szenario), können Sie eine Klasse erstellen, die von VisualStateManagererbt. Beachten Sie diese Vorgaben:

Die abgeleitete Klasse sollte die geschützte GoToStateCore-Methode überschreiben. Jede instance der benutzerdefinierten VisualStateManager verwendet diese Core-Logik, wenn die GoToState-Methode aufgerufen wird.
Um auf Ihre benutzerdefinierte VisualStateManager Klasse zu verweisen, legen Sie den Wert der VisualStateManager.CustomVisualStateManager angefügten Eigenschaft für das Stammelement einer ControlTemplate fest, in dem Sie das verhalten der benutzerdefinierten VisualStateManager Klasse verwenden möchten, zusammen mit der Verwendung der VisualStateManager.VisualStateGroups angefügten Eigenschaft, die die visuellen Zustände für die Vorlage definiert. In der Regel erstellen Sie eine instance der benutzerdefinierten VisualStateManager Klasse über die standardmäßige XAML-Konstruktion in Application.Resources. Anschließend wird die VisualStateManager.CustomVisualStateManager angefügte Eigenschaft mithilfe eines {StaticResource}-Markuperweiterungsverweis auf den Schlüssel der benutzerdefinierten VisualStateManager Ressource festgelegt.

Dies sind die grundlegenden Anforderungen für das Erstellen und Verwenden eines benutzerdefinierten VisualStateManager. Sie können auch einige weitere Verhaltensweisen außer Kraft setzen:

Überschreiben Sie RaiseCurrentStateChanged , um zu steuern, wann das CurrentStateChanged-Ereignis von einer VisualStateGroup ausgelöst wird, die VisualStateManagervon verwaltet wird.
Überschreiben Sie RaiseCurrentStateChanging , um zu steuern, wann das CurrentStateChanging-Ereignis von einer VisualStateGroup ausgelöst wird, die VisualStateManagervon verwaltet wird.
Überschreiben oder überladen Sie den Konstruktor, wenn Ihre benutzerdefinierte Klasse zusätzliche Informationen zum Initialisieren benötigt.

Alle anderen APIs (CustomVisualStateManagerProperty, GetCustomVisualStateManager, GetVisualStateGroups, SetCustomVisualStateManager) sind infrastrukturell für die Unterstützung angefügter Eigenschaften, und Sie müssen sie nicht aufrufen oder mit ihnen umgehen.

Visuelle Zustände für Elemente, die keine Steuerelemente sind

Visuelle Zustände sind manchmal nützlich für Szenarien, in denen Sie den Zustand eines Bereichs der Benutzeroberfläche ändern möchten, der nicht sofort eine Control-Unterklasse ist. Dies ist nicht direkt möglich, da der Steuerelementparameter der GoToState-Methode eine Control Unterklasse erfordert, die auf das Objekt verweist, auf das visualStateManager reagiert. Page ist eine Control Unterklasse, und es ist ziemlich selten, dass Die Benutzeroberfläche in einem Kontext angezeigt wird, in dem Sie keine haben Pageoder ihr Window.Content-Stamm keine Control Unterklasse ist. Es wird empfohlen, ein benutzerdefiniertes UserControl-Steuerelement zu definieren, um entweder als Window.Content Stamm oder als Container für andere Inhalte zu dienen, auf die Sie Zustände anwenden möchten (z. B. ein Panel). Anschließend können Sie GoToState für Ihren UserControl - und anwenden-Zustand aufrufen, unabhängig davon, ob der Rest des Inhalts ein Controlist. Beispielsweise könnten Sie visuelle Zustände auf die Benutzeroberfläche anwenden, die andernfalls nur aus einem SwapChainPanel besteht, solange Sie diese innerhalb ihrer UserControl und deklarierten benannten Zustände platziert haben, die für die Eigenschaften des übergeordneten UserControl oder des benannten SwapChainPanel Teils der Vorlage gelten.

Angefügte XAML-Eigenschaften

VisualStateManager ist die Hostdienstklasse für mehrere angefügte XAML-Eigenschaften.

Um den XAML-Prozessorzugriff auf die angefügten Eigenschaften zu unterstützen und auch gleichwertige Get - und Set-Vorgänge für Code verfügbar zu machen, verfügt jede angefügte XAML-Eigenschaft über ein Paar von Get - und Set -Accessormethoden. Eine weitere Möglichkeit zum Abrufen oder Festlegen des Werts im Code besteht darin, das Abhängigkeitseigenschaftensystem zu verwenden, entweder GetValue oder SetValue aufzurufen und das Bezeichnerfeld als Abhängigkeitseigenschaftsbezeichner zu übergeben.

Angefügte Eigenschaft	BESCHREIBUNG
Visualstategroups	Ruft die Auflistung von VisualStateGroup-Elementen ab, die durch ein Stammelement einer Vorlagendefinition definiert werden. Ein Steuerelement definiert dies in der Regel als Teil seiner Vorlage. Typ: VisualStateGroup Bezeichnerfeld: N/A Accessormethoden: GetVisualStateGroups Wenn Sie diese Eigenschaft im Code abrufen, verwenden Sie GetVisualStateGroups. Dadurch wird ein Auflistungsobjekt zurückgegeben, dem Sie Elemente hinzufügen können. Dies entspricht dem XAML-Verarbeitungsverhalten aller untergeordneten Elemente einer VisualStateManager.VisualStateGroups-Eigenschaft. Da für diese bestimmte angefügte Eigenschaft kein öffentlicher Abhängigkeitseigenschaftsbezeichner vorhanden ist, können Sie getValue nicht verwenden, um diesen angefügten Eigenschaftswert abzurufen. Sie müssen immer GetVisualStateGroups verwenden.
CustomVisualStateManager	Ruft das benutzerdefinierte VisualStateManager-Objekt ab, das Übergänge zwischen den Zuständen eines Steuerelements behandelt, oder legt es fest. Typ: VisualStateManager Bezeichnerfeld: CustomVisualStateManagerProperty Accessormethoden: GetCustomVisualStateManager, SetCustomVisualStateManager Diese angefügte Eigenschaft ist nur für Fälle erforderlich, in denen Sie eine benutzerdefinierte Implementierungsklasse verwenden möchten, um die visuellen Zustandsänderungen Ihrer App zu behandeln, anstatt die standardmäßige VisualStateManager-Klasse, die vom Windows-Runtime implementiert wird. Wenn Sie keine benutzerdefinierte Implementierung verwenden möchten, müssen Sie diese Eigenschaft nicht festlegen.

Angefügte Eigenschaft

BESCHREIBUNG

Visualstategroups

Ruft die Auflistung von VisualStateGroup-Elementen ab, die durch ein Stammelement einer Vorlagendefinition definiert werden. Ein Steuerelement definiert dies in der Regel als Teil seiner Vorlage.

Typ: VisualStateGroup
Bezeichnerfeld: N/A
Accessormethoden: GetVisualStateGroups

Wenn Sie diese Eigenschaft im Code abrufen, verwenden Sie GetVisualStateGroups. Dadurch wird ein Auflistungsobjekt zurückgegeben, dem Sie Elemente hinzufügen können. Dies entspricht dem XAML-Verarbeitungsverhalten aller untergeordneten Elemente einer VisualStateManager.VisualStateGroups-Eigenschaft.

Da für diese bestimmte angefügte Eigenschaft kein öffentlicher Abhängigkeitseigenschaftsbezeichner vorhanden ist, können Sie getValue nicht verwenden, um diesen angefügten Eigenschaftswert abzurufen. Sie müssen immer GetVisualStateGroups verwenden.

CustomVisualStateManager

Ruft das benutzerdefinierte VisualStateManager-Objekt ab, das Übergänge zwischen den Zuständen eines Steuerelements behandelt, oder legt es fest.

Typ: VisualStateManager
Bezeichnerfeld: CustomVisualStateManagerProperty
Accessormethoden: GetCustomVisualStateManager, SetCustomVisualStateManager

Diese angefügte Eigenschaft ist nur für Fälle erforderlich, in denen Sie eine benutzerdefinierte Implementierungsklasse verwenden möchten, um die visuellen Zustandsänderungen Ihrer App zu behandeln, anstatt die standardmäßige VisualStateManager-Klasse, die vom Windows-Runtime implementiert wird. Wenn Sie keine benutzerdefinierte Implementierung verwenden möchten, müssen Sie diese Eigenschaft nicht festlegen.

Konstruktoren

VisualStateManager()

Initialisiert eine neue instance der VisualStateManager-Klasse.

Eigenschaften

CustomVisualStateManagerProperty	Identifiziert die VisualStateManager.CustomVisualStateManager-Abhängigkeitseigenschaft .
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)

Angefügte Eigenschaften