在 Windows 11 傳統型應用程式中套用 Mica 或壓克力材質

發行項
07/17/2024

Windows 11 的材質是套用在 UX 表面的視覺效果，擬似現實生活中的工藝品。雲母和壓克力這類遮擋材質會使用在互動式 UI 控制項下方當作基底層。

雲母是一種不透明的材質，融合了使用者的佈景主題和桌面桌布，建立出高度個人化的外觀。雲母是專為效能而設計，因為它只會擷取一次背景桌布來建立視覺效果，因此我們建議將它用於應用程式的基礎層，特別是標題列區域。

壓克力是一種半透明材質，重現了結霜玻璃的效果。壓克力僅用於暫時性的消失關閉介面，例如飛出視窗和操作功能表。

本文說明如何將雲母或壓克力套用為 Windows 應用程式 SDK/WinUI 3 XAML 應用程式的基底層。

注意

若要使用應用程式內 AcrylicBrush，請參閱壓克力材質。
若要在 Win32 應用程式中使用背景材質，請參閱在 Windows 11 的 Win32 傳統型應用程式中套用 Mica。
若要在UWP/WinUI 2 應用程式中使用背景材質，請參閱針對UWP 或壓克力材質套用Mica與WinUI 2。

如何使用背景材質

重要 API：Window.SystemBackdrop 屬性、MicaBackdrop 類別、DesktopAcrylicBackdrop 類別、SystemBackdropConfiguration 類別

開啟 WinUI 3 資源庫應用程式，查看系統背景的實際運作。

WinUI 3 資源庫應用程式包含大多數 WinUI 3 控制項和功能的互動式範例。從 Microsoft Store 取得應用程式，或在 GitHub 上取得原始程式碼

若要將Mica或Acrylic材質套用至您的應用程式，您可以將屬性設定SystemBackdrop為 XAML SystemBackdrop（通常是其中一個內建背景、MicaBackdrop 或 DesktopAcrylicBackdrop）。

這些元素具有 SystemBackdrop 屬性：

這些範例示範如何在 XAML 和程式碼中設定系統背景。

Mica

Mica 通常用來作為應用程式視窗的背景。

<Window
    ... >

    <Window.SystemBackdrop>
        <MicaBackdrop Kind="BaseAlt"/>
    </Window.SystemBackdrop>

</Window>

public MainWindow()
{
    this.InitializeComponent();

    SystemBackdrop = new MicaBackdrop() 
                        { Kind = MicaKind.BaseAlt };
}

壓克力

壓克力通常用於暫時性 UI 的背景，例如飛出視窗。

<Flyout
    ... >

    <Flyout.SystemBackdrop>
        <DesktopAcrylicBackdrop/>
    </Flyout.SystemBackdrop>
</Flyout>

Flyout flyout = new Flyout()
{
    SystemBackdrop = new DesktopAcrylicBackdrop()
};

如何使用系統背景控制器

注意

從 Windows 應用程式 SDK 1.3 起，您可以按照上一節所述將 Window.SystemBackdrop 屬性設定為 XAMLSystemBackdrop，藉此套用材質。這是套用材質時的建議方法。

本文的其餘部分說明如何使用組合 MicaController 和 DesktopAcrylicController API。

若要在應用程式中使用背景材質，您可以使用其中一種控制器來實作 ISystemBackdropController 介面 (MicaController 或 DesktopAcrylicController)。這些類別可管理系統底圖材質的呈現，以及處理雲母材質的系統原則。

若要將雲母設為背景材質，請建立 MicaController 物件。若要使用壓克力，則請建立 DesktopAcrylicController 物件。每個系統背景材質類型的設定和支援程式碼都相同。

以下程式碼示範如何建立 MicaController。

MicaController m_backdropController;

bool TrySetSystemBackdrop()
{
    if (MicaController.IsSupported())
    {
        ...
        m_backdropController = new MicaController();
        ...
    }
}

// namespace MUCSB = Microsoft::UI::Composition::SystemBackdrops;

winrt::MUCSB::MicaController m_backdropController{ nullptr };

void SetBackground()
{
    if (winrt::MUCSB::MicaController::IsSupported())
    {
        ...
        m_backdropController = winrt::MUCSB::MicaController();
        ...
    }
}

若要使用雲母的 Mica Alt 變體，請建立 MicaController 物件，並將 Kind 屬性設為 MicaKind.BaseAlt。

MicaController m_backdropController;

bool TrySetSystemBackdrop()
{
    if (MicaController.IsSupported())
    {
        ...
        m_backdropController = new MicaController()
        {
            Kind = MicaKind.BaseAlt
        };
        ...
    }
}

// namespace MUCSB = Microsoft::UI::Composition::SystemBackdrops;

winrt::MUCSB::MicaController m_backdropController{ nullptr };

void SetBackground()
{
    if (winrt::MUCSB::MicaController::IsSupported())
    {
        ...
        m_backdropController = winrt::MUCSB::MicaController();
        m_backdropController.Kind(winrt::MUCSB::MicaKind::BaseAlt);
        ...
    }
}

以下程式碼示範如何建立 DesktopAcrylicController。

DesktopAcrylicController m_backdropController;

bool TrySetSystemBackdrop()
{
    if (DesktopAcrylicController.IsSupported())
    {
        ...
        m_backdropController = new DesktopAcrylicController();
        ...
    }
}

// namespace MUCSB = Microsoft::UI::Composition::SystemBackdrops;

winrt::MUCSB::DesktopAcrylicController m_backdropController{ nullptr };

void SetBackground()
{
    if (winrt::MUCSB::DesktopAcrylicController::IsSupported())
    {
        ...
        m_backdropController = winrt::MUCSB::DesktopAcrylicController();
        ...
    }
}

控制器會依預設回應系統的淺色和深色主題。若要覆寫此行為，您可以在控制器設定下列屬性：

若要在應用程式使用背景材質，您需要下列項目：

系統支援

執行應用程式的系統必須支援背景材質。呼叫 MicaController.IsSupported 或 DesktopAcrylicController.IsSupported 方法，以確保執行階段支援背景材質。
有效的目標

您必須提供目標來實作 ICompositionSupportsSystemBackdrop 介面。在 XAML 應用程式中，XAML Window 會實作這類介面，並當作背景目標來使用。
SystemBackdropConfiguration 物件

SystemBackdropConfiguration 提供系統背景控制器與應用程式特定的原則資訊，藉此正確設定系統背景材質。
DispatcherQueue 物件。

您的主要 XAML 執行緒需要有可用的 Windows.System.DispatcherQueue。請參考範例程式碼或 WinUI 3 資源庫範例的 WindowsSystemDispatcherQueueHelper 類別。

範例：在 Windows AppSDK/WinUI 3 應用程式中使用雲母

此範例示範如何在 XAML 應用程式中設定雲母背景材質。

提示

此外，請在 GitHub 參閱以下範例專案：

C#：WinUI3 資源庫中的 SampleSystemBackdropsWindow。

C++/WinRT：Windows 應用程式 SDK 雲母範例。

using Microsoft.UI.Composition.SystemBackdrops;
using Microsoft.UI.Xaml;
using System.Runtime.InteropServices; // For DllImport
using WinRT; // required to support Window.As<ICompositionSupportsSystemBackdrop>()

public sealed partial class MainWindow : Window
{
    WindowsSystemDispatcherQueueHelper m_wsdqHelper; // See below for implementation.
    MicaController m_backdropController;
    SystemBackdropConfiguration m_configurationSource;

    public MainWindow()
    {
        this.InitializeComponent();

        TrySetSystemBackdrop();
    }

    bool TrySetSystemBackdrop()
    {
        if (Microsoft.UI.Composition.SystemBackdrops.MicaController.IsSupported())
        {
            m_wsdqHelper = new WindowsSystemDispatcherQueueHelper();
            m_wsdqHelper.EnsureWindowsSystemDispatcherQueueController();

            // Create the policy object.
            m_configurationSource = new SystemBackdropConfiguration();
            this.Activated += Window_Activated;
            this.Closed += Window_Closed;
            ((FrameworkElement)this.Content).ActualThemeChanged += Window_ThemeChanged;

            // Initial configuration state.
            m_configurationSource.IsInputActive = true;
            SetConfigurationSourceTheme();

            m_backdropController = new Microsoft.UI.Composition.SystemBackdrops.MicaController();

            // Enable the system backdrop.
            // Note: Be sure to have "using WinRT;" to support the Window.As<...>() call.
            m_backdropController.AddSystemBackdropTarget(this.As<Microsoft.UI.Composition.ICompositionSupportsSystemBackdrop>());
            m_backdropController.SetSystemBackdropConfiguration(m_configurationSource);
            return true; // succeeded
        }

        return false; // Mica is not supported on this system
    }

    private void Window_Activated(object sender, WindowActivatedEventArgs args)
        {
            m_configurationSource.IsInputActive = args.WindowActivationState != WindowActivationState.Deactivated;
        }

    private void Window_Closed(object sender, WindowEventArgs args)
        {
            // Make sure any Mica/Acrylic controller is disposed
            // so it doesn't try to use this closed window.
            if (m_backdropController != null)
            {
                m_backdropController.Dispose();
                m_backdropController = null;
            }
            this.Activated -= Window_Activated;
            m_configurationSource = null;
        }

    private void Window_ThemeChanged(FrameworkElement sender, object args)
        {
            if (m_configurationSource != null)
            {
                SetConfigurationSourceTheme();
            }
        }

    private void SetConfigurationSourceTheme()
        {
            switch (((FrameworkElement)this.Content).ActualTheme)
            {
                case ElementTheme.Dark: m_configurationSource.Theme = Microsoft.UI.Composition.SystemBackdrops.SystemBackdropTheme.Dark; break;
                case ElementTheme.Light: m_configurationSource.Theme = Microsoft.UI.Composition.SystemBackdrops.SystemBackdropTheme.Light; break;
                case ElementTheme.Default: m_configurationSource.Theme = Microsoft.UI.Composition.SystemBackdrops.SystemBackdropTheme.Default; break;
            }
        }
}

class WindowsSystemDispatcherQueueHelper
{
    [StructLayout(LayoutKind.Sequential)]
    struct DispatcherQueueOptions
    {
        internal int dwSize;
        internal int threadType;
        internal int apartmentType;
    }

    [DllImport("CoreMessaging.dll")]
    private static extern int CreateDispatcherQueueController([In] DispatcherQueueOptions options, [In, Out, MarshalAs(UnmanagedType.IUnknown)] ref object dispatcherQueueController);

    object m_dispatcherQueueController = null;
    public void EnsureWindowsSystemDispatcherQueueController()
    {
        if (Windows.System.DispatcherQueue.GetForCurrentThread() != null)
        {
            // one already exists, so we'll just use it.
            return;
        }

        if (m_dispatcherQueueController == null)
        {
            DispatcherQueueOptions options;
            options.dwSize = Marshal.SizeOf(typeof(DispatcherQueueOptions));
            options.threadType = 2;    // DQTYPE_THREAD_CURRENT
            options.apartmentType = 2; // DQTAT_COM_STA

            CreateDispatcherQueueController(options, ref m_dispatcherQueueController);
        }
    }
}

// pch.h
...
#include <winrt/Microsoft.UI.Composition.SystemBackdrops.h>
#include <winrt/Windows.System.h>
#include <dispatcherqueue.h>

// MainWindow.xaml.h
...
namespace winrt
{
    namespace MUC = Microsoft::UI::Composition;
    namespace MUCSB = Microsoft::UI::Composition::SystemBackdrops;
    namespace MUX = Microsoft::UI::Xaml;
    namespace WS = Windows::System;
}
...
struct MainWindow : MainWindowT<MainWindow>
{
    winrt::MUCSB::SystemBackdropConfiguration m_configuration{ nullptr };
    winrt::MUCSB::MicaController m_backdropController{ nullptr };
    winrt::MUX::Window::Activated_revoker m_activatedRevoker;
    winrt::MUX::Window::Closed_revoker m_closedRevoker;
    winrt::MUX::FrameworkElement::ActualThemeChanged_revoker m_themeChangedRevoker;
    winrt::MUX::FrameworkElement m_rootElement{ nullptr };
    winrt::WS::DispatcherQueueController m_dispatcherQueueController{ nullptr };

    MainWindow::MainWindow()
    {
        InitializeComponent();

        SetBackground();

        m_closedRevoker = this->Closed(winrt::auto_revoke, [&](auto&&, auto&&)
        {
            if (nullptr != m_backdropController)
            {
                m_backdropController.Close();
                m_backdropController = nullptr;
            }

            if (nullptr != m_dispatcherQueueController)
            {
                m_dispatcherQueueController.ShutdownQueueAsync();
                m_dispatcherQueueController = nullptr;
            }
        });
    }

    void SetBackground()
    {
        if (winrt::MUCSB::MicaController::IsSupported())
        {
            // We ensure that there is a Windows.System.DispatcherQueue on the current thread.
            // Always check if one already exists before attempting to create a new one.
            if (nullptr == winrt::WS::DispatcherQueue::GetForCurrentThread() &&
                nullptr == m_dispatcherQueueController)
            {
                m_dispatcherQueueController = CreateSystemDispatcherQueueController();
            }

            // Setup the SystemBackdropConfiguration object.
            SetupSystemBackdropConfiguration();

            // Setup Mica on the current Window.
            m_backdropController = winrt::MUCSB::MicaController();
            m_backdropController.SetSystemBackdropConfiguration(m_configuration);
            m_backdropController.AddSystemBackdropTarget(
                this->m_inner.as<winrt::MUC::ICompositionSupportsSystemBackdrop>());
        }
        else
        {
            // The backdrop material is not supported.
        }
    }

    winrt::WS::DispatcherQueueController CreateSystemDispatcherQueueController()
    {
        DispatcherQueueOptions options
        {
            sizeof(DispatcherQueueOptions),
            DQTYPE_THREAD_CURRENT,
            DQTAT_COM_NONE
        };

        ::ABI::Windows::System::IDispatcherQueueController* ptr{ nullptr };
        winrt::check_hresult(CreateDispatcherQueueController(options, &ptr));
        return { ptr, take_ownership_from_abi };
    }

    void SetupSystemBackdropConfiguration()
    {
        m_configuration = winrt::MUCSB::SystemBackdropConfiguration();

        // Activation state.
        m_activatedRevoker = this->Activated(winrt::auto_revoke,
            [&](auto&&, MUX::WindowActivatedEventArgs const& args)
            {
                m_configuration.IsInputActive(
                    winrt::MUX::WindowActivationState::Deactivated != args.WindowActivationState());
            });

        // Initial state.
        m_configuration.IsInputActive(true);

        // Application theme.
        m_rootElement = this->Content().try_as<winrt::MUX::FrameworkElement>();
        if (nullptr != m_rootElement)
        {
            m_themeChangedRevoker = m_rootElement.ActualThemeChanged(winrt::auto_revoke,
                [&](auto&&, auto&&)
                {
                    m_configuration.Theme(
                        ConvertToSystemBackdropTheme(m_rootElement.ActualTheme()));
                });

            // Initial state.
            m_configuration.Theme(
                ConvertToSystemBackdropTheme(m_rootElement.ActualTheme()));
        }
    }

    winrt::MUCSB::SystemBackdropTheme ConvertToSystemBackdropTheme(
        winrt::MUX::ElementTheme const& theme)
    {
        switch (theme)
        {
        case winrt::MUX::ElementTheme::Dark:
            return winrt::MUCSB::SystemBackdropTheme::Dark;
        case winrt::MUX::ElementTheme::Light:
            return winrt::MUCSB::SystemBackdropTheme::Light;
        default:
            return winrt::MUCSB::SystemBackdropTheme::Default;
        }
    }
    ...
};
...

共用方式為

在 Windows 11 傳統型應用程式中套用 Mica 或壓克力材質

如何使用背景材質

Mica

壓克力

如何使用系統背景控制器

範例：在 Windows AppSDK/WinUI 3 應用程式中使用雲母

其他資源

共用方式為

在 Windows 11 傳統型應用程式中套用 Mica 或壓克力材質

如何使用背景材質

Mica

壓克力

如何使用系統背景控制器

範例：在 Windows AppSDK/WinUI 3 應用程式中使用雲母

相關文章

其他資源