Share via

VisualState 类

  • 参考

定义

命名空间:
Microsoft.UI.Xaml
编辑

表示 UI 元素处于特定状态时的视觉外观。 视觉状态使用 Setters 或 Storyboard 在定义 的页面或控件模板 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 在根的第一个子级下声明，以便触发器自动生效。

默认状态

定义 VisualState 具有 x：Name 属性 但未在 情节提要中指定任何内容的 是合法的， 很常见。 这很有用， VisualState 因为此类 将使用默认模板中存在的任何值。 然后，可以从 GoToState 调用中专门请求空状态。 当空状态变为当前状态时，将取消对同一 VisualStateGroup 中以前视觉状态所做的所有模板属性修改。

使用 StateTriggers 时，不再需要创建一个空 VisualState 来调用 GoToState 。 当 不再满足 StateTrigger 的条件时，将自动删除对相应 VisualState 属性所做的所有修改，并且默认标记中提供的值将生效。

VisualState 和 x：Name

GoToState 方法 (通常从控件代码调用) 需要参数stateName来通知 VisualStateManager 哪个状态应用作当前状态。 为每个VisualState需要使用GoToState代码调用手动应用的 x：Name 属性指定。 如果使用 StateTriggers 从标记自动触发 VisualState ，则无需在该 VisualState 上指定 x：Name 属性 。

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

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

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

替换现有控件的控件模板

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

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

使用 IDE（如 Microsoft Visual Studio）时，用于替换控件模板的操作提供了从原始模板 XAML 的副本开始的选项，以便你可以看到要替换的所有原始命名 VisualState 元素和其他控件组合。 最好先从模板副本开始，然后修改它们，这样就不会意外地从新模板中省略预期的视觉状态。

归因自定义控件的命名视觉状态

如果要定义在其控件模板 XAML 中具有视觉状态的自定义控件，最佳做法是将控件类特性化，以向控件使用者指示哪些视觉状态可用。 为此，请在控件定义代码的类级别应用一个或多个 TemplateVisualState 属性。 每个属性都应指定状态的 x：Name 属性，该属性是 stateName 控件使用者在 GoToState 调用中传递以使用该视觉状态的值。 VisualState如果 是 VisualStateGroup 的一部分，则还应在属性值中指示这一点。

构造函数

VisualState()

初始化 VisualState 类的新实例。

属性

Dispatcher

始终在Windows 应用 SDK应用中返回 null 。 请改用 DispatcherQueue 。

(继承自 DependencyObject)
DispatcherQueue

获取 DispatcherQueue 与此 对象关联的 。 DispatcherQueue表示可以访问 DependencyObject UI 线程上的 的功能，即使代码是由非 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)

适用于

另请参阅