XamlLight 类

定义

命名空间:

Microsoft.UI.Xaml.Media

提供用于创建 XAML 灯的基类，该类使用 CompositionLight 将照明效果应用于 XAML 元素和画笔。

/// [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 XamlLight : DependencyObject

[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 class XamlLight : DependencyObject

Public Class XamlLight
Inherits DependencyObject

继承

Object IInspectable DependencyObject XamlLight

属性

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

示例

请参阅 照明中的代码示例。

注解

可以使用 XamlLight 创建自定义灯。

例如，它可用于创建一个光，将合成 SpotLight 应用于目标元素以点亮它们。

XamlLight 提供了方法以用于面向 UIElement 或 XAML 画笔、将光应用于 UIElement 树以及帮助管理 CompositionLight 资源的生存期（根据它们当前是否已使用）。

自定义 XamlLight 可以与派生自 XamlCompositionBrushBase 的自定义画笔结合使用，这些画笔使用 SceneLightingEffect 在 XamlLight 点燃时控制元素的反射属性。

面向对象

如果使用 XamlLight 面向某个画笔，则光会照亮使用该画笔的任何 UIElement 的位置。

如果使用 XamlLight 面向某个 UIElement，则光会照亮整个 UIElement 及其子 UIElement。

可以通过在 XamlLight 实例上调用方法添加和删除目标。 XamlLights 还可以定义 自定义附加属性 ，以在标记中添加和删除目标。

管理资源

创建 XamlLight 时，通常最好延迟创建 CompositionLight 和任何相关资源，直到使用灯。 当 XamlLight 首次用于在屏幕上以元素或画笔为目标时，将调用 OnConnected 方法，因此可以替代 OnConnected ，以便仅在需要时才安全地创建资源。

当组合资源不再使用时，释放这些资源也是一种很好的做法。 当 XamlLight 实例不再在屏幕上的任何位置使用时，将调用 OnDisconnected 方法，因此你可以重写 OnDisconnected 以安全地释放资源。 如果在断开连接后再次使用 XamlLight，则将再次调用 OnConnected 。

警告

在 Windows 10 创意者更新 (SDK 15063) ，调用 Dispose 后无法访问 CompositionLight，因此调用 Dispose 后将其设置为 null 会导致错误。 若要解决此问题，可以将 CompositionLight 保存到临时变量，并在将 CompositionLight 设置为 null 后在该变量上调用 Dispose。 var temp = CompositionLight; CompositionLight = null; temp.Dispose(); 此问题在 SDK 的更高版本中已修复。 有关如何面向不同 SDK 版本的信息，请参阅 版本自适应应用 。

构造函数

XamlLight()

初始化 XamlLight 类的新实例。

属性

CompositionLight	获取或设置用于应用照明效果的 CompositionLight 实例。
Dispatcher	始终在Windows 应用 SDK应用中返回 null 。 请改用 DispatcherQueue 。 (继承自 DependencyObject)
DispatcherQueue	DispatcherQueue获取与此对象关联的 。 表示 DispatcherQueue 一个可以在 UI 线程上访问 DependencyObject 的设施，即使代码是由非 UI 线程启动的。 (继承自 DependencyObject)

方法

AddTargetBrush(String, Brush)	将 Brush 设置为 XamlLight 的目标。
AddTargetElement(String, UIElement)	将 UIElement 设置为 XamlLight 的目标。
ClearValue(DependencyProperty)	清除依赖属性的本地值。 (继承自 DependencyObject)
GetAnimationBaseValue(DependencyProperty)	返回为依赖属性建立的任何基值，该基值适用于动画未处于活动状态的情况。 (继承自 DependencyObject)
GetId()	返回自定义 XamlLight 类型的标识符。 在大多数情况下，应使用唯一标识符来防止冲突。 例如，可以使用自定义 XamlLight 类型的 FullName 。 标识符用于添加和删除画笔和 UIElement 作为特定光线类型的目标。
GetValue(DependencyProperty)	从 DependencyObject 返回依赖属性的当前有效值。 (继承自 DependencyObject)
OnConnected(UIElement)	当 XamlLight 首次在屏幕上使用时，或者在之前断开连接后再次使用时，会自动调用此方法。 这样就有机会仅在需要时创建 CompositionLight 等资源。 当 XamlLight 不再用于点亮任何 UIElements 或 Brushs 时，将调用 OnDisconnected。
OnDisconnected(UIElement)	当 XamlLight 不再在屏幕上的任何位置使用时，会自动调用此方法。 这样就有机会在当前不需要时安全处置 CompositionLight 等资源。 如果 XamlLight 稍后在断开连接后点亮任何 UIElement 或 Brush，则将再次调用 OnConnected。
ReadLocalValue(DependencyProperty)	如果设置了本地值，则返回依赖属性的本地值。 (继承自 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	注册通知函数，用于侦听此 DependencyObject 实例上对特定 DependencyProperty 的更改。 (继承自 DependencyObject)
RemoveTargetBrush(String, Brush)	阻止 画笔 成为 XamlLight 的目标。
RemoveTargetElement(String, UIElement)	阻止 UIElement 成为 XamlLight 的目标。
SetValue(DependencyProperty, Object)	设置 DependencyObject 上依赖属性的本地值。 (继承自 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消以前通过调用 RegisterPropertyChangedCallback 注册的更改通知。 (继承自 DependencyObject)

另请参阅

• Lights
• CompositionLight
• 将组合视觉层与 XAML 配合使用
• 合成光线