VisualState 类

定义

命名空间:

Windows.UI.Xaml

表示 UI 元素处于特定状态时的视觉外观。 视觉状态使用 Setters 或 Storyboard 在定义 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 对象。 按钮还定义了一个名为“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 应将哪个状态用作当前状态。 为每个 VisualState 指定一个 x：Name 属性 ，该属性需要使用代码中的 GoToState 调用手动应用。 如果使用 StateTriggers 从标记自动触发 VisualState，则无需在该 VisualState 上指定 x：Name 属性 。

如果使用视觉转换，VisualTransition 的 From 或 To 值也会引用 VisualState 的 x：Name 属性值。 在这种情况下，名称标识 VisualTransition 提供中间值之间的状态或状态。

为 VisualState 指定的 x：Name 属性值 在 VisualState 存在的控件模板 XAML 中必须是唯一的。 状态名称的范围不仅仅限于每个 VisualStateGroup，还限定为模板中的所有视觉状态。 例如，不能在同一模板 XAML 中定义两个名为“重点”的不同状态，即使它们位于不同的组中。

必须使用 x：Name 属性 来命名视觉对象状态组或视觉对象状态组;未设置的属性“Name”将不起作用。 VisualState 和 VisualStateGroup 各有 一个 Name 属性，但这些属性是只读的。 该 Name 属性存在于使用代码在运行时检查控件模板内容的高级方案，而不是用于从 XAML 进行设置。

替换现有控件的控件模板

如果你是应用开发人员，在应用 UI 中使用控件，可以通过将 Control.Template 属性设置为其他值来替换控件模板。 或者，可以通过声明使用该控件的隐式样式键的新样式来替换模板。 有关这些概念的详细信息，请参阅 快速入门：控件模板。

替换控件模板时，请务必在 XAML 中从原始控件模板的 VisualStateManager.VisualStateGroups 内容中重现所有现有的名为 VisualState 元素。 未修改) 调用 GoToState 的控件代码 (。 具有这些名称的状态必须存在于控件模板中。 缺少 VisualState 的请求不会引发异常，但它通常会使控件处于视觉状态，这会使用户感到困惑。 例如，如果不为 CheckBox 控件提供名为“Checked”的 VisualState，则当用户选择控件时不会显示视觉反馈。 用户会期望有一些在视觉上不同的东西来区分选中的 CheckBox 与未选中的 CheckBox。 因此，如果无法重现应用开发人员的视觉状态，则用户似乎将控件损坏。

使用 IDE（如 Microsoft Visual Studio）时，用于替换控件模板的操作提供了从原始模板 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)