Bagikan melalui

Gambaran umum pengelolaan jendela untuk WinUI 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

Aplikasi Galeri WinUI 3 mencakup contoh interaktif dari sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di 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 yang memungkinkan Anda 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.

win u i windowing diagram

Nota

Anda dapat menggunakan AppWindow API dengan kerangka kerja UI apa pun yang Windows didukung App SDK - Win32, WPF, WinForms, atau WinUI 3. Untuk kerangka kerja selain WinUI 3, 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 3 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 ini AppWindow , Anda memiliki akses ke API manajemen jendela tambahan.

Penting

Jika Anda tidak menggunakan WinUI 3 1.3 atau yang lebih baru, gunakan API interop untuk mendapatkan AppWindow guna menggunakan API AppWindow. Untuk informasi selengkapnya tentang API interop, lihat Mengelola jendela aplikasi - kerangka kerja UI dan interop HWND serta sampel galeri Windowing.

Manajemen seumur hidup

XAML Window AppWindow
Constructor Buat, DapatkanDariWindowId
Activate Perlihatkan, Sembunyikan
Menutup, Ditutup Hancurkan, Menghancurkan, Menutup
>>> Id, OwnerWindowId

Saat Anda membuat proyek WinUI baru di Visual Studio, templat proyek menyediakan MainWindow kelas untuk Anda, yang merupakan sub-kelas dari 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 Current properti tidak didukung di aplikasi WinUI, Anda mungkin masih perlu mengakses Window API 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 akses ke Window dengan cara yang sama seperti properti Current dengan menggunakan properti statis publik di kelas App Anda.

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

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