VisualState 類別

參考

定義

命名空間:: Microsoft.UI.Xaml

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

表示 UI 元素處於特定狀態時的視覺外觀。視覺狀態會使用 Setter 或分鏡腳本，在定義的頁面或控制項範本 VisualState 內設定 UI 屬性。

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>

繼承: Object Platform::Object IInspectable DependencyObject VisualState

屬性: ContentPropertyAttribute ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

範例

本範例會在名為「CommonStates」的 Button ControlTemplate中建立VisualStateGroup，並為狀態、「Normal」、「Pressed」和「PointerOver」新增 VisualState 物件。也會 Button 定義名為「Disabled」的狀態，該狀態位於名為 VisualStateGroup的「CommonStates」中，但範例會省略它以求簡潔。

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

備註

元素 VisualState 一律必須包含在 XAML 標記中的 VisualStateGroup 父代內。 VisualStateGroup具有隱含集合屬性States，因此您可以將每個 VisualState 屬性放在父代的 VisualStateGroup 立即子專案。例如：

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

當您使用 StateTriggers時，請確定 VisualStateGroup 是在根目錄的第一個子系下宣告，以便觸發程式自動生效。

預設狀態

定義具有x：Name 屬性但未在分鏡腳本中指定任何專案的，是合法的且常見的 VisualState 。這很有用，因為這樣 VisualState 會使用預設範本中存在的任何值。然後，您可以從 GoToState 呼叫特別要求空白狀態。當空狀態變成目前狀態時，會取消對相同 VisualStateGroup上一個視覺狀態所建立之範本屬性的所有修改。

當您使用 StateTriggers時，不再需要建立空白 VisualState 來呼叫 GoToState 。當已不再符合 StateTrigger 的條件時，會自動移除對對應 VisualState 所做屬性所做的所有修改，而預設標記中提供的值就會生效。

VisualState 和 x：Name

GoToState方法 (通常會從控制項程式碼) 呼叫，需要 stateName 參數來通知VisualStateManager應該使用哪個狀態作為目前狀態。針對需要使用程式碼呼叫手動套用 GoToState 的每個 VisualState ，指定x：Name 屬性。如果您使用 StateTriggers 自動觸發標記中的 VisualState ，則不需要在該 VisualState 上指定 x：Name 屬性。

如果您使用視覺轉換，VisualTransition的From或To值也會參考的 VisualStatex：Name 屬性值。在此情況下，名稱會識別提供之間中繼值的狀態或狀態 VisualTransition 。

您為指定的 VisualStatex：Name 屬性值在存在的 VisualState 控制項範本 XAML 內必須是唯一的。狀態名稱的範圍不只限於每個 VisualStateGroup，其範圍僅限於範本中的所有視覺狀態。例如，即使它們位於不同的群組中，您也無法在相同的範本 XAML 中定義名為「Focused」的不同狀態。

您必須使用 x：Name 屬性來命名視覺狀態或視覺效果狀態群組;未取代的屬性「Name」將無法運作。 VisualState 和 VisualStateGroup 各有屬性， Name 但這些屬性是唯讀的。該 Name 屬性適用于使用程式碼在執行時間檢查控制項範本內容的進階案例，而不是從 XAML 進行設定。

取代現有控制項的控制項範本

如果您是在應用程式 UI 中使用控制項的應用程式開發人員，您可以將 Control.Template 屬性設定為不同的值來取代控制項範本。或者，您可以宣告使用該控制項之隱含樣式索引鍵的新樣式來取代範本。如需這些概念的詳細資訊，請參閱 XAML 控制項範本。

當您取代控制項範本時，請務必從原始控制項範本 VisualStateManager.VisualStateGroups 的內容中重現所有現有的具名 VisualState 元素。您未修改) 的控制項程式碼 (呼叫 GoToState。這些名稱的狀態必須存在於控制項範本中。遺失 VisualState 的要求不會擲回例外狀況，但通常會讓控制項處於視覺狀態，而對使用者造成混淆。例如，如果您未為CheckBox控制項提供 VisualState 名為「Checked」的控制項，當使用者選取控制項時，就不會顯示任何視覺回饋。使用者預期有一些視覺上不同的專案，以區分已核取 CheckBox 與未核取 CheckBox 的。因此，在應用程式開發人員的元件上重現視覺狀態失敗，會讓使用者看起來會中斷控制項。

當您使用像是 Microsoft Visual Studio 的 IDE 時，您用來取代控制項範本的動作提供從原始範本 XAML 複本開始的選項，讓您可以查看所有原始具名 VisualState 元素和其他您要取代的控制群組合。最好從範本複本開始，然後加以修改，讓您不小心省略新範本的預期視覺狀態。

設定自訂控制項的具名視覺狀態

如果您要定義在其控制項範本 XAML 中具有視覺狀態的自訂控制項，最佳作法是將控制項類別屬性設定為可控制取用者的視覺狀態。若要這樣做，請在控制項定義程式碼的類別層級套用一或多個 TemplateVisualState 屬性。每個屬性都應該指定狀態的 x：Name 屬性，也就是 stateName 控制項取用者傳入 GoToState 呼叫以使用該視覺狀態的值。 VisualState如果是VisualStateGroup的一部分，則也應該在屬性值中指出。

建構函式

VisualState()

初始化 VisualState 類別的新實例。

屬性

Dispatcher	一律會在 `null` Windows 應用程式 SDK應用程式中傳回。請改用 DispatcherQueue 。 (繼承來源 DependencyObject)
DispatcherQueue	`DispatcherQueue`取得與這個物件相關聯的。 `DispatcherQueue`表示即使程式碼是由非 UI 執行緒起始，也可以存取 `DependencyObject` UI 執行緒上的。 (繼承來源 DependencyObject)
Name	取得 VisualState的名稱。
Setters	取得Setter物件的集合，這個集合會定義離散屬性值，以控制套用這個VisualState時UIElement的外觀。
StateTriggers	取得 StateTriggerBase 物件的集合，指出何時應套用這個 VisualState 。如果任何 (並非所有觸發程式) 都處於作用中狀態， `VisualState` 將會套用。
Storyboard	取得或設定分鏡腳本，這個腳本會在使用這個視覺狀態時定義控制項的狀態特定屬性值和外觀。

方法

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)

適用於

共用方式為

VisualState 類別

定義

範例

備註

預設狀態

VisualState 和 x：Name

取代現有控制項的控制項範本

設定自訂控制項的具名視覺狀態

建構函式

屬性

方法

適用於

另請參閱

意見反應

其他資源