ControlTemplate 类

定义

定义用作控件的控件模板的元素树。

public ref class ControlTemplate sealed : FrameworkTemplate
/// [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 ControlTemplate final : FrameworkTemplate
[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 ControlTemplate : FrameworkTemplate
Public NotInheritable Class ControlTemplate
Inherits FrameworkTemplate
<ControlTemplate ...>
    templateRootElement
</ControlTemplate>
继承
Object Platform::Object IInspectable DependencyObject FrameworkTemplate ControlTemplate
属性

示例

以下示例为 Button 创建一个简单的 ControlTemplate。 控件模板包含一个 Grid 并指定以下行为:

  • 当用户将鼠标悬停在 按钮上时, 网格 会在半秒内从绿色变为红色。
  • 当用户将鼠标移开按钮时, 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>

可以在 generic.xaml 文件中查看每个 XAML 控件的完整模板。 此文件位于 (Program Files) \Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP<SDK version>\Generic 文件夹中。

注解

有关详细信息和示例,请参阅 XAML 控件模板

ControlTemplate 用作 Control.Template 属性的值,该属性通过应用模板定义控件的视觉对象。 你几乎总是使用隐式键 TargetType 将 ControlTemplate 定义为 XAML 资源,该键与使用 Setter 设置 Control.TemplateStyle 相同。 很少会直接在控件实例上为 Control.Template 分配值。

定义 ControlTemplate 时,实际上只使用两个属性: TargetType 和隐式 XAML 内容。 ControlTemplate 从其 FrameworkTemplate 父级继承隐式 XAML 内容行为。 基本上,包含在 XAML 中定义的 ControlTemplate 中的元素是为定义模板的 XAML 元素的进一步结构分配根元素。 这会设置一个“Template”属性,该属性随后无法由代码检查,并且仅对 XAML 分析程序如何基于应用该模板为控件分配内容有意义。

若要从 ControlTemplate 设置其内容,控件元素必须是真正的 Control 子类,以便它具有 Control.Template 属性。 在其他情况下,模板应用内容,但这通常涉及其他 FrameworkTemplate 派生模板类之一, (DataTemplateItemsPanelTemplate) 。

控件模板提供视觉对象和部件,这些视觉对象和部件构成在应用的 UI 中显示的控件实例。 在运行时,模板已应用,因此从模板中创建的所有部件现在都是控件的真正部分,并且可以通过从控件内容中检查 XAML 名称范围或使用 VisualTreeHelper 类等技术进行访问。 诸如输入事件之类的事件有时会公开来自已应用控件模板的控件部分。

在模板应用于特定控件实例之前或之后,可以通过多种方式访问模板定义的内容;请参阅 OnApplyTemplateGetTemplateChild

可以检测到 ControlTemplate 应用于控件实例的实际时间点,因为这会调用 OnApplyTemplate 保护的虚拟方法。 只要控件未密封,就可以对控件进行子类化,以便有机会替代 OnApplyTemplate。 可以编写此替代以执行在应用模板之前不可能执行的操作。 例如,可以将事件处理程序连接到控件部件,或设置控件属性以引用从模板中创建但未以 {TemplateBinding} 标记扩展 值开头的对象部件。

构造函数

ControlTemplate()

初始化 ControlTemplate 类的新实例。

属性

Dispatcher

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

(继承自 DependencyObject)
DispatcherQueue

获取 DispatcherQueue 与此 对象关联的 。 DispatcherQueue表示可以访问 DependencyObject UI 线程上的 的功能,即使代码是由非 UI 线程启动的。

(继承自 DependencyObject)
TargetType

获取或设置 ControlTemplate 应用于的类型。

方法

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)

适用于

另请参阅