XamlLight 類別

定義

命名空間:

Microsoft.UI.Xaml.Media

提供基類，用來建立使用 CompositionLight 將光源效果套用至 XAML 元素和筆刷的 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 Brushes 為目標的方法、將光線套用至 UIElements 的樹狀結構，以及根據目前是否正在使用 CompositionLight 資源的存留期來協助管理 CompositionLight 資源的存留期。

自定義 XamlLights 可以與衍生自 XamlCompositionBrushBase 的自定義 Brushes 搭配使用，使用 SceneLightingEffect 控制 XamlLight 所光線時元素的反射屬性。

目標物件

如果您將目標設為具有 XamlLight 的Brush，則使用該 Brush 之任何 UIElement 的各部分都會透過光源亮起。

如果您將目標設為具有 XamlLight 的UIElement，則整個 UIElement 和其子 UIElement 都會透過光源亮起。

您可以在 XamlLight 實例上呼叫方法來新增和移除目標。 XamlLights 也可以定義 自定義附加屬性 ，以新增和移除標記中的目標。

管理資源

建立 XamlLight 時，通常會延遲建立 CompositionLight 和任何相關資源，直到使用光線為止。 當 XamlLight 第一次用來以螢幕上的專案或筆刷為目標時，就會呼叫 OnConnected 方法，因此您可以覆寫 OnConnected ，只在需要資源時安全地建立資源。

當組合資源不再使用時，也是一個很好的做法。 當 XamlLight 實例不再使用在螢幕上的任何位置時，就會呼叫 OnDisconnected 方法，因此您可以覆寫 OnDisconnected 以安全地處置資源。 如果在中斷聯機之後再次使用 XamlLight，則會再次呼叫 OnConnected 。

警告

在 Windows 10 Creators Update (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 。 標識碼是用來新增和移除 Brushes 和 UIElements 作為特定光線類型的目標。
GetValue(DependencyProperty)	從 DependencyObject 傳回相依性屬性的目前有效值。 (繼承來源 DependencyObject)
OnConnected(UIElement)	當 XamlLight 第一次在畫面上使用時，或在先前中斷連線之後，再再次使用時，會自動呼叫這個方法。 這可讓您只在需要時建立資源，例如 CompositionLight。 當 XamlLight 不再用來亮起任何 UIElement 或 Brush 時，將會呼叫 OnDisconnected。
OnDisconnected(UIElement)	當 XamlLight 不再使用螢幕上的任何位置時，會自動呼叫這個方法。 這可讓您在目前不需要時安全地處置資源，例如 CompositionLight。 如果 XamlLight 稍後用來在中斷連線之後啟動任何 UIElement 或 Brushes，則會再次呼叫 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
• CompositionLight
• 搭配 XAML 使用組合視覺層
• 組合光源