XamlLight 类

定义

命名空间:

Windows.UI.Xaml.Media

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

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 262144)]
/// [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(Windows.Foundation.UniversalApiContract), 262144)]
[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

Windows 要求

设备系列	Windows 10 Creators Update (在 10.0.15063.0 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v4.0 中引入)

示例

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

注解

可以使用 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 = CompostionLight; CompositionLight = null; temp.Dispose(); 此问题在更高版本的 SDK 中已修复。 有关如何面向不同 SDK 版本的信息，请参阅 版本自适应应用 。

构造函数

XamlLight()

初始化 XamlLight 类的新实例。

属性

CompositionLight	获取或设置用于应用照明效果的 CompositionLight 实例。
Dispatcher	获取与此 对象关联的 CoreDispatcher 。 CoreDispatcher 表示可以访问 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 不再用于点亮任何 UIElement 或 Brush 时，将调用 OnDisconnected。
OnDisconnected(UIElement)	当 XamlLight 不再在屏幕上的任何位置使用时，将自动调用此方法。 这提供了在当前不需要时安全处置 CompositionLight 等资源的机会。 如果稍后使用 XamlLight 在断开连接后点亮任何 UIElement 或 Brush，则将再次调用 OnConnected。
ReadLocalValue(DependencyProperty)	如果设置了本地值，则返回依赖属性的本地值。 (继承自 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	注册一个通知函数，用于侦听此 DependencyObject 实例上特定 DependencyProperty 的更改。 (继承自 DependencyObject)
RemoveTargetBrush(String, Brush)	阻止 Brush 成为 XamlLight 的目标。
RemoveTargetElement(String, UIElement)	阻止 UIElement 成为 XamlLight 的目标。
SetValue(DependencyProperty, Object)	设置 DependencyObject 上依赖属性的本地值。 (继承自 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消以前通过调用 RegisterPropertyChangedCallback 注册的更改通知。 (继承自 DependencyObject)

另请参阅

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