Udostępnij za pośrednictwem

Stosowanie materiałów Mica lub akrylowych w aplikacjach desktopowych w systemie Windows 11

  • Artykuł

Materiały w systemie Windows 11 to efekty wizualne stosowane do powierzchni środowiska użytkownika przypominających prawdziwe artefakty życia. Materiały okludujące, takie jak mikka i akryl, są używane jako warstwy bazowe pod interaktywnymi kontrolkami interfejsu użytkownika.

Mica jest nieprzezroczystym materiałem, który zawiera motyw użytkownika i tapetę pulpitu, tworząc bardzo spersonalizowany wygląd. Mica została zaprojektowana z myślą o wydajności, ponieważ przechwytuje tapetę tła tylko raz, aby utworzyć swoją wizualizację, dlatego zalecamy jej użycie na warstwie bazowej aplikacji, szczególnie w pasku tytułowym.

Akryl jest półprzezroczystym materiałem, który replikuje efekt matowego szkła. Jest używany tylko w przypadku przejściowych, łatwo znikających powierzchni, takich jak wyskakujące okienka i menu kontekstowe.

W tym artykule opisano sposób stosowania miki lub akrylu jako podstawowej warstwy w aplikacji Windows App SDK lub aplikacji WinUI 3 XAML.

Notatka

Jak używać materiału tła

Otwórz aplikację Galerii WinUI 3 i zobacz działanie teł systemu

Aplikacja z galerii WinUI 3 zawiera interaktywne przykłady większości kontrolek, funkcji i funkcji interfejsu WinUI 3. Pobierz aplikację ze sklepu Microsoft Store lub pobierz kod źródłowy w witrynie GitHub

Aby zastosować materiał typu mica lub akrylowy do aplikacji, należy ustawić właściwość SystemBackdrop na XAML SystemBackdrop (zazwyczaj jeden z wbudowanych teł, MicaBackdrop lub DesktopAcrylicBackdrop).

Te elementy mają właściwość SystemBackdrop:

W tych przykładach pokazano, jak ustawić tło systemu w języku XAML i w kodzie.

Mika

Mica jest zwykle używana jako tło dla okna aplikacji.

<Window
    ... >

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

</Window>

public MainWindow()
{
    this.InitializeComponent();

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

Akryl

Akryl jest często używany jako tło dla przejściowego interfejsu użytkownika, na przykład wysuwanego.

<Flyout
    ... >

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

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

Jak używać kontrolera tła systemu

Notatka

Począwszy od zestawu Windows App SDK 1.3, można zastosować materiał, ustawiając właściwość Window.SystemBackdrop na SystemBackdrop XAML zgodnie z opisem w poprzedniej sekcji. Jest to zalecany sposób stosowania materiału.

W pozostałej części tego artykułu pokazano, jak używać interfejsów API MicaController i DesktopAcrylicController.

Aby użyć materiału tła w aplikacji, można użyć jednego z kontrolerów, który implementuje interfejs ISystemBackdropController (MicaController lub DesktopAcrylicController). Klasy te zarządzają zarówno wyświetlaniem materiału tła systemowego, jak i obsługą polityki systemowej dla materiału.

Aby użyć mica jako materiału tła, utwórz obiekt MicaController. Aby użyć akrylu, utwórz obiekt DesktopAcrylicController. Konfiguracja i kod pomocniczy są takie same dla każdego typu materiału tła systemu.

Ten kod pokazuje, jak utworzyć 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();
        ...
    }
}

Aby użyć wariantu Mica Alt Mica, utwórz obiekt MicaController i ustaw właściwość 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);
        ...
    }
}

Ten kod pokazuje, jak utworzyć 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 domyślnie reaguje na systemowe motywy jasne i ciemne. Aby zastąpić to zachowanie, można ustawić następujące właściwości na kontrolerze:

Notatka

Po dostosowaniu dowolnej z czterech właściwości kontrolera, nie stosuje już domyślnych wartości jasne lub ciemne, gdy skojarzone ustawienie SystemBackdropConfiguration.Theme ulega zmianie. Aby dopasować nowy motyw, należy ręcznie zaktualizować te właściwości.

Aby można było używać materiału tła w aplikacji, wymagane są następujące elementy:

  • obsługa systemu

    System, w którym działa aplikacja, musi obsługiwać materiał w tle. Aby upewnić się, że materiał tła jest obsługiwany w czasie wykonywania, wywołaj metodę MicaController.IsSupported lub DesktopAcrylicController.IsSupported.

  • Prawidłowy cel

    Należy podać element docelowy, który implementuje interfejs ICompositionSupportsSystemBackdrop. W aplikacji XAML okno XAML implementuje ten interfejs i jest używane jako tło docelowe.

  • Obiekt SystemBackdropConfiguration

    SystemBackdropConfiguration udostępnia kontrolerowi tła systemu informacje o zasadach specyficznych dla aplikacji w celu prawidłowego skonfigurowania materiału tła systemu.

  • obiekt DispatcherQueue.

    Potrzebujesz dostępnego elementu Windows.System.DispatcherQueue w głównym wątku XAML. Zobacz klasę WindowsSystemDispatcherQueueHelper w przykładowym kodzie lub w przykładzie WinUI 3 Gallery.

Przykład: Użyj mica w aplikacji AppSDK/WinUI 3 systemu Windows

W tym przykładzie pokazano, jak skonfigurować materiał tła Mica w aplikacji XAML.

Napiwek

Zobacz również następujące przykładowe projekty w witrynie GitHub:

C#: Okno SampleSystemBackdropsWindow w galerii WinUI3.

C++/WinRT: przykładowy zestaw SDK aplikacji systemu Windows 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;
        }
    }
    ...
};
...