SystemBackdrop 类

定义

命名空间:

Microsoft.UI.Xaml.Media

用于呈现材料（如 Mica 和 Acrylic）的自定义系统背景的基类。

public ref class SystemBackdrop : DependencyObject

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 262144)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class SystemBackdrop : DependencyObject

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 262144)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class SystemBackdrop : DependencyObject

Public Class SystemBackdrop
Inherits DependencyObject

继承

Object Platform::Object IInspectable DependencyObject SystemBackdrop

派生

Microsoft.UI.Xaml.Media.DesktopAcrylicBackdrop

Microsoft.UI.Xaml.Media.MicaBackdrop

属性

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

示例

此示例演示使用 MicaController 实现的自定义系统背景类。

调用基 OnTargetConnected 方法可初始化 GetDefaultSystemBackdropConfiguration 返回的默认配置对象，以反映影响此 SystemBackdrop 实例 (由 connectedTarget, XamlRoot) 指定的环境更改。

尽管本页上的示例不支持 MicaSystemBackdrop 共享实例 (例如， Window1.SystemBackdrop = Window2.SystemBackdrop = myMicaSystemBackdrop) ，但这种共享是可能的，并且受内置 MicaBackdrop 和 DesktopAcrylicBackdrop 材料支持。 若要在自定义材料中实现共享，请将支持 ISystemBackdropController 存储矢量化，以便为每个使用上下文保留单独的实例 (，例如，通过) 上的 connectedTarget 映射键控。 请注意， SystemBackdrop 同样会向量化 GetDefaultSystemBackdropConfiguration 返回的关联默认配置对象，确保配置在共享时 SystemBackdrop 反映每个使用上下文。

<Window
    ... >
    <Window.SystemBackdrop>
        <local:MicaSystemBackdrop/>
    </Window.SystemBackdrop>

    <!-- XAML content -->

</Window>

public class MicaSystemBackdrop : SystemBackdrop
{
    MicaController micaController;

    protected override void OnTargetConnected(ICompositionSupportsSystemBackdrop connectedTarget, XamlRoot xamlRoot)
    {
        // Call the base method to initialize the default configuration object.
        base.OnTargetConnected(connectedTarget, xamlRoot);

        // This example does not support sharing MicaSystemBackdrop instances.
        if (micaController is not null)
        {
            throw new Exception("This controller cannot be shared");
        }

        micaController = new MicaController();
        // Set configuration.
        SystemBackdropConfiguration defaultConfig = GetDefaultSystemBackdropConfiguration(connectedTarget, xamlRoot);
        micaController.SetSystemBackdropConfiguration(defaultConfig);
        // Add target.
        micaController.AddSystemBackdropTarget(connectedTarget);
    }

    protected override void OnTargetDisconnected(ICompositionSupportsSystemBackdrop disconnectedTarget)
    {
        base.OnTargetDisconnected(disconnectedTarget);

        micaController.RemoveSystemBackdropTarget(disconnectedTarget);
        micaController = null;
    }
}

注解

使用此类创建自定义系统背景。 不要直接创建此类 (记下受保护的构造函数) 。 相反，将其子类化以添加自定义支持。 还可以使用一个内置的派生类 MicaBackdrop 和 DesktopAcrylicBackdrop。

通常，自定义材料会替代 OnTargetConnected 以创建和配置支持 ISystemBackdropController，后者将管理用于填充背景区域的 CompositionBrush 。 画笔的最终像素呈现受以下因素影响：

• 通过 SystemBackdropConfiguration 设置的环境/策略
• 材料的外观参数，通过常规属性（如 ISystemBackdropControllerWithTargets.State (Active/FallbackHighContrast/) ）和特定于材料的属性（如 MicaController.Kind () Base/BaseAlt ）公开。

内置控制器 (MicaController 和 DesktopAcrylicController) 支持以下参数来自定义其外观： FallbackColor、 LuminosityOpacity、 TintColor和 TintOpacity。 (MicaBackdrop 和 DesktopAcrylicBackdrop) 的内置系统背景不公开 FallbackColor 或材料自定义属性 (TintOpacity等) 。 相反，它们依赖于基础 MicaController 和 DesktopAcrylicController的默认浅色/深色配置。 若要自定义这些属性，请创建派生自 SystemBackdrop 并公开所需属性的自定义材料类。

构造函数

SystemBackdrop()

初始化 SystemBackdrop 类的新实例。

属性

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

方法

ClearValue(DependencyProperty)	清除依赖属性的本地值。 (继承自 DependencyObject)
GetAnimationBaseValue(DependencyProperty)	返回为依赖属性建立的任何基值，该基值适用于动画未处于活动状态的情况。 (继承自 DependencyObject)
GetDefaultSystemBackdropConfiguration(ICompositionSupportsSystemBackdrop, XamlRoot)	检索可传递给 ISystemBackdropControllerWithTargets.SetSystemBackdropConfiguration的默认SystemBackdropConfiguration对象。
GetValue(DependencyProperty)	从 DependencyObject 返回依赖属性的当前有效值。 (继承自 DependencyObject)
OnDefaultSystemBackdropConfigurationChanged(ICompositionSupportsSystemBackdrop, XamlRoot)	重写在对象更改返回时要调用的 GetDefaultSystemBackdropConfiguration 此方法。 如果使用自定义 SystemBackdropConfiguration，这非常有用。
OnTargetConnected(ICompositionSupportsSystemBackdrop, XamlRoot)	将此对象附加到有效容器时调用;例如，在 上 Window.SystemBackdrop设置 时。
OnTargetDisconnected(ICompositionSupportsSystemBackdrop)	从其容器中清除此对象时调用。
ReadLocalValue(DependencyProperty)	如果设置了本地值，则返回依赖属性的本地值。 (继承自 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	注册通知函数，用于侦听此 DependencyObject 实例上对特定 DependencyProperty 的更改。 (继承自 DependencyObject)
SetValue(DependencyProperty, Object)	设置 DependencyObject 上依赖属性的本地值。 (继承自 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消以前通过调用 RegisterPropertyChangedCallback 注册的更改通知。 (继承自 DependencyObject)

另请参阅

• Mica 材质
• 亚克力材料