Bagikan melalui

Gambaran umum windowing untuk WinUI 3 dan Windows App SDK

Fungsionalitas windowing dalam aplikasi WinUI disediakan oleh kombinasi kelas XAML Window dan AppWindow kelas , yang keduanya didasarkan pada model Win32 HWND.

Buka aplikasi Galeri WinUI 3 dan lihat Sampel windowing beraksi

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

XAML Window

Di aplikasi Anda, objek jendela adalah instans kelas Microsoft.UI.Xaml.Window (atau kelas turunan) yang mewakili jendela dalam kode program Anda. Anda membuatnya langsung dengan panggilan ke konstruktor. XAML Window adalah tempat Anda melampirkan konten aplikasi dan mengelola siklus hidup jendela aplikasi Anda.

HWND

Jendela aplikasi dibuat oleh Windows sistem operasi dan diwakili oleh objek jendela Win32. Ini adalah kontainer yang dikelola sistem tempat konten Anda dihosting, dan mewakili entitas yang berinteraksi dengan pengguna saat mereka mengubah ukuran dan memindahkan aplikasi Anda di layar. (Lihat Tentang Windows dalam dokumentasi Win32 untuk informasi selengkapnya.)

Setelah Windows membuat jendela aplikasi, fungsi pembuatan mengembalikan window handle (HWND) yang secara unik mengidentifikasi jendela. A window handle memiliki jenis data HWND, meskipun muncul di C# sebagai IntPtr. Ini adalah handle buram ke struktur data internal Windows yang sesuai dengan jendela yang digambar oleh sistem operasi dan menggunakan sumber daya sistem ketika hadir.

HWND dibuat setelah objek XAML Window, biasanya ketika Window.Activate dipanggil.

AppWindow

Windows App SDK menyediakan fungsionalitas windowing tambahan melalui kelas Microsoft.UI.Windowing.AppWindow AppWindow mewakili abstraksi tingkat tinggi HWND. Ada pemetaan 1:1 antara AppWindow dan HWND tingkat atas di aplikasi Anda. AppWindow dan kelas terkait menyediakan API untuk mengelola banyak aspek jendela tingkat atas aplikasi Anda tanpa perlu mengakses HWND secara langsung.

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

Diagram WINDOWING API

Diagram ini menunjukkan hubungan antara kelas dan API yang Anda gunakan untuk mengelola jendela di aplikasi Anda, dan kelas mana yang bertanggung jawab atas setiap bagian manajemen jendela. Dalam beberapa kasus, seperti ExtendsContentIntoTitleBar, API adalah anggota AppWindow untuk membuatnya tersedia untuk kerangka kerja UI lain, tetapi juga diekspos pada kelas Window untuk kenyamanan. Diagram ini tidak komprehensif, tetapi menunjukkan API yang paling umum digunakan.

diagram pemrosesan jendela win u i

Nota

Anda dapat menggunakan API AppWindow dengan kerangka kerja UI apa pun yang didukung Windows App SDK - Win32, WPF, WinForms, atau WinUI. Untuk kerangka kerja selain WinUI, fungsionalitas yang ditunjukkan dalam kotak XAML Window diagram akan digantikan oleh API windowing khusus kerangka kerja yang sesuai:

Window/AppWindow Perbandingan API

Jika Anda menggunakan WinUI XAML sebagai kerangka kerja UI aplikasi Anda, api Window dan AppWindow tersedia untuk Anda. Mulai Windows App SDK 1.4, Anda dapat menggunakan properti Window.AppWindow untuk mendapatkan objek AppWindow dari jendela XAML yang ada. Dengan objek AppWindow ini Anda memiliki access ke API manajemen jendela tambahan.

Penting

Jika Anda tidak menggunakan WinUI 1.3 atau yang lebih baru, gunakan API interoperabilitas untuk mendapatkan AppWindow agar dapat menggunakan AppWindow. Untuk informasi selengkapnya tentang API interop, lihat Manage app windows - kerangka kerja UI dan interop HWND dan sampel galeri Windowing.

Manajemen seumur hidup

XAML Window AppWindow
Pembangun Buat, DapatkanDariWindowId
Aktifkan Perlihatkan, Sembunyikan
Menutup, Ditutup Hancurkan, Menghancurkan, Menutup
>>> Id, OwnerWindowId

Saat Anda membuat project WinUI baru di Visual Studio, templat project menyediakan kelas MainWindow untuk Anda, yang merupakan sub-kelas Window. Jika aplikasi Anda hanya memerlukan satu jendela, ini saja yang Anda butuhkan. Untuk mempelajari cara membuat dan mengelola jendela tambahan, dan alasan yang mungkin Anda inginkan, lihat Menampilkan beberapa jendela untuk aplikasi Anda.

Kelas AppWindow ini memiliki API untuk membuat dan menghancurkan jendela baru; namun, untuk aplikasi WinUI, Anda tidak akan melakukan ini dalam praktiknya karena tidak ada API untuk melampirkan konten ke jendela yang Anda buat. Sebagai gantinya, Anda mendapatkan instans AppWindow yang dibuat oleh sistem dan terkait dengan XAML Window dan HWND. Di WinUI 1.4 dan versi yang lebih baru, Anda dapat menggunakan properti Window.AppWindow untuk mendapatkan instans AppWindow. Dalam kasus lain, Anda dapat menggunakan metode statis AppWindow.GetFromWindowId untuk mendapatkan instance AppWindow. Lihat Mengelola jendela aplikasi untuk informasi selengkapnya.

Content

XAML Window AppWindow
Content N/A

.Window Properti konten adalah tempat Anda melampirkan konten aplikasi ke jendela yang menampilkannya. Anda dapat melakukan ini di XAML atau dalam kode.

Judul, ikon, dan bilah judul

XAML Window AppWindow
Title Title
SetTitleBar TitleBar
>>> SetIcon, SetTaskbarIcon, SetTitleBarIcon
ExtendsContentIntoTitleBar AppWindow.TitleBar.ExtendsContentIntoTitleBar

Anda dapat memodifikasi bilah judul aplikasi ke berbagai derajat; mengatur judul dan ikon, mengubah warna, atau sepenuhnya mengganti bilah judul dengan konten aplikasi kustom.

Untuk informasi tentang menggunakan API bilah judul, termasuk contoh kode, lihat Kustomisasi bilah judul.

Ukuran dan posisi

XAML Window AppWindow
Batasan Posisi, Ukuran, Ukuran Tampilan Klien
Ukuran Berubah Diubah (DidPositionChange, DidSizeChange)
>>> Pindahkan, Ubah Ukuran, Ubah Ukuran Klien, Pindahkan dan Ubah Ukuran
>>> MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Anda menggunakan properti Window.Bounds dan peristiwa SizeChanged untuk mengelola elemen di UI aplikasi Anda, seperti memindahkannya saat ukuran jendela berubah. XAML menggunakan effective pixels (epx), bukan piksel fisik aktual. Effective pixels adalah unit pengukuran virtual, dan digunakan untuk mengekspresikan dimensi dan penspasian tata letak, terlepas dari kepadatan layar.

AppWindow, di sisi lain, menggunakan Window Sistem Koordinat, di mana unit pengukuran dasar adalah piksel perangkat fisik. Anda menggunakan AppWindow API untuk tindakan jendela, seperti mengubah ukuran jendela atau memindahkannya terkait dengan sesuatu yang lain di layar.

Dalam beberapa kasus, Anda mungkin perlu menggunakan pengukuran dari satu kelas ke kelas lain; dalam hal ini, Anda harus mengonversi antara effective pixels dan piksel perangkat. Misalnya, jika Anda mengatur area seret di bilah judul kustom, Anda harus mengonversi ukuran. Untuk contoh cara menggunakan XamlRoot.RasterizationScale untuk mengonversi pengukuran, lihat bagian konten interaktif dari artikel kustomisasi bilah Judul .

Penampilan dan perilaku

XAML Window AppWindow
SystemBackdrop N/A
>>> Penyaji, SetPresenter
>>> IsShownInSwitchers
Terlihat, VisibilitasBerubah IsVisible, Changed (DidVisibilityChange)
DispatcherQueue DispatcherQueue, AssociateWithDispatcherQueue
Compositor N/A

API XAML Window umumnya bertanggung jawab atas tampilan konten aplikasi Anda, seperti latar belakang. Untuk informasi selengkapnya tentang SystemBackdrop, lihat Menerapkan bahan Mica atau Akrilik.

AppWindow API bertanggung jawab atas bagian non-klien jendela dan interaksi aplikasi Anda dengan Windows OS.

Nota

Kelas XAML Window memiliki beberapa properti yang dibawa dari UWP Windows. UI. Xaml.Window kelas, tetapi tidak didukung di aplikasi WinUI. Properti ini selalu memiliki null nilai dan tidak digunakan dalam aplikasi WinUI: CoreWindow, Current, dan Dispatcher.

Lacak jendela saat ini

Meskipun properti Current tidak didukung di aplikasi WinUI, Anda mungkin masih perlu mengakses API Window dari tempat lain di aplikasi Anda. Misalnya, Anda mungkin perlu mendapatkan Window batas atau menangani Window. Peristiwa SizeChanged dari kode untuk Halaman. Dalam hal ini, Anda dapat memberikan access ke Window dengan cara yang sama dengan properti Current dengan menggunakan properti statis publik pada kelas App Anda.

Untuk melakukannya, ubah deklarasi Window di kelas App seperti yang ditunjukkan.

// App.xaml.cs in a WinUI app
public partial class App : Application
{
    ...
    public static Window Window { get { return m_window; } }
    private static Window m_window;
}

// App.xaml.h in a WinUI app
...
struct App : AppT<App>
{
    ...
    static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };

private:
    static winrt::Microsoft::UI::Xaml::Window window;
};
...

// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...

Kemudian, untuk mengakses Window dari tempat lain di aplikasi Anda, gunakan App.Window seperti ini:

// MainPage.xaml.cs in a WinUI app
var width = App.Window.Bounds.Width;

// MainPage.xaml.cpp in a WinUI app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };

Penting

Menggunakan properti statis Window di kelas Anda App berguna jika aplikasi Anda hanya menggunakan satu jendela. Jika aplikasi Anda menggunakan beberapa jendela, Anda harus menggunakan WindowId untuk melacak Window instans sebagai gantinya, untuk memastikan bahwa Anda mengakses instans yang benar dari Window. Lihat Menampilkan beberapa jendela untuk aplikasi Anda untuk informasi dan contoh selengkapnya.

  • Last updated on