在 Windows 11 桌面應用程式中應用雲母或壓克力材質

Windows 11中的材質是應用於用戶界面表面，模擬真實物件的視覺效果。雲母和壓克力這類遮擋材質會使用在互動式 UI 控制項下方當作基底層。

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

壓克力是一種半透明材質，重現了結霜玻璃的效果。它僅用於暫時性、輕鬆關閉的介面，例如快顯視窗和選單。

本文說明如何將雲母或壓克力顏料應用於 Windows 應用程式 SDK/WinUI 3 XAML 應用程式的基礎層。

備註

要在 Win32 應用程式中使用背景材質，請參考在 Windows 11 上的 Win32 桌面應用程式中應用雲母。
關於應用內壓克力顏料應用於 UI 元素（非視窗背景），請參見應用內壓克力。

如何使用背景材質

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

開啟 WinUI 3 圖庫應用程式，看看系統背景的運作

WinUI 3 圖庫應用程式包含互動式的 WinUI 控制項與功能範例。你可以從 Microsoft Store下載 App，或在 GitHub 瀏覽原始碼。

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

這些元素具有 SystemBackdrop 屬性：

這些範例展示了如何在 XAML 中設定系統背景。

Mica

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

<Window
    ... >

    <Window.SystemBackdrop>
        <MicaBackdrop/>
    </Window.SystemBackdrop>

</Window>

米卡·阿爾特

要使用 Mica Alt 變體，請將屬性設 Kind 為 BaseAlt。

<Window
    ... >

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

</Window>

Acrylic

桌面壓克力可以作為窗戶的背景。

<Window
    ... >

    <Window.SystemBackdrop>
        <DesktopAcrylicBackdrop/>
    </Window.SystemBackdrop>

</Window>

壓克力顏料在瞬態介面上

壓克力也常用作暫時使用者介面的背景，例如彈出視窗。你可以在 XAML 或程式碼中設定，因為彈出選單通常是動態產生的。

<Flyout
    ... >

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

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

對任何 XAML 元素套用系統背景

Important

SystemBackdropElement需要 Windows 應用程式 SDK 2.0 或更新版本。

重要 API： SystemBackdropElement

打開 WinUI 3 圖庫應用程式，看看 SystemBackdropElement 的運作

WinUI 3 圖庫應用程式包含互動式的 WinUI 控制項與功能範例。你可以從 Microsoft Store下載 App，或在 GitHub 瀏覽原始碼。

Window.SystemBackdrop 屬性會將背景材質套用到整個視窗。如果你需要在介面的特定區域（例如卡片、面板或任何有界區域）上塗雲母或壓克力，請改用控制 SystemBackdropElement 鍵。

SystemBackdropElement 是一個 XAML 控制項，可在其自身範圍內轉譯系統背景材質。你可以把它放在 XAML 樹的任意位置，明確設定大小，或讓它填滿父節點，並用 CornerRadius 來套用圓角。

在 XAML 中使用 SystemBackdropElement

將 SystemBackdropElement 放在其他內容後方作為同層元素，或作為 Grid 內部的背景宿主。將其 SystemBackdrop 屬性設為所需的材質。

<Grid Width="300" Height="200">
    <SystemBackdropElement CornerRadius="8">
        <SystemBackdropElement.SystemBackdrop>
            <DesktopAcrylicBackdrop />
        </SystemBackdropElement.SystemBackdrop>
    </SystemBackdropElement>

    <!-- Content rendered on top of the backdrop -->
    <Button HorizontalAlignment="Center"
            VerticalAlignment="Center"
            Content="Click Me" />
</Grid>

在執行時切換背景素材

你可以在執行時更改 SystemBackdrop 屬性。此範例讓使用者在壓克力與兩種雲母變體之間選擇：

private void OnBackdropTypeChanged(string backdropType)
{
    DynamicBackdropHost.SystemBackdrop = backdropType switch
    {
        "Mica"    => new MicaBackdrop { Kind = MicaKind.Base },
        "MicaAlt" => new MicaBackdrop { Kind = MicaKind.BaseAlt },
        _         => new DesktopAcrylicBackdrop()
    };
}

備註

SystemBackdropElement 將系統背景套用到頁面內元素，而非視窗。對於視窗層級背景，請使用如本文前面所述的 Window.SystemBackdrop 屬性。這兩種方式是獨立的，可以在同一個應用程式中一起使用。

進階：如何使用系統背景控制器

備註

從 Windows 應用程式 SDK 1.3 開始，你可以像前一節所述，將 Window.SystemBackdrop 屬性設定成 XAML SystemBackdrop 來套用材質。這是大多數應用程式推薦的塗布方式。

本文剩餘部分將說明如何使用 Composition MicaController 和 DesktopAcrylicController API，這些 API 讓你能更好地控制背景的行為。

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

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

建立 MicaController

MicaController micaController;

bool TrySetMicaBackdrop(bool useMicaAlt)
{
    if (MicaController.IsSupported())
    {
        ...
        micaController = new MicaController();
        micaController.Kind = useMicaAlt ? MicaKind.BaseAlt : MicaKind.Base;
        ...
    }
}

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

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

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

建立桌面壓克力控制器

DesktopAcrylicController acrylicController;

bool TrySetAcrylicBackdrop(bool useAcrylicThin)
{
    if (DesktopAcrylicController.IsSupported())
    {
        ...
        acrylicController = new DesktopAcrylicController();
        acrylicController.Kind = useAcrylicThin 
            ? DesktopAcrylicKind.Thin : DesktopAcrylicKind.Base;
        ...
    }
}

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

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

void SetBackground(bool useAcrylicThin)
{
    if (winrt::MUCSB::DesktopAcrylicController::IsSupported())
    {
        ...
        m_backdropController = winrt::MUCSB::DesktopAcrylicController();
        m_backdropController.Kind(useAcrylicThin 
            ? winrt::MUCSB::DesktopAcrylicKind::Thin 
            : winrt::MUCSB::DesktopAcrylicKind::Base);
        ...
    }
}

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

備註

自訂控制器的四個屬性後，當相關的 SystemBackdropConfiguration.Theme 改變時，它不再套用預設的亮或暗值。您必須手動更新這些屬性，以符合新的主題。

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

系統支援

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

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

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

您的主要 XAML 執行緒需要有可用的 Windows.System.DispatcherQueue。打電話 DispatcherQueue.EnsureSystemDispatcherQueue() 確認有沒有。

範例：在 WinUI 應用程式中使用控制器搭配 Mica。

這個範例展示了如何在 XAML 應用程式中使用控制器設定 Mica 背景材質。

小提示

另外，請參考 GitHub 上的這些範例專案：

C#：WinUI 畫廊中的 SampleSystemBackdropsWindow。

C++/WinRT：Windows 應用程式 SDK Mica 樣本。

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

public sealed partial class MainWindow : Window
{
    MicaController micaController;
    SystemBackdropConfiguration configurationSource;

    public MainWindow()
    {
        this.InitializeComponent();

        TrySetMicaBackdrop(false);
    }

    bool TrySetMicaBackdrop(bool useMicaAlt)
    {
        if (MicaController.IsSupported())
        {
            DispatcherQueue.EnsureSystemDispatcherQueue();

            // Hooking up the policy object.
            configurationSource = new SystemBackdropConfiguration();
            Activated += Window_Activated;
            Closed += Window_Closed;
            ((FrameworkElement)Content).ActualThemeChanged += Window_ThemeChanged;

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

            micaController = new MicaController
            {
                Kind = useMicaAlt ? MicaKind.BaseAlt : MicaKind.Base
            };

            // Enable the system backdrop.
            // Note: Be sure to have "using WinRT;" to support the Window.As<...>() call.
            micaController.AddSystemBackdropTarget(
                this.As<ICompositionSupportsSystemBackdrop>());
            micaController.SetSystemBackdropConfiguration(configurationSource);
            return true; // Succeeded.
        }

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

    private void Window_Activated(object sender, WindowActivatedEventArgs args)
    {
        if (configurationSource != null)
            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.
        micaController?.Dispose();
        micaController = null;
        Activated -= Window_Activated;
        configurationSource = null;
    }

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

    private void SetConfigurationSourceTheme()
    {
        if (configurationSource != null)
            configurationSource.Theme = 
                (SystemBackdropTheme)((FrameworkElement)Content).ActualTheme;
    }
}

// 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>());
        }
    }

    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;
        }
    }
    ...
};
...

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-19