Aplicación de materiales Mica o Acrílico en aplicaciones de escritorio de Windows 11

Artículo
05/22/2023

Los materiales de Windows 11 son efectos visuales aplicados a superficies de la experiencia de usuario que recuerdan a artefactos de la vida real. Los materiales bloqueantes, como Mica y Acrílico, se emplean como capas base bajo los controles interactivos de la interfaz de usuario.

Mica es un material opaco que incorpora el tema y el fondo de pantalla de escritorio del usuario para crear una apariencia muy personalizada. Mica está diseñado para mejorar el rendimiento, ya que solo captura el fondo de pantalla una vez para crear su visualización, por lo que se recomienda para la capa básica de la aplicación, especialmente en el área de la barra de título.

Acrílico es un material semitransparente que replica el efecto de cristal esmerilado. Solo se usa para superficies transitorias que no dejan pasar la luz, como controles flotantes y menús contextuales.

En este artículo se describe cómo aplicar Mica o Acrílico como capa base de la aplicación XAML del SDK de aplicaciones para Windows o WinUI 3.

Nota:

Para usar materiales de fondo en una aplicación Win32, consulte Aplicación de Mica en aplicaciones de escritorio en Win32 para Windows 11.
Para usar materiales de fondo en una aplicación para UWP o WinUI 2, consulte Mica o Acrílico.

Uso de un material de fondo

API importantes: propiedad Window.SystemBackdrop, clase MicaBackdrop, clase DesktopAcrylicBackdrop, clase SystemBackdropConfiguration

Abra la aplicación WinUI 3 Gallery y vea los fondos del sistema en acción.

La aplicación WinUI 3 Gallery incluye ejemplos interactivos de la mayoría de los controles, características y funcionalidades de WinUI 3. Obtenga la aplicación de Microsoft Store u obtenga el código fuente en GitHub.

Para aplicar material Mica o Acrílico a su aplicación, la propiedad Window.SystemBackdrop se establece en un objeto SystemBackdrop de XAML (normalmente, uno de los fondos integrados, MicaBackdrop o DesktopAcrylicBackdrop).

En estos ejemplos se muestra cómo hacerlo en XAML y en el código.

Mica

<Window
    ... >

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

</Window>

public MainWindow()
{
    this.InitializeComponent();

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

Acrílico

<Window
    ... >

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

</Window>

public MainWindow()
{
    this.InitializeComponent();

    SystemBackdrop = new DesktopAcrylicBackdrop();
}

Uso de un controlador de fondos del sistema

Nota:

A partir del SDK de aplicaciones para Windows 1.3, puede aplicar material estableciendo la propiedad Window.SystemBackdrop en un objeto SystemBackdrop de XAML, como se describe en la sección anterior. Esta es la manera recomendada de aplicar un material.

En el resto de este artículo se muestra cómo usar las API Composition MicaController y DesktopAcrylicController.

Para usar un material de fondo en su aplicación, puede utilizar uno de los controladores que implementa la interfaz ISystemBackdropController (MicaController o DesktopAcrylicController). Estas clases administran tanto la representación del material de fondo del sistema como el control de la directiva del sistema del material.

Para usar Mica como material de fondo, cree un objeto MicaController. Para usar Acrílico, cree un objeto DesktopAcrylicController. El código de configuración y complementario es el mismo para cada tipo de material de fondo del sistema.

Este código muestra cómo crear un objeto 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();
        ...
    }
}

Para usar la variante Mica Alt de Mica, cree un objeto MicaController y establezca la propiedad Kind en 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);
        ...
    }
}

Este código muestra cómo crear un objeto 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();
        ...
    }
}

El controlador reacciona a los temas Claro y Oscuro del sistema de forma predeterminada. Para invalidar este comportamiento, puede establecer las siguientes propiedades en el controlador:

Para usar el material de fondo de la aplicación, se requieren los siguientes elementos:

Compatibilidad del sistema

El sistema donde se ejecuta la aplicación debe admitir el material de fondo. Llame al método MicaController.IsSupported o DesktopAcrylicController.IsSupported para asegurarse de que el material de fondo se admita en tiempo de ejecución.
Un destino válido

Debe proporcionar un destino que implemente la interfaz ICompositionSupportsSystemBackdrop. En una aplicación XAML, la ventana de XAML implementa esta interfaz y se usa como destino de fondo.
Un objeto SystemBackdropConfiguration

SystemBackdropConfiguration proporciona al controlador de fondo del sistema información de directiva específica de la aplicación para configurar correctamente el material de fondo del sistema.
Un objeto DispatcherQueue.

Necesita un objeto Windows.System.DispatcherQueue disponible en el subproceso XAML principal. Consulte la clase WindowsSystemDispatcherQueueHelper en el código de ejemplo o en el ejemplo de la galería de WinUI 3.

Ejemplo: Uso de Mica en una aplicación del SDK de aplicaciones para Windows o WinUI 3

En este ejemplo se muestra cómo configurar el material de fondo Mica en una aplicación XAML.

Sugerencia

Consulte también estos proyectos de ejemplo en GitHub:

C#: SampleSystemBackdropsWindow en la galería de WinUI3.

C++/WinRT: Ejemplo de Mica del SDK de aplicaciones para Windows.

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

Aplicación de materiales Mica o Acrílico en aplicaciones de escritorio de Windows 11

Uso de un material de fondo

Mica

Acrílico

Uso de un controlador de fondos del sistema

Ejemplo: Uso de Mica en una aplicación del SDK de aplicaciones para Windows o WinUI 3

Comentarios

Recursos adicionales

Aplicación de materiales Mica o Acrílico en aplicaciones de escritorio de Windows 11

Uso de un material de fondo

Mica

Acrílico

Uso de un controlador de fondos del sistema

Ejemplo: Uso de Mica en una aplicación del SDK de aplicaciones para Windows o WinUI 3

Artículos relacionados

Comentarios

Recursos adicionales