VisualStateGroup 類別

定義

命名空間:

Microsoft.UI.Xaml

包含互斥 的 VisualState 物件和用來從某個狀態移至另一個狀態的 VisualTransition 物件。

public ref class VisualStateGroup sealed : DependencyObject

/// [Microsoft.UI.Xaml.Markup.ContentProperty(Name="States")]
/// [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 VisualStateGroup final : DependencyObject

[Microsoft.UI.Xaml.Markup.ContentProperty(Name="States")]
[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 VisualStateGroup : DependencyObject

Public NotInheritable Class VisualStateGroup
Inherits DependencyObject

<VisualStateManager.VisualStateGroups>
   <VisualStateGroup x:Name="groupname" ...>
     oneOrMoreVisualStates
   </VisualStateGroup>
   <!--- other peer VisualStateGroup's here ... -->
</VisualStateManager.VisualStateGroups>

繼承

Object Platform::Object IInspectable DependencyObject VisualStateGroup

屬性

ContentPropertyAttribute ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

範例

此範例會為包含一個Grid的Button建立簡單的ControlTemplate。 它也包含 VisualStateGroup 稱為 「CommonStates」 的 ，其定義 「PointerOver」 和 「Normal」 狀態。 VisualStateGroup也有一個 VisualTransition，指定當使用者將指標放在 上方 Button 時，需要一半秒的時間，才能 Grid 從綠色變更為紅色。

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

備註

每個 VisualStateGroup 在 XAML 中宣告為控制項範本的一部分，應該一律設定 x：Name 屬性 。 控制項樣板集合中使用的 VisualStateGroups 每個名稱字串，在該範本中必須是唯一的。 不過，對於不同的控制項，通常會使用相同的組名。 例如，幾乎所有現有的控制項範本都具有 VisualStateGroup 「 x:Name attribute CommonStates」 的 。

每個 VisualStateGroup 內的視覺狀態集合應該在群組中互斥。 換句話說，控制項應該一律使用其每個已定義 VisualStateGroup 群組的其中一個視覺狀態。 每當有一個控制項要同時處於兩種狀態的情況時，請確定這兩個狀態位於不同的群組中。 例如，下拉式控制項可以同時設為焦點，並開啟其下拉式清單。 在正確的視覺狀態設計中，您會針對每個狀態各有不同的 VisualStateGroup 狀態，以便兩者一次都處於作用中狀態。 這類群組的名稱可能如 「FocusStates」 和 「DropDownStates」。

每當您在其中一個VisualState元素中定義 VisualStateGroup 啟用暫時分鏡腳本行為的 時，請確定該群組也包含第二 VisualState 個可以呼叫以取消先前狀態的腳本行為。 這可以像宣告第二個腳本 VisualState 一樣簡單，而完全沒有 Storyboard ，只是 x：Name 屬性。

您為 VisualStateGroup 設定的x：Name 屬性值不會用於對VisualStateManager.GoToState的呼叫，而是 x:Name attribute 用於 VisualStateManager.GoToState 的VisualState 。 任何使用 VisualStateManager.GoToState 的任何人都應該知道所有可用的群組和狀態，讓每個呼叫都能正確地從舊狀態轉換為群組內的新狀態。

除了一組 VisualState 元素之外， VisualStateGroup 也可以定義一組 VisualTransition 元素，其中每個元素 VisualTransition 都至少與群組中定義的其中一個具名 VisualState 元素有關。 在 XAML 中，專案集合 VisualState 可以宣告為 的 VisualStateGroup 立即物件專案子專案。 這是可行的，因為 States 屬性是 視覺狀態的集合， 是 的 VisualStateGroup XAML 內容屬性。 相反地，若要設定視覺轉換的集合，您必須在 XAML 的 VisualStateGroup.Transitions 屬性元素內宣告該集合。 如需 XAML 內容屬性的詳細資訊，請參閱 XAML 語法指南。

使用 StateTriggers 來控制視覺狀態時，觸發程式引擎會使用下列優先順序規則來評分觸發程式，並判斷哪一個觸發程式和對應的 VisualState將會作用中：

1. 衍生自StateTriggerBase 的自訂觸發程式
2. 自適性Trigger因為MinWindowWidth而啟動
3. 自適性Trigger因為MinWindowHeight而啟動

如果一次有多個作用中觸發程式在評分 (發生衝突，也就是兩個作用中的自訂觸發程式) ，則標記檔案中宣告的第一個觸發程式優先。

注意：雖然 AdaptiveTrigger 確實衍生自 StateTriggerBase，但只能透過設定 MinWindowWidth 和/或 MinWindowHeight加以啟用。

VisualStateGroup 支援自訂 VisualStateManager 實作的 API

的許多 API VisualStateGroup 僅支援自訂 VisualStateManager 實作 。 這些包括： Name、 CurrentState、 CurrentStateChanging、 CurrentStateChanged。 控制項範本的視覺狀態最常見的用法不需要這些 API。 特別是處理事件並不一般。 控制項的大部分邏輯作業都應該包含自己的屬性和事件。 針對大部分的應用程式和控制項定義案例，控制項發生的視覺狀態變更應該只是控制項套用至其範本之邏輯的結束結果，而不是其他邏輯的觸發程式。

建構函式

VisualStateGroup()

初始化 VisualStateGroup 類別的新實例。

屬性

CurrentState	從成功呼叫 GoToState方法取得最近設定的VisualState。
Dispatcher	一律會在Windows 應用程式 SDK應用程式中傳 null 回。 請改用 DispatcherQueue 。 (繼承來源 DependencyObject)
DispatcherQueue	DispatcherQueue取得與這個 物件相關聯的 。 DispatcherQueue表示即使程式碼是由非 UI 執行緒起始，也可以存取 DependencyObject UI 執行緒上的 設備。 (繼承來源 DependencyObject)
Name	取得 VisualStateGroup的名稱。
States	取得互斥 VisualState 物件的集合。
Transitions	取得 VisualTransition 物件的集合。

方法

ClearValue(DependencyProperty)	清除相依性屬性的本機值。 (繼承來源 DependencyObject)
GetAnimationBaseValue(DependencyProperty)	傳回為相依性屬性建立的任何基底值，如果動畫未使用中，則適用此屬性。 (繼承來源 DependencyObject)
GetValue(DependencyProperty)	從 DependencyObject傳回相依性屬性的目前有效值。 (繼承來源 DependencyObject)
ReadLocalValue(DependencyProperty)	如果已設定本機值，則傳回相依性屬性的本機值。 (繼承來源 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	註冊通知函式，以接聽此DependencyObject實例上特定DependencyProperty的變更。 (繼承來源 DependencyObject)
SetValue(DependencyProperty, Object)	設定 DependencyObject上相依性屬性的本機值。 (繼承來源 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消先前透過呼叫 RegisterPropertyChangedCallback註冊的變更通知。 (繼承來源 DependencyObject)

事件

CurrentStateChanged	發生于控制項變更為不同的狀態之後。
CurrentStateChanging	發生于控制項開始變更為不同的狀態時。

另請參閱

• DependencyObject
• VisualStateManager
• VisualState
• XAML 控制項範本
• 腳本動畫
• XAML 控制項和應用程式樣式範例