Mengelola jendela aplikasi

Berlaku untuk: ✅ WinUI 3, ✅ Windows App SDK

Windows App SDK menyediakan kelas Microsoft.UI.Windowing.AppWindow yang 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.

Nota

Artikel ini menunjukkan cara menggunakan AppWindow API di aplikasi Anda. Sebagai prasyarat, kami sarankan Anda membaca dan memahami AppWindow informasi dalam Rangkuman Windowing untuk WinUI dan Windows App SDK, yang berlaku apakah Anda menggunakan WinUI atau kerangka kerja UI lain.

API Penting: AppWindow kelas, kelas OverlappedPresenter

Buka aplikasi Galeri WinUI 3 dan lihat AppWindow 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

Anda dapat menggunakan AppWindow API dengan kerangka kerja UI apa pun yang didukung Windows App SDK - WinUI 3, WPF, WinForms, atau Win32. AppWindow API berfungsi bersama API windowing khusus kerangka kerja:

Anda biasanya menggunakan AppWindow API untuk:

Kelola ukuran dan posisi jendela aplikasi Anda.
Mengelola judul jendela, ikon, dan warna bilah judul; atau buat bilah judul kustom penuh dengan API AppWindowTitleBar .

Lihat Kustomisasi bilah judul untuk informasi dan contoh selengkapnya.
Kelola tampilan dan perilaku jendela dengan API turunan AppWindowPresenter.

Menanggapi AppWindow perubahan

Anda menanggapi perubahan AppWindow dengan menangani peristiwa Diubah tunggal, lalu memeriksa argumen peristiwa (AppWindowChangedEventArgs) untuk menentukan jenis perubahan yang terjadi. Jika perubahan yang Anda minati terjadi, Anda dapat menanggapinya. Potensi perubahan termasuk posisi, ukuran, presenter, visibilitas, dan z-order.

Berikut adalah contoh penangan kejadian AppWindow.Diubah.

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    // ConfigText and SizeText are TextBox controls defined in XAML for the page.
    if (args.DidPresenterChange == true)
    {
        ConfigText.Text = sender.Presenter.Kind.ToString();
    }

    if (args.DidSizeChange == true)
    {
        SizeText.Text = sender.Size.Width.ToString() + ", " + sender.Size.Height.ToString();
    }
}

Window ukuran dan penempatan

Kelas AppWindow ini memiliki beberapa properti dan metode yang dapat Anda gunakan untuk mengelola ukuran dan penempatan jendela.

Kategori	Karakteristik
Properti baca-saja	Posisi, Ukuran, Ukuran Tampilan Klien
Events	Diubah (DidPositionChange, DidSizeChange)
Metode pengukuran dan penempatan	Pindahkan, Ubah Ukuran, Ubah Ukuran Klien, Pindahkan dan Ubah Ukuran
Metode urutan Z	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Panggil Mengubah Ukuran untuk menentukan ukuran jendela baru.

Dalam contoh ini, kode ada di MainWindow.xaml.cs, sehingga Anda dapat menggunakan properti Window.AppWindow untuk mendapatkan instance AppWindow.

public MainWindow()
{
    InitializeComponent();
    AppWindow.Resize(new Windows.Graphics.SizeInt32(1200, 800));
}

Panggil metode Pindahkan untuk mengubah posisi jendela.

Contoh ini memindahkan jendela untuk dipusatkan di layar saat pengguna mengklik tombol.

Ini terjadi dalam file kode untuk kelas Halaman , sehingga Anda tidak secara otomatis memiliki akses ke Window objek atau AppWindow . Anda memiliki beberapa opsi untuk mendapatkan AppWindow.

Jika Anda menyimpan referensi ke Window seperti yang dijelaskan di Lacak jendela saat ini atau Lacak instans Window, Anda bisa mendapatkan Window, lalu dapatkan AppWindow dari properti WindowAppWindow.
Atau, Anda dapat memanggil metode statis AppWindow.GetFromWindowId untuk mendapatkan instans, seperti ditunjukkan AppWindow di sini. (Lihat Menentukan jendela yang menghosting elemen visual.)

private void MoveWindowButton_Click(object sender, RoutedEventArgs e)
{
    AppWindow appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    RectInt32? area = DisplayArea.GetFromWindowId(appWindow.Id, DisplayAreaFallback.Nearest)?.WorkArea;
    if (area == null) return;
    appWindow.Move(new PointInt32((area.Value.Width - appWindow.Size.Width) / 2, (area.Value.Height - appWindow.Size.Height) / 2));
}

Kelas AppWindowPresenter, dan subkelas

Masing-masing AppWindow memiliki AppWindowPresenter (penyaji jendela aplikasi) yang diterapkan padanya. Penyaji dibuat oleh sistem dan diterapkan pada AppWindow saat waktu pembuatan. Setiap sub-kelas AppWindowPresenter menyediakan konfigurasi yang telah ditentukan sebelumnya yang sesuai untuk tujuan jendela. Penyaji turunan AppWindowPresenter ini disediakan, dan tersedia di semua versi OS yang didukung.

CompactOverlayPresenter

Mengonfigurasi jendela always-on-top dengan ukuran tetap, dengan rasio aspek 16:9 untuk memungkinkan pengalaman seperti gambar dalam gambar. Secara default, InitialSize adalah CompactOverlaySize.Small, tetapi Anda dapat mengubahnya menjadi Medium atau Large. Anda juga dapat memanggil AppWindow. Mengubah ukuran untuk mengambil alih rasio aspek 16:9 dan membuat jendela memiliki ukuran yang diinginkan.
FullScreenPresenter

Mengonfigurasi jendela untuk memberikan pengalaman layar penuh yang cocok untuk menonton video. Jendela tidak memiliki batas atau bilah judul, dan menyembunyikan bilah tugas sistem.
OverlappedPresenter

Konfigurasi jendela standar secara default menyediakan batas dengan pegangan untuk mengubah ukuran dan bilah judul dengan tombol untuk meminimalkan, memaksimalkan, dan mengembalikan.

Nota

Sebagai konsep baru dalam model aplikasi Win32, presenter mirip dengan (tetapi tidak sama dengan) kombinasi status jendela dan gaya. Beberapa penyaji juga memiliki perilaku yang ditentukan di dalamnya yang tidak dapat diperiksa dari properti status jendela dan gaya klasik (seperti bilah judul yang menyembunyikan otomatis).

Penyaji bawaan

Penyaji default yang diterapkan saat AppWindow dibuat adalah instans OverlappedPresenter dengan pengaturan properti default. Tidak perlu menyimpan referensi ke penyaji tersebut untuk kembali ke penyaji default jendela setelah menerapkan penyaji lain. Itu karena sistem menyimpan instans yang sama dari presenter ini selama masa pakainya pada AppWindow untuk mana itu dibuat; dan Anda dapat menerapkannya kembali dengan memanggil metode AppWindow.SetPresenter dengan AppWindowPresenterKind.Default sebagai parameter.

Penting

Memanggil SetPresenter(AppWindowPresenterKind.Default) selalu menggunakan kembali instans penyaji default yang dibuat dengan AppWindow. Jika Anda membuat dan menerapkan presenter lain, dan ingin menerapkannya kembali nanti, Anda perlu menyimpan referensi ke presenter Anda.

Anda juga bisa mendapatkan referensi ke instans penyaji default dan memodifikasinya. Jika Anda telah menerapkan penyaji baru, pertama-tama pastikan bahwa penyaji default diterapkan, seperti yang ditunjukkan di sini:

appWindow.SetPresenter(AppWindowPresenterKind.Default);
OverlappedPresenter defaultPresenter = (OverlappedPresenter)appWindow.Presenter;
defaultPresenter.IsMaximizable = false;
defaultPresenter.IsMinimizable = false;

Mengubah OverlappedPresenter

OverlappedPresenter adalah penyaji fleksibel yang dapat Anda konfigurasi dengan berbagai cara.

Metode Create* memungkinkan Anda membuat penyaji yang tumpang tindih dengan pengaturan properti default, atau dengan pengaturan properti yang telah dikonfigurasi sebelumnya untuk penggunaan tertentu.

Tabel ini memperlihatkan bagaimana properti konfigurasi diatur saat Anda membuat objek OverlappedPresenter dari setiap metode.

Harta benda	Create	CreateForContextMenu	CreateForDialog	CreateForToolWindow
HasBorder	`true`	`true`	`true`	`true`
Bilah HasTitle	`true`	`false`	`true`	`true`
IsAlwaysOnTop	`false`	`false`	`false`	`false`
IsMaximizable	`true`	`false`	`false`	`true`
IsMinimizable	`true`	`false`	`false`	`true`
IsModal	`false`	`false`	`false`	`false`
IsResizable	`true`	`false`	`false`	`true`

Penyaji yang diterapkan adalah objek aktif. Perubahan pada properti apa pun dari objek AppWindow.Presenter segera berlaku. Tidak ada peristiwa untuk memberi tahu Anda tentang perubahan ini, tetapi Anda dapat memeriksa properti untuk nilai saat ini kapan saja.

Properti HasBorder dan HasTitleBar bersifat baca-saja. Anda dapat mengatur nilai-nilai ini dengan memanggil metode SetBorderAndTitleBar (SetBorderAndTitleBar(bool hasBorder, bool hasTitleBar)). OverlappedPresenter tidak dapat memiliki bilah judul tanpa batas. Artinya, jika hasTitleBar parameternya adalah true, maka hasBorder parameternya juga harus true. Jika tidak, pengecualian dilemparkan dengan pesan ini:

The parameter is incorrect.
Invalid combination: Border=false, TitleBar=true.

Atur IsMaximizable ke false untuk menyembunyikan tombol maksimalkan di toolbar. Kami menyarankan Anda melakukan ini jika Anda mengatur PreferredMaximumHeight properti atau PreferredMaximumWidth , karena properti ini membatasi ukuran jendela bahkan dalam status dimaksimalkan. Ini tidak memengaruhi panggilan ke metode Maksimalkan .

Atur IsMinimizable untuk false menyembunyikan tombol minimalkan di toolbar. Ini tidak memengaruhi panggilan ke metode Minimalkan .

Atur IsResizable untuk false menyembunyikan kontrol mengubah ukuran dan mencegah pengguna mengubah ukuran jendela. Ini tidak memengaruhi panggilan ke metode AppWindow.Resize.

Atur IsAlwaysOnTop ke true untuk menjaga jendela ini tetap berada di atas jendela lain. Jika Anda memanggil salah AppWindow.MoveInZOrder* satu metode, metode tersebut masih berlaku untuk mengubah urutan z jendela bahkan jika properti ini adalah true.

Atur PreferredMaximumHeight dan PreferredMaximumWidth untuk membatasi ukuran maksimum tempat pengguna dapat meregangkan jendela. Kami menyarankan agar Anda mengatur IsMaximizable ke false jika Anda mengatur properti ukuran maksimum, karena properti ini membatasi ukuran jendela bahkan dalam status dimaksimalkan. Properti ini juga memengaruhi panggilan ke AppWindow. Mengubah ukuran; jendela tidak akan diubah ukurannya lebih besar dari tinggi dan lebar maksimum yang ditentukan.

Atur PreferredMinimumHeight dan PreferredMinimumWidth untuk mengatur ukuran minimum tempat pengguna dapat menyusutkan jendela. Properti ini juga memengaruhi panggilan ke AppWindow. Mengubah ukuran; jendela tidak akan diubah ukurannya lebih kecil dari tinggi dan lebar minimum yang ditentukan.

Anda dapat mengatur IsModal ke true untuk membuat jendela modal. Jendela modal adalah jendela terpisah yang memblokir interaksi dengan jendela pemiliknya sampai ditutup. Namun, untuk membuat jendela modal, Anda juga harus mengatur jendela pemilik; jika tidak, sebuah pengecualian akan dilemparkan dengan pesan berikut:

The parameter is incorrect.

The window should have an owner when IsModal=true.

Untuk mengatur jendela pemilik di aplikasi WinUI memerlukan interop Win32. Untuk informasi selengkapnya dan contoh kode, lihat AppWindow halaman di aplikasi sampel Galeri WinUI.

Menerapkan penyaji

Pemroses tampilan hanya dapat diterapkan ke satu jendela pada satu waktu. Mencoba menerapkan penampil yang sama ke jendela kedua menimbulkan 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.

Saat penyaji baru digunakan (properti dari AppWindow.Presenter berubah), aplikasi Anda diberi tahu oleh peristiwa AppWindow.Changed pada AppWindow yang terpengaruh, dengan properti AppWindowChangedEventArgs.DidPresenterChange disetel ke true.

Petunjuk / Saran

Jika Anda menerapkan penyaji yang dimodifikasi, dan mengizinkan perubahan antar penyaji, pastikan untuk menyimpan referensi ke penyaji yang dimodifikasi sehingga dapat diterapkan kembali ke AppWindow.

Contoh ini menunjukkan cara melakukan hal berikut:

Gunakan properti AppWindow.Presenter untuk mendapatkan penyaji saat ini.
Gunakan properti AppWindowPresenter.Kind untuk memeriksa jenis konfigurasi apa yang saat ini diterapkan.
Panggil AppWindow. SetPresenter untuk mengubah konfigurasi saat ini.

Di sini, sebuah penyaji dibuat, kemudian dimodifikasi, dan diterapkan di dalam konstruktor untuk jendela.

OverlappedPresenter presenter = OverlappedPresenter.Create();
presenter.PreferredMinimumWidth = 420;
presenter.PreferredMinimumHeight = 550;
AppWindow.SetPresenter(presenter);

Di Halaman yang menjadi isi jendela, Anda bisa mendapatkan referensi ke AppWindow dan presenter yang diterapkan.

AppWindow appWindow;
OverlappedPresenter modifiedPresenter;

private void AppWindowPage_Loaded(object sender, RoutedEventArgs e)
{
    appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    modifiedPresenter = (OverlappedPresenter)appWindow.Presenter;

    appWindow.Changed += AppWindow_Changed;
}

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    if (args.DidPresenterChange)
    {
        // ConfigText is a TextBox control defined in XAML for the page.
        ConfigText.Text = appWindow.Presenter.Kind.ToString();
    }
}

private void CompactOverlayButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.CompactOverlay)
    {
        appWindow.SetPresenter(CompactOverlayPresenter.Create());
        fullScreenButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

private void FullScreenButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.FullScreen)
    {
        appWindow.SetPresenter(FullScreenPresenter.Create());
        compactOverlayButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

Kerangka kerja UI dan interoperabilitas HWND

Kelas AppWindow ini 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 UI tersebut, Anda dapat menggunakan fungsi interop windowing (lihat di bawah) yang disediakan dalam Windows App SDK untuk mengakses AppWindow yang sesuai beserta metode, properti, dan peristiwanya.

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

Penyesuaian bilah judul yang mudah; secara default, fitur ini mempertahankan tampilan UI Windows 11 (sudut membulat, menu flyout grup snap).
Pengalaman layar penuh dan mode gambar dalam gambar (compact overlay) yang disediakan oleh sistem.
Lapisan antarmuka Windows Runtime (WinRT) API untuk beberapa konsep inti windowing Win32.

AppWindow Dapatkan untuk versi Windows App SDK sebelum 1.3 (atau kerangka kerja aplikasi desktop lainnya)

Properti Window.AppWindow tersedia di Windows App SDK 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 sebuah aplikasi .NET.

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

Bagian contoh kode di bawah ini menunjukkan kode sumber aktual; berikut adalah langkah-langkah untuk mengambil objek AppWindow dari jendela yang sudah ada.

Ambil HWND untuk objek jendela yang ada (untuk kerangka kerja UI Anda), jika Anda belum memilikinya.
Teruskan HWND tersebut ke fungsi interop GetWindowIdFromWindow untuk mengambil WindowId.
Teruskan WindowId tersebut ke metode statis AppWindow.GetFromWindowId 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!");
    }
}

Untuk contoh selengkapnya tentang cara bekerja dengan AppWindow, lihat sampel galeri Windowing.

Keterbatasan

Windows App SDK saat ini tidak menyediakan metode untuk melampirkan konten kerangka kerja UI ke AppWindow.

Gambaran umum windowing
Kustomisasi bilah judul
migrasi fungsionalitas jendela
Memanggil API interop dari aplikasi .NET
Mengambil sebuah handle jendela (HWND)
Sampel jendela galeri

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-11-25