Använda mica- eller akrylmaterial i skrivbordsappar för Windows 11

Artikel
03/13/2025

Material i Windows 11 är visuella effekter som tillämpas på UX-ytor som liknar verkliga artefakter. Skymmande material, som mica och akryl, används som baslager under de interaktiva gränssnittskontrollerna.

Mica är ett täckande material som innehåller användarens tema och skrivbordsunderlägg för att skapa ett mycket personligt utseende. Mica är utformat för prestanda eftersom det bara avbildar bakgrundsunderlägget en gång för att skapa sin visualisering, så vi rekommenderar det för grundskiktet i din app, särskilt i området med namnlisten.

Akryl är ett halvtransparent material som replikerar effekten av frostat glas. Den används endast för tillfälliga, lättslämda ytor som utfällbara menyer och snabbmenyer.

Den här artikeln beskriver hur du använder Mica eller Acrylic som basskikt för din Windows App SDK/WinUI 3 XAML-app.

Not

För att använda en AcrylicBrush i appen, se Akrylmaterial.
Information om hur du använder bakgrundsmaterial i en Win32-app finns i Tillämpa Mica i Win32-skrivbordsappar för Windows 11.
Information om hur du använder bakgrundsmaterial i en UWP/WinUI 2-app finns i Använd Mica med WinUI 2 för UWP eller Akrylmaterial.

Så här använder du ett bakgrundsmaterial

Viktiga API:er: Window.SystemBackdrop-egenskapen, Klassen MicaBackdrop, DesktopAcrylicBackdrop-klass, SystemBackdropConfiguration-klass

Öppna WinUI 3-galleriappen och se systembakgrunder i praktiken

WinUI 3 Gallery-appen innehåller interaktiva exempel på de flesta WinUI 3-kontroller, funktioner och funktioner. Hämta appen från Microsoft Store- eller hämta källkoden på GitHub-

Om du vill använda Mica- eller Akrylmaterial i din app ställer du in egenskapen SystemBackdrop till en XAML-SystemBackdrop- (vanligtvis en av de inbyggda bakgrunderna, MicaBackdrop eller DesktopAcrylicBackdrop).

Dessa element har en SystemBackdrop egenskap:

De här exemplen visar hur du ställer in systembakgrunden i XAML och i kod.

Glimmer

Mica används vanligtvis som bakgrund för ett appfönster.

<Window
    ... >

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

</Window>

public MainWindow()
{
    this.InitializeComponent();

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

Akryl

Akryl används vanligtvis som bakgrund för tillfälligt användargränssnitt, till exempel en utfälld skärm.

<Flyout
    ... >

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

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

Så här använder du en systembakgrundskontrollant

Not

Från och med Windows App SDK 1.3 kan du använda material genom att ange egenskapen Window.SystemBackdrop till en XAML-SystemBackdrop enligt beskrivningen i föregående avsnitt. Detta är det rekommenderade sättet att tillämpa ett material.

Resten av den här artikeln visar hur du använder API:erna Composition MicaController och DesktopAcrylicController.

Om du vill använda ett bakgrundsmaterial i din app kan du använda en av de kontrollanter som implementerar ISystemBackdropController-gränssnittet (MicaController eller DesktopAcrylicController). Dessa klasser hanterar både återgivningen av systemets bakgrundsmaterial samt hanteringen av systempolicyn för materialet.

Om du vill använda Mica som bakgrundsmaterial skapar du ett MicaController- objekt. Om du vill använda Akryl skapar du ett DesktopAcrylicController--objekt. Den konfigurerade och stödjande koden är densamma för varje typ av systembakgrundsmaterial.

Den här koden visar hur du skapar en 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();
        ...
    }
}

Om du vill använda Mica Alt-varianten av Mica skapar du ett MicaController-objekt och anger egenskapen Kind till 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);
        ...
    }
}

Den här koden visar hur du skapar en 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();
        ...
    }
}

Styrenheten reagerar som standard på systemets ljusa och mörka teman. Om du vill åsidosätta det här beteendet kan du ange följande egenskaper på kontrollanten:

Not

När du har anpassat någon av kontrollantens fyra egenskaper tillämpas inte längre standardvärden för ljus eller mörk när de associerade SystemBackdropConfiguration.Theme ändras. Du måste uppdatera egenskaperna manuellt för att matcha det nya temat.

För att kunna använda bakgrundsmaterialet i din app krävs följande:

Systemstöd

Systemet där appen körs måste ha stöd för bakgrundsmaterialet. Anropa metoden MicaController.IsSupported eller DesktopAcrylicController.IsSupported för att säkerställa att bakgrundsmaterialet stöds under körning.
Ett giltigt mål

Du måste ange ett mål som implementerar gränssnittet ICompositionSupportsSystemBackdrop. I en XAML-app implementerar XAML Window det här gränssnittet och används som bakgrundsmål.
Ett SystemBackdropConfiguration-objekt

SystemBackdropConfiguration ger systembakgrundskontrollanten appspecifik principinformation för att korrekt konfigurera systemets bakgrundsmaterial.
Ett DispatcherQueue-objekt.

Du behöver en tillgänglig Windows.System.DispatcherQueue på XAML-huvudtråden. Se klassen WindowsSystemDispatcherQueueHelper i exempelkoden eller i WinUI 3-galleriexemplet.

Exempel: Använda Mica i en Windows AppSDK/WinUI 3-app

Det här exemplet visar hur du konfigurerar Mica-bakgrundsmaterialet i en XAML-app.

Tips

Se även följande exempelprojekt på GitHub:

C#: SampleSystemBackdropsWindow i WinUI3-galleriet.

C++/WinRT: Windows App SDK Mica-exempel.

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

Dela via

Använda mica- eller akrylmaterial i skrivbordsappar för Windows 11

Så här använder du ett bakgrundsmaterial

Glimmer

Akryl

Så här använder du en systembakgrundskontrollant

Exempel: Använda Mica i en Windows AppSDK/WinUI 3-app

Ytterligare resurser

Dela via

Använda mica- eller akrylmaterial i skrivbordsappar för Windows 11

Så här använder du ett bakgrundsmaterial

Glimmer

Akryl

Så här använder du en systembakgrundskontrollant

Exempel: Använda Mica i en Windows AppSDK/WinUI 3-app

Relaterade artiklar

Ytterligare resurser