Bagikan melalui

Mengelola jendela aplikasi (SDK Aplikasi Windows)

  • Artikel

Topik ini berisi bagian Contoh kode.

SDK Aplikasi Windows menyediakan kelas Microsoft.UI.Windowing.AppWindow yang mudah digunakan. AppWindow adalah framework-agnostic, dan tersedia untuk semua aplikasi Windows termasuk Win32, WPF, dan WinForms. Anda dapat membedakan sifat framework-agnostic AppWindow dengan Microsoft.UI.Xaml.Window, yang merupakan kelas jendela khusus untuk kerangka kerja WinUI 3. AppWindow juga merupakan evolusi dari Windows.UI.WindowManagement.AppWindow dari Platform Windows Universal.UI.WindowManagement.AppWindow.

Versi SDK Aplikasi Windows Microsoft.UI.Windowing.AppWindow tidak mengandalkan pola asinkron; dan memberikan umpan balik langsung ke aplikasi Anda tentang apakah panggilan API telah berhasil.

Mulai juga dengan WinUI dan Gunakan SDK Aplikasi Windows dalam proyek yang ada.

Kelas AppWindow

Microsoft.UI.Windowing.AppWindow adalah API windowing tingkat tinggi yang memungkinkan skenario windowing yang mudah digunakan. AppWindow terintegrasi dengan baik dengan UI/UX Windows, dan dengan aplikasi lain.

AppWindow mewakili abstraksi tingkat tinggi dari kontainer yang dikelola sistem untuk konten aplikasi. Ini adalah kontainer tempat konten Anda dihosting; dan mewakili entitas yang berinteraksi dengan pengguna saat mereka mengubah ukuran dan memindahkan aplikasi Anda di layar. Jika Anda terbiasa dengan Win32, jendela aplikasi dapat dilihat sebagai abstraksi tingkat tinggi HWND. Jika Anda terbiasa dengan UWP, jendela aplikasi dapat dilihat sebagai pengganti CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow.

Untuk versi SDK Aplikasi Windows Microsoft.UI.Windowing.AppWindow, kami hanya mendukung HWNDtingkat atas. Ada pemetaan 1:1 antara AppWindow dan HWND tingkat atas.

Masa pakai objek AppWindow dan HWND sama— AppWindow tersedia segera setelah jendela dibuat; dan dihancurkan saat jendela ditutup.

Kelas AppWindowPresenter, dan subkelas

Setiap AppWindow memiliki AppWindowPresenter (penyaji) yang diterapkan padanya. Jika Anda adalah pengembang UWP yang bekerja dengan Windows.UI.WindowManagement.AppWindow, maka ini akan akrab; bahkan jika itu bukan pemetaan fungsionalitas dan perilaku 1:1. Lihat juga migrasi fungsionalitas Windowing.

Sebagai konsep baru untuk model aplikasi Win32, penyaji mirip dengan (tetapi tidak sama dengan) kombinasi status jendela dan gaya. Beberapa penyaji juga memiliki perilaku UI/UX yang didefinisikan di dalamnya yang tidak dapat diperiksa dari properti status jendela dan gaya klasik (seperti titlebar yang disembunyikan secara otomatis).

Secara default, penyaji dibuat oleh sistem, dan diterapkan ke AppWindow pada waktu pembuatan. Di SDK Aplikasi Windows 1.0, pada desktop Windows, jenis penyaji adalah OverlappedPresenter, yang merupakan subkelas AppWindowPresenter. Aplikasi Anda tidak perlu menyimpannya, atau menyimpan referensi untuk kembali ke penyaji default untuk jendela setelah menerapkan penyaji lain. Itu karena sistem menyimpan instans yang sama dari penyaji ini selama masa pakai AppWindow yang dibuat; dan aplikasi Anda dapat menerapkannya kembali dengan memanggil metode AppWindow.SetPresenter dengan AppWindowPresenterKind.Default sebagai parameter.

Penyaji hanya dapat diterapkan ke satu jendela pada satu waktu. Mencoba menerapkan penyaji yang sama ke jendela kedua melemparkan pengecualian. Itu berarti bahwa jika Anda memiliki beberapa jendela, dan Anda ingin mengalihkan masing-masing jendela ke mode presentasi tertentu, maka Anda perlu membuat beberapa penyaji dengan jenis yang sama, lalu menerapkan masing-masing ke jendelanya sendiri.

Beberapa penyaji memiliki fungsionalitas yang memungkinkan pengguna untuk membuat perubahan di luar kontrol aplikasi Anda sendiri. Ketika perubahan seperti itu terjadi, aplikasi Anda diberi tahu oleh peristiwa AppWindow.Changed pada AppWindow yang terpengaruh, dengan properti AppWindowChangedEventArgs.DidPresenterChange diatur ke true. Aplikasi Anda kemudian harus memeriksa properti penyaji yang diterapkan untuk melihat apa yang berubah.

Penyaji yang diterapkan adalah objek langsung. Perubahan pada properti objek AppWindow.Presenter berlaku segera.

Penyaji tidak dapat dihancurkan saat diterapkan ke jendela. Untuk menghancurkan objek penyaji, pertama-tama terapkan objek penyaji yang berbeda ke jendela; dengan begitu, penyaji yang ingin Anda hancurkan dihapus dari jendela. Anda dapat melakukannya dengan menerapkan penyaji tertentu lain ke jendela, atau dengan memanggil metode AppWindow.SetPresenter dengan AppWindowPresenterKind.Default sebagai argumen, yang akan menerapkan kembali penyaji yang dibuat sistem default ke jendela. Jika Anda kebetulan menyimpan referensi ke penyaji yang dibuat sistem untuk jendela, maka itu akan valid pada titik ini (yaitu, instans yang pertama kali dibuat untuk jendela diterapkan kembali).

Penyaji yang tersedia

Penyaji turunan AppWindowPresenter ini disediakan, dan tersedia di semua versi OS yang didukung.

  • CompactOverlayPresenter. Membuat jendela always-on-top dengan ukuran tetap, dengan rasio aspek 16:9 untuk memungkinkan pengalaman seperti gambar dalam gambar.
  • FullScreenPresenter. Memungkinkan jendela untuk masuk ke pengalaman layar penuh.
  • Tumpang tindihPresenter. Penyaji default yang dibuat sistem, yang memungkinkan Anda meminta dan bereaksi untuk meminimalkan/memaksimalkan/memulihkan operasi dan perubahan status.

Kerangka kerja UI dan interop HWND

Kelas AppWindow tersedia untuk HWND tingkat atas apa pun di aplikasi Anda. Itu berarti bahwa ketika Anda bekerja dengan kerangka kerja UI desktop (termasuk WinUI 3), Anda dapat terus menggunakan titik masuk kerangka kerja tersebut untuk membuat jendela, dan melampirkan kontennya. Dan setelah Anda membuat jendela dengan kerangka kerja UI tersebut, Anda dapat menggunakan fungsi interop windowing (lihat di bawah) yang disediakan dalam SDK Aplikasi Windows untuk mengakses AppWindow yang sesuai dan metode, properti, dan peristiwanya.

Beberapa manfaat menggunakan AppWindow (bahkan saat bekerja dengan kerangka kerja UI) adalah:

  • Penyesuaian bilah judul yang mudah; yang secara default mempertahankan UI Windows 11 (sudut bulat, flyout grup snap).
  • Pengalaman layar penuh dan overlay ringkas yang disediakan sistem (gambar dalam gambar).
  • Permukaan WINDOWS Runtime (WinRT) API untuk beberapa konsep windowing Inti Win32.

Contoh kode

Contoh kode ini menunjukkan cara mengambil Microsoft.UI.Windowing.AppWindow dari jendela WinUI 3 dengan menggunakan properti Microsoft.UI.Xaml.Window.AppWindow. Untuk menggunakan contoh, buat proyek Aplikasi Kosong, Paket (WinUI 3 di Desktop) baru, dan tempelkan kode.

Untuk detail tambahan tentang cara bekerja dengan AppWindow, lihat sampel galeri Windowing.

// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow = this.AppWindow;

    if (appWindow != null)
    {
        // With a non-null AppWindow object, you can call its methods
        // to manipulate the window. As an example, let's change the title
        // text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = this->AppWindow();

    if (appWindow)
    {
        // With a non-null AppWindow object, you can call its methods
        // to manipulate the window. As an example, let's change the title
        // text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

Contoh kode untuk versi SDK Aplikasi Windows sebelum 1.3 (atau kerangka kerja aplikasi desktop lainnya)

Properti Microsoft.UI.Xaml.Window.AppWindow (digunakan dalam contoh kode di atas) tersedia di SDK Aplikasi Windows versi 1.3 dan yang lebih baru. Untuk versi sebelumnya, Anda dapat menggunakan contoh kode yang setara secara fungsional di bagian ini.

C#. Pembungkus .NET untuk fungsi interop windowing diimplementasikan sebagai metode kelas Microsoft.UI.Win32Interop. Lihat juga Memanggil API interop dari aplikasi .NET.

C++. Fungsi interop didefinisikan dalam file header winrt/Microsoft.ui.interop.h .

Bagian Contoh kode di bawah ini menunjukkan kode sumber aktual; tetapi berikut adalah resep untuk mengambil objek AppWindow yang diberi jendela yang ada:

  1. Ambil HWND untuk objek jendela yang ada (untuk kerangka kerja UI Anda), jika Anda belum memilikinya.
  2. Teruskan HWND tersebut ke fungsi interop GetWindowIdFromWindow untuk mengambil WindowId.
  3. Teruskan WindowId tersebut ke metode AppWindow.GetFromWindowId statis untuk mengambil AppWindow.
// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    var hWnd =
        WinRT.Interop.WindowNative.GetWindowHandle(this);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft.UI.WindowId windowId =
        Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow =
        Microsoft.UI.Windowing.AppWindow.GetFromWindowId(windowId);

    if (appWindow != null)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include "microsoft.ui.xaml.window.h" // For the IWindowNative interface.
#include <winrt/Microsoft.UI.Interop.h> // For the WindowId struct and the GetWindowIdFromWindow function.
#include <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    auto windowNative{ this->m_inner.as<::IWindowNative>() };
    HWND hWnd{ 0 };
    windowNative->get_WindowHandle(&hWnd);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft::UI::WindowId windowId = 
        Microsoft::UI::GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = 
        Microsoft::UI::Windowing::AppWindow::GetFromWindowId(windowId);

    if (appWindow)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

Batasan

  • AppWindow adalah API WinUI 3. Itu berarti bahwa itu hanya tersedia untuk aplikasi desktop (baik yang dikemas maupun tidak dikemas); dan tidak tersedia untuk aplikasi UWP.
  • SDK Aplikasi Windows saat ini tidak menyediakan metode untuk melampirkan konten kerangka kerja UI ke AppWindow. Tetapi lihat bagian Contoh kode .
  • Kustomisasi bilah judul didukung di Windows 11 dan yang lebih baru; dan di Windows 10 untuk versi 1.2 dan yang lebih baru dari SDK Aplikasi Windows. Untuk detailnya, lihat Kustomisasi bilah judul.