Menerapkan materi Mica atau Akrilik di aplikasi desktop untuk Windows 11

Materials di Windows 11 adalah efek visual yang diterapkan pada permukaan antarmuka pengguna yang menyerupai artefak kehidupan nyata. Bahan yang menutupi, seperti Mika dan Akrilik, digunakan sebagai lapisan dasar di bawah kontrol UI interaktif.

Mica adalah bahan buram yang menggabungkan tema pengguna dan wallpaper desktop untuk menciptakan penampilan yang sangat dipersonalisasi. Mica dirancang untuk performa karena hanya menangkap wallpaper latar belakang sekali untuk membuat visualisasinya, jadi kami merekomendasikannya untuk lapisan fondasi aplikasi Anda, terutama di area bilah judul.

Akrilik adalah bahan semi transparan yang mereplikasi efek kaca beku. Ini hanya digunakan untuk permukaan sementara yang mematikan cahaya seperti flyout dan menu konteks.

Artikel ini menjelaskan cara menerapkan Mica atau Acrylic sebagai lapisan dasar aplikasi XAML SDK Aplikasi Windows/WinUI 3 Anda.

Nota

• Untuk menggunakan materi backdrop di aplikasi Win32, lihat Terapkan Mica pada aplikasi desktop Win32 di Windows 11.
• Untuk akrilik dalam aplikasi yang diterapkan ke elemen UI (bukan latar belakang jendela), lihat Akrilik dalam aplikasi.

Cara menggunakan bahan backdrop

• API Penting: Properti Window.SystemBackdrop, Kelas MicaBackdrop, Kelas DesktopAcrylicBackdrop, Kelas SystemBackdropConfiguration

Buka aplikasi Galeri WinUI 3 dan lihat Latar Belakang Sistem beraksi

Aplikasi Galeri WinUI 3 mencakup contoh interaktif kontrol dan fitur WinUI. Dapatkan aplikasi dari Microsoft Store atau telusuri kode sumber pada GitHub.

Untuk menerapkan material Mica atau Acrylic pada aplikasi Anda, atur properti SystemBackdrop ke XAML SystemBackdrop (biasanya, salah satu latar belakang bawaan, seperti MicaBackdrop atau DesktopAcrylicBackdrop).

Elemen-elemen ini memiliki SystemBackdrop properti:

• CommandBarFlyoutCommandBar.Latar Belakang Sistem
• ContentIsland.SystemBackdrop
• DesktopWindowXamlSource.SystemBackdrop
• FlyoutBase.SystemBackdrop
• MenuFlyoutPresenter.SystemBackdrop (Fitur latar belakang sistem pada presenter menu)
• Latar Belakang Sistem Popup
• Window.SystemBackdrop

Contoh-contoh ini menunjukkan cara mengatur latar belakang sistem di XAML.

Mica

Mica biasanya digunakan sebagai latar untuk jendela aplikasi.

<Window
    ... >

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

</Window>

Mica Alt

Untuk menggunakan varian Mica Alt, atur properti Kind ke BaseAlt.

<Window
    ... >

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

</Window>

Acrylic

Akrilik Desktop dapat digunakan sebagai latar belakang untuk Jendela.

<Window
    ... >

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

</Window>

Akrilik dalam Antarmuka Pengguna Sementara

Akrilik juga umumnya digunakan sebagai latar belakang untuk UI sementara, seperti flyout. Anda dapat mengatur ini di XAML atau dalam kode, karena flyout sering dibuat secara dinamis.

<Flyout
    ... >

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

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

Menerapkan backdrop sistem ke elemen XAML apa pun

• API Penting: SystemBackdropElement

Buka aplikasi Galeri WinUI 3 dan lihat SystemBackdropElement beraksi

Aplikasi Galeri WinUI 3 mencakup contoh interaktif kontrol dan fitur WinUI. Dapatkan aplikasi dari Microsoft Store atau telusuri kode sumber pada GitHub.

Properti Window.SystemBackdrop menerapkan material backdrop ke seluruh jendela. Jika Anda perlu menerapkan Mica atau Acrylic ke area tertentu pada UI Anda — seperti kartu, panel, atau area yang dibatasi — gunakan kontrol SystemBackdropElement sebagai gantinya.

SystemBackdropElement adalah kontrol XAML yang menampilkan material latar belakang sistem di dalam batas kontrol itu sendiri. Anda dapat menempatkannya di mana pun dalam pohon XAML, mengatur ukurannya secara eksplisit atau membiarkannya mengisi elemen induknya, dan menggunakan CornerRadius untuk memberikan sudut membulat.

Menggunakan SystemBackdropElement di XAML

Tempatkan SystemBackdropElement sebagai saudara di belakang konten lain, atau sebagai host latar belakang di dalam Grid. Atur properti SystemBackdrop ke material yang diinginkan.

<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>

Ganti material latar belakang saat runtime

Anda dapat mengubah properti SystemBackdrop saat runtime. Contoh ini memungkinkan pengguna memilih antara Acrylic dan dua varian Mica:

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

Nota

SystemBackdropElement menerapkan latar belakang sistem pada elemen di dalam halaman, bukan pada jendela. Untuk backdrop pada tingkat jendela, gunakan properti Window.SystemBackdrop seperti yang dijelaskan sebelumnya dalam artikel ini. Kedua pendekatan tersebut bersifat independen dan dapat digunakan bersama-sama dalam aplikasi yang sama.

Tingkat Lanjut: Cara menggunakan pengontrol latar belakang sistem

Nota

Dimulai dengan SDK Aplikasi Windows 1.3, Anda dapat menerapkan materi dengan mengatur properti Window.SystemBackdrop ke XAML SystemBackdrop seperti yang dijelaskan di bagian sebelumnya. Ini adalah cara yang disarankan untuk menerapkan materi untuk sebagian besar aplikasi.

Sisa artikel ini menunjukkan cara menggunakan API MicaController dan DesktopAcrylicController, yang memberi pengguna lebih banyak kontrol atas perilaku latar belakang.

Untuk menggunakan materi backdrop di aplikasi, Anda dapat menggunakan salah satu pengontrol yang mengimplementasikan antarmuka ISystemBackdropController (MicaController atau DesktopAcrylicController). Kelas-kelas ini mengelola pemrosesan materi latar belakang sistem serta penanganan kebijakan sistem untuk materi tersebut.

Untuk menggunakan Mica sebagai bahan backdrop Anda, buat objek MicaController . Untuk menggunakan Acrylic, buat objek DesktopAcrylicController . Pengaturan dan kode pendukung adalah sama untuk setiap jenis material latar belakang sistem.

Membuat MicaController

C#

MicaController micaController;

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

C++

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

Membuat sebuah DesktopAcrylicController

C#

DesktopAcrylicController acrylicController;

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

C++

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

Pengontrol bereaksi terhadap tema Terang dan Gelap sistem secara default. Untuk mengambil alih perilaku ini, Anda dapat mengatur properti berikut pada pengontrol:

• FallbackColor
• KecerahanKegelapan
• TintColor
• Opasitas Warna

Nota

Setelah menyesuaikan salah satu dari empat properti pengontrol, properti tersebut tidak lagi menerapkan nilai Terang atau Gelap default saat SystemBackdropConfiguration.Theme terkait berubah. Anda perlu memperbarui properti tersebut secara manual agar sesuai dengan tema baru.

Untuk menggunakan materi backdrop di aplikasi Anda, item berikut diperlukan:

• Dukungan sistem

  Sistem yang digunakan aplikasi harus mendukung material latar belakang. Panggil metode MicaController.IsSupported atau DesktopAcrylicController.IsSupported untuk memastikan materi backdrop didukung saat runtime.

• Target yang valid

  Anda harus menyediakan target yang mengimplementasikan antarmuka ICompositionSupportsSystemBackdrop . Dalam aplikasi XAML, Jendela XAML mengimplementasikan antarmuka ini dan digunakan sebagai target backdrop.

• Objek SystemBackdropConfiguration

  SystemBackdropConfiguration menyediakan kontroler backdrop sistem dengan informasi kebijakan spesifik aplikasi guna mengonfigurasi bahan backdrop sistem secara tepat.

• Objek DispatcherQueue

  Anda memerlukan Windows.System.DispatcherQueue yang tersedia pada utas XAML utama. Hubungi DispatcherQueue.EnsureSystemDispatcherQueue() untuk memastikan keberadaannya.

Contoh: Menggunakan Mica dengan pengontrol di aplikasi WinUI

Contoh ini menunjukkan cara menyiapkan materi backdrop Mica menggunakan pengontrol di aplikasi XAML.

Tip

Selain itu, lihat contoh proyek ini di GitHub:

C#: SampleSystemBackdropsWindow di Galeri WinUI.

C++/WinRT: SDK Aplikasi Windows sampel Mica.

C#

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

C++

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

Artikel terkait

• Gambaran umum materi
• Akrilik dalam aplikasi
• Materi di Windows 11
• Mika
• Akrilik
• Gunakan Mica pada aplikasi desktop Win32 untuk Windows 11
• Galeri WinUI — Contoh System Backdrops (GitHub)