Použití materiálů Mica nebo Akryl v desktopových aplikacích pro Windows 11

Článek
03/13/2025

Materiály ve Windows 11 jsou vizuální efekty, které se uplatňují na povrchy uživatelského rozhraní a připomínají artefakty reálného světa. Podkladové materiály, jako jsou Mica a Akryl, se používají jako základní vrstvy pod interaktivními ovládacími prvky uživatelského rozhraní.

Mica je neprůzný materiál, který zahrnuje motiv uživatele a tapetu na plochu, aby se vytvořil vysoce přizpůsobený vzhled. Mica je navržená pro výkon, protože zachytí tapetu na pozadí jen jednou za účelem vytvoření vizualizace, proto ji doporučujeme pro základní vrstvu vaší aplikace, zejména v oblasti záhlaví.

Akrylový je poloprůhledný materiál, který replikuje efekt zamrzlého skla. Používá se jenom pro přechodné, snadno zavíratelné plochy, jako jsou rozbalovací a kontextové nabídky.

Tento článek popisuje, jak použít Mica nebo Akryl jako základní vrstvu vaší aplikace WINDOWS App SDK/WinUI 3 XAML.

Poznámka

Chcete-li použít akrylový kartáč v aplikaci, viz akrylový materiál.
Další informace o použití podkladových materiálů v aplikaci Win32 najdete v tématu Aplikace materiálu Mica v desktopových aplikacích Win32 pro Windows 11.
Pokud chcete použít podkladové materiály v aplikaci pro UWP/WinUI 2, podívejte se na téma Použití Mica s WinUI 2 pro UWP nebo Akrylový materiál.

Jak používat podkladový materiál

důležitá rozhraní API: Vlastnost Window.SystemBackdrop, Třída MicaBackdrop, Třída DesktopAcrylicBackdrop, Třída SystemBackdropConfiguration

Otevřete aplikaci Galerie WinUI 3 a prohlédněte si systémová pozadí v akci

Aplikace Galerie WinUI 3 obsahuje interaktivní příklady většiny ovládacích prvků, funkcí a vlastností WinUI 3. Získejte aplikaci z Microsoft Storu nebo získejte zdrojový kód na GitHubu.

Chcete-li použít materiál Mica nebo Akryl ve vaší aplikaci, nastavíte vlastnost SystemBackdrop na XAML SystemBackdrop (obvykle jedno z předdefinovaných pozadí, MicaBackdrop nebo DesktopAcrylicBackdrop).

Tyto prvky mají vlastnost SystemBackdrop:

Tyto příklady ukazují, jak nastavit pozadí systému v XAML a v kódu.

Slída

Mica se obvykle používá jako pozadí okna aplikace.

<Window
    ... >

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

</Window>

public MainWindow()
{
    this.InitializeComponent();

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

Akryl

Akryl se obvykle používá jako pozadí pro dočasné uživatelské rozhraní, jako je vyskakovací okno.

<Flyout
    ... >

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

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

Jak používat systémový kontroler pozadí

Poznámka

Počínaje Windows App SDK 1.3 můžete použít materiál nastavením vlastnosti Window.SystemBackdrop na XAML SystemBackdrop, jak je popsáno v předchozí části. Toto je doporučený způsob použití materiálu.

Zbývající část tohoto článku ukazuje, jak používat API MicaController a DesktopAcrylicController .

Pokud chcete v aplikaci použít podkladový materiál, můžete použít jeden z kontrolerů, který implementuje rozhraní ISystemBackdropController (MicaController nebo DesktopAcrylicController). Tyto třídy spravují vykreslování materiálů systémových pozadí i řízení systémových zásad pro materiál.

Chcete-li použít Mica jako podkladový materiál, vytvořte objekt MicaController. Chcete-li použít akryl, vytvořte DesktopAcrylicController objektu. Nastavení a podpůrný kód je pro každý typ systémového podkladového materiálu stejný.

Tento kód ukazuje, jak vytvořit 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();
        ...
    }
}

Chcete-li použít Mica Alt variantu Mica, vytvořte objekt MicaController a nastavte vlastnost Kind na 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);
        ...
    }
}

Tento kód ukazuje, jak vytvořit 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();
        ...
    }
}

Kontroler ve výchozím nastavení reaguje na systémové světlé a tmavé motivy. Chcete-li toto chování přepsat, můžete v kontroleru nastavit následující vlastnosti:

Poznámka

Po přizpůsobení kterékoliv ze čtyř vlastností ovladače už se neaplikují výchozí světlé nebo tmavé hodnoty, když dojde ke změně přidružené hodnoty SystemBackdropConfiguration.Theme. Tyto vlastnosti je potřeba aktualizovat ručně tak, aby odpovídaly novému motivu.

Aby bylo možné v aplikaci použít podkladový materiál, jsou vyžadovány následující položky:

podpora systému

Systém, na kterém aplikace běží, musí podporovat materiál pozadí. Zavolejte metodu MicaController.IsSupported nebo DesktopAcrylicController.IsSupported, abyste zajistili podporu podkladového materiálu během provozu.
platný cíl

Musíte zadat cíl, který implementuje rozhraní ICompositionSupportsSystemBackdrop. V aplikaci XAML Okno XAML implementuje toto rozhraní a používá se jako prostředí pozadí.
objekt SystemBackdropConfiguration

SystemBackdropConfiguration poskytuje řadič backdrop systému s informacemi o zásadách specifických pro aplikace, aby správně nakonfiguroval materiál pozadí systému.
Objekt DispatcherQueue.

Potřebujete dostupnou Windows.System.DispatcherQueue v hlavním vlákně XAML. Podívejte se na třídu WindowsSystemDispatcherQueueHelper v ukázkovém kódu nebo v ukázce z galerie WinUI 3 .

Příklad: Použití Mica v aplikaci Windows AppSDK/WinUI 3

Tento příklad ukazuje, jak nastavit materiál pozadí Mica v aplikaci XAML.

Spropitné

Podívejte se také na tyto ukázkové projekty na GitHubu:

C#: SampleSystemBackdropsWindow v galerii WinUI3.

C++/WinRT: ukázkovésady Windows App SDK Mica .

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

Materiály ve Windows 11
Mica
akrylové
použití Mica v desktopových aplikacích Win32 pro Windows 11

Sdílet prostřednictvím

Použití materiálů Mica nebo Akryl v desktopových aplikacích pro Windows 11

Jak používat podkladový materiál

Slída

Akryl

Jak používat systémový kontroler pozadí

Příklad: Použití Mica v aplikaci Windows AppSDK/WinUI 3

Další materiály

Sdílet prostřednictvím

Použití materiálů Mica nebo Akryl v desktopových aplikacích pro Windows 11

Jak používat podkladový materiál

Slída

Akryl

Jak používat systémový kontroler pozadí

Příklad: Použití Mica v aplikaci Windows AppSDK/WinUI 3

Související články

Další materiály