VisualState 類別

定義

命名空間:

Windows.UI.Xaml

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

public ref class VisualState sealed : DependencyObject

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

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
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

屬性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute ContentPropertyAttribute

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

範例

本範例會在名為「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 屬性 但未在 Storyboard中指定任何專案的 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值也會參考 VisualState 的x：Name 屬性值。 在此情況下，此名稱會識別 VisualTransition 在 之間提供中繼值的狀態或狀態。

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

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

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

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

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

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

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

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

建構函式

VisualState()

初始化 VisualState 類別的新實例。

屬性

Dispatcher	取得與此物件相關聯的 CoreDispatcher 。 CoreDispatcher代表可以存取 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)

另請參閱

• DependencyObject
• VisualStateGroup
• 視覺狀態的腳本動畫
• 腳本動畫
• x:Name 屬性
• 快速入門：控制項範本
• XAML 控制項和應用程式樣式範例
• 主要/詳細資料範例 (Windows 10)