Bagikan melalui

Kontrol WinRT XAML host di aplikasi desktop (Kepulauan XAML)

  • Artikel

Penting

Topik ini menggunakan atau menyebutkan jenis dari repositori GitHub CommunityToolkit/Microsoft.Toolkit.Win32 . Untuk informasi penting tentang dukungan Kepulauan XAML, silakan lihat Pemberitahuan Kepulauan XAML di repositori tersebut.

Mulai Windows 10, versi 1903, Anda dapat menghosting kontrol WinRT XAML di aplikasi desktop non-UWP menggunakan fitur yang disebut Kepulauan XAML. Fitur ini memungkinkan Anda untuk meningkatkan tampilan, nuansa, dan fungsionalitas aplikasi WPF, Formulir Windows, dan desktop C++ (Win32) yang ada dengan fitur UI Windows terbaru yang hanya tersedia melalui kontrol WinRT XAML. Ini berarti Anda dapat menggunakan fitur UWP seperti Windows Ink dan kontrol yang mendukung Sistem Fluent Design di aplikasi desktop WPF, Formulir Windows, dan C++ yang ada.

Anda dapat menghosting kontrol WinRT XAML apa pun yang berasal dari Windows.UI.Xaml.UIElement, termasuk:

  • Sebagian besar kontrol WinRT XAML pihak pertama yang disediakan oleh Windows SDK atau pustaka WinUI 2 (lihat pengecualian).
  • Kontrol WinRT XAML kustom apa pun (misalnya, kontrol pengguna yang terdiri dari beberapa kontrol WinRT XAML yang bekerja sama). Anda harus memiliki kode sumber untuk kontrol kustom sehingga Anda dapat mengkompilasinya dengan aplikasi Anda.

Pada dasarnya, Kepulauan XAML dibuat dengan menggunakan API hosting WinRT XAML. API ini terdiri dari beberapa kelas Windows Runtime dan antarmuka COM yang diperkenalkan di Windows 10, versi 1903 SDK. Kami juga menyediakan serangkaian kontrol .NET Pulau XAML di Windows Community Toolkit yang menggunakan API hosting WinRT XAML secara internal dan memberikan pengalaman pengembangan yang lebih nyaman untuk aplikasi WPF dan Formulir Windows.

Cara Anda menggunakan Kepulauan XAML tergantung pada jenis aplikasi Anda dan jenis kontrol WinRT XAML yang ingin Anda host.

Catatan

Jika Anda memiliki umpan balik tentang Kepulauan XAML, buat masalah baru di repositori Microsoft.Toolkit.Win32 dan tinggalkan komentar Anda di sana.

Persyaratan

Kepulauan XAML memiliki persyaratan run time berikut:

  • Windows 10, versi 1903, atau rilis yang lebih baru.
  • Jika aplikasi Anda tidak dibungkus dalam paket MSIX untuk penyebaran, komputer harus menginstal Visual C++ Runtime .

Aplikasi WPF dan Formulir Windows

Catatan

Menggunakan Kepulauan XAML untuk menghosting kontrol WinRT XAML di WPF dan aplikasi Formulir Windows saat ini hanya didukung di aplikasi yang menargetkan .NET Core 3.x. Kepulauan XAML belum didukung di aplikasi yang menargetkan .NET, atau di aplikasi yang versi .NET Framework apa pun.

Sebaiknya aplikasi WPF dan Formulir Windows menggunakan kontrol .NET Pulau XAML yang tersedia di Windows Community Toolkit. Kontrol ini menyediakan model objek yang menirus (atau menyediakan akses ke) properti, metode, dan peristiwa kontrol WinRT XAML yang sesuai. Mereka juga menangani perilaku seperti navigasi keyboard dan perubahan tata letak.

Ada dua set kontrol Pulau XAML untuk WPF dan aplikasi Formulir Windows: kontrol yang dibungkus dan kontrol host.

Kontrol yang dibungkus

Aplikasi WPF dan Formulir Windows dapat menggunakan pilihan kontrol Pulau XAML yang membungkus antarmuka dan fungsionalitas kontrol WinRT XAML tertentu. Anda dapat menambahkan kontrol ini langsung ke permukaan desain proyek WPF atau Formulir Windows Anda dan kemudian menggunakannya seperti kontrol WPF atau Formulir Windows lainnya di perancang.

Kontrol WinRT XAML yang dibungkus berikut saat ini tersedia di Toolkit Komunitas Windows.

Menguasai OS minimum yang didukung Deskripsi
InkCanvas
InkToolbar		 Windows 10, versi 1903 Sediakan permukaan dan toolbar terkait untuk interaksi pengguna berbasis Windows Ink di aplikasi desktop Formulir Windows atau WPF Anda.
MediaPlayerElement Windows 10, versi 1903 Menyematkan tampilan yang mengalirkan dan merender konten media seperti video di aplikasi desktop Formulir Windows atau WPF Anda.
MapControl Windows 10, versi 1903 Memungkinkan Anda menampilkan peta simbolis atau fotorealistik di aplikasi desktop Formulir Windows atau WPF Anda.

Untuk panduan yang menunjukkan cara menggunakan kontrol WinRT XAML yang dibungkus, lihat Menggunakan Kepulauan XAML untuk menghosting kontrol XAML UWP di aplikasi C# WPF.

Kontrol host

Untuk kontrol kustom dan skenario lain di luar yang tercakup oleh kontrol terbungkus yang tersedia, WPF dan aplikasi Formulir Windows juga dapat menggunakan kontrol WindowsXamlHost yang tersedia di Toolkit Komunitas Windows.

Menguasai OS minimum yang didukung Deskripsi
WindowsXamlHost Windows 10, versi 1903 Dapat menghosting kontrol WinRT XAML apa pun yang berasal dari Windows.UI.Xaml.UIElement, termasuk kontrol WinRT XAML pihak pertama yang disediakan oleh Windows SDK serta kontrol kustom.

Untuk panduan yang menunjukkan cara menggunakan kontrol WindowsXamlHost , lihat Menggunakan Kepulauan XAML untuk menghosting kontrol XAML UWP di aplikasi C# WPF dan Menghosting kontrol WinRT XAML kustom di aplikasi WPF menggunakan Kepulauan XAML.

Mengonfigurasi proyek Anda untuk menggunakan kontrol .NET Pulau XAML

Kontrol XAML Island .NET memerlukan Windows 10, versi 1903, atau versi yang lebih baru. Untuk menggunakan kontrol ini, instal salah satu paket NuGet yang tercantum di bawah ini. Paket ini menyediakan semua yang Anda butuhkan untuk menggunakan kontrol yang dibungkus XAML Island dan kontrol host, dan termasuk paket NuGet terkait lainnya yang juga diperlukan.

Jenis kontrol Paket NuGet Artikel terkait
Kontrol yang dibungkus Versi 6.0.0 atau yang lebih baru dari paket ini: Menggunakan Kepulauan XAML untuk menghosting kontrol UWP XAML di aplikasi C# WPF
Kontrol host Versi 6.0.0 atau yang lebih baru dari paket ini: Menggunakan Kepulauan XAML untuk menghosting kontrol UWP XAML di aplikasi C# WPF
Menghosting kontrol WinRT XAML kustom di aplikasi WPF

Perhatikan detail berikut:

  • Paket kontrol host juga disertakan dalam paket kontrol yang dibungkus. Anda dapat menginstal paket kontrol yang dibungkus jika Anda ingin menggunakan kedua set kontrol.

  • Jika Anda menghosting kontrol WinRT XAML kustom, Anda juga harus melakukan beberapa langkah tambahan untuk mereferensikan kontrol kustom. Untuk informasi selengkapnya, lihat Menghosting kontrol WinRT XAML kustom di aplikasi WPF menggunakan Kepulauan XAML.

Kontrol tampilan web

Windows Community Toolkit juga menyediakan kontrol .NET berikut untuk menghosting konten web di WPF dan aplikasi Formulir Windows. Kontrol ini sering digunakan dalam skenario modernisasi aplikasi desktop yang sama dengan kontrol Pulau XAML, dan mereka dipertahankan dalam repositori Microsoft.Toolkit.Win32 yang sama dengan kontrol Pulau XAML.

Menguasai OS minimum yang didukung Deskripsi
WebView Windows 10, versi 1803 Menggunakan mesin penyajian Microsoft Edge untuk menampilkan konten web.
WebViewCompatible Windows 7 Menyediakan versi WebView yang kompatibel dengan lebih banyak versi OS. Kontrol ini menggunakan mesin penyajian Microsoft Edge untuk menampilkan konten web pada Windows 10 versi 1803 dan yang lebih baru, dan mesin penyajian Internet Explorer untuk menampilkan konten web pada versi Windows 10, Windows 8.x, dan Windows 7 yang lebih lama.

Untuk menggunakan kontrol ini, instal salah satu paket NuGet ini:

Aplikasi desktop C++ (Win32)

Kontrol .NET Pulau XAML tidak didukung dalam aplikasi desktop C++. Aplikasi ini harus menggunakan API hosting WinRT XAML yang disediakan oleh Windows 10 SDK (versi 1903 dan yang lebih baru).

API hosting WinRT XAML terdiri dari beberapa kelas Windows Runtime dan antarmuka COM yang dapat digunakan aplikasi desktop C++ Anda untuk menghosting kontrol WinRT XAML apa pun yang berasal dari Windows.UI.Xaml.UIElement. Anda dapat menghosting kontrol WinRT XAML di elemen UI apa pun di aplikasi Anda yang memiliki handel jendela terkait (HWND). Untuk informasi selengkapnya tentang API ini, lihat artikel berikut ini.

Catatan

Kontrol yang dibungkus dan kontrol host di Windows Community Toolkit menggunakan API hosting WinRT XAML secara internal dan menerapkan semua perilaku yang Anda perlukan untuk menangani diri Anda sendiri jika Anda menggunakan API hosting WinRT XAML secara langsung, termasuk navigasi keyboard dan perubahan tata letak. Untuk aplikasi WPF dan Formulir Windows, kami sangat menyarankan Anda menggunakan kontrol ini alih-alih API hosting WinRT XAML secara langsung karena mengabstraksi banyak detail implementasi menggunakan API.

Arsitektur Kepulauan XAML

Berikut adalah lihat sekilas bagaimana berbagai jenis kontrol Pulau XAML diatur secara arsitektur di atas API hosting WinRT XAML.

Arsitektur kontrol host

API yang muncul di bagian bawah diagram ini dikirim dengan Windows SDK. Kontrol yang dibungkus dan kontrol host tersedia melalui paket NuGet di Toolkit Komunitas Windows.

Batasan dan solusi

Bagian berikut membahas batasan dan solusi untuk skenario pengembangan UWP tertentu di aplikasi desktop yang menggunakan Kepulauan XAML.

Hanya didukung dengan solusi sementara

✔️ Kontrol hosting dari Pustaka WinUI 2 di Pulau XAML didukung secara kondisional dalam rilis Kepulauan XAML saat ini. Jika aplikasi desktop Anda menggunakan paket MSIX untuk penyebaran, Anda dapat menghosting kontrol WinUI dari versi prarilis atau rilis paket NuGet Microsoft.UI.Xaml . Jika aplikasi desktop Anda tidak dikemas menggunakan MSIX, Anda dapat menghosting kontrol WinUI hanya jika Anda menginstal versi prarilis paket NuGet Microsoft.UI.Xaml , atau jika Anda menggunakan API Dependensi Dinamis. Dukungan untuk kontrol hosting dari Pustaka WinUI 3.0 akan hadir dalam rilis selanjutnya.

✔️ Untuk mengakses elemen akar pohon konten XAML di Pulau XAML dan mendapatkan informasi terkait tentang konteks dihosting, jangan gunakan kelas CoreWindow, ApplicationView, dan Window . Sebagai gantinya , gunakan kelas XamlRoot . Untuk informasi selengkapnya, lihat bagian ini.

✔️ Untuk mendukung kontrak Berbagi dari aplikasi WPF, Formulir Windows, atau desktop C++ (Win32), aplikasi Anda harus menggunakan antarmuka IDataTransferManagerInterop untuk mendapatkan objek DataTransferManager guna memulai operasi berbagi untuk jendela tertentu. Untuk sampel yang menunjukkan cara menggunakan antarmuka ini di aplikasi WPF, lihat sampel ShareSource.

✔️ Penggunaan x:Bind dengan kontrol yang dihosting di Kepulauan XAML tidak didukung. Anda harus mendeklarasikan model data dalam pustaka Standar .NET.

Tidak didukung

🚫Menggunakan Kepulauan XAML di WPF dan aplikasi Formulir Windows yang menargetkan .NET Framework. Kepulauan XAML hanya didukung dalam aplikasi yang menargetkan .NET Core 3.x.

🚫 Konten UWP XAML di Kepulauan XAML tidak merespons perubahan tema Windows dari gelap ke terang atau sebaliknya pada waktu proses. Konten merespons perubahan kontras tinggi pada waktu proses.

🚫Menambahkan kontrol Windows.UI.Xaml.WebView. Untuk aplikasi WPF dan WinForms, lihat alternatif ini.

🚫Kontrol MediaPlayer dan kontrol host MediaPlayerElement tidak didukung dalam mode layar penuh.

🚫 Input teks dengan tampilan tulisan tangan. Untuk informasi selengkapnya tentang fitur ini, lihat artikel ini.

🚫 Kontrol teks yang menggunakan @Places dan @People tautan konten. Untuk informasi selengkapnya tentang fitur ini, lihat artikel ini.

🚫 Kepulauan XAML tidak mendukung hosting ContentDialog yang berisi kontrol yang menerima input teks, seperti TextBox, RichEditBox, atau AutoSuggestBox. Jika Anda melakukan ini, kontrol input tidak akan merespons penekanan tombol dengan benar. Untuk mencapai fungsionalitas serupa menggunakan Pulau XAML, kami sarankan Anda menghosting Popup yang berisi kontrol input.

🚫Kepulauan XAML saat ini tidak mendukung penayangan file SVG di kontrol Windows.UI.Xaml.Controls.Image yang dihosting atau dengan menggunakan objek Windows.UI.Xaml.Media.Imaging.SvgImageSource. Sebagai solusinya, konversikan file gambar yang ingin Anda tampilkan ke format berbasis raster seperti JPG atau PNG.

Konteks host jendela untuk Kepulauan XAML

Saat Anda menghosting Kepulauan XAML di aplikasi desktop, Anda dapat memiliki beberapa pohon konten XAML yang berjalan pada utas yang sama secara bersamaan. Untuk mengakses elemen akar pohon konten XAML di Pulau XAML dan mendapatkan informasi terkait tentang konteks dihosting, gunakan kelas XamlRoot . Kelas CoreWindow, ApplicationView, dan Window tidak akan memberikan informasi yang benar untuk Kepulauan XAML. Objek CoreWindow dan Window memang ada di utas dan dapat diakses oleh aplikasi Anda, tetapi tidak akan mengembalikan batas atau visibilitas yang bermakna (selalu tidak terlihat dan memiliki ukuran 1x1). Untuk informasi selengkapnya, lihat Host windowing.

Misalnya, untuk mendapatkan persegi panjang pembatas jendela yang berisi kontrol WinRT XAML yang dihosting di Pulau XAML, gunakan properti XamlRoot.Size kontrol. Karena setiap kontrol WinRT XAML yang dapat dihosting di Pulau XAML berasal dari Windows.UI.Xaml.UIElement, Anda dapat menggunakan properti kontrol XamlRoot untuk mengakses objek XamlRoot.

Size windowSize = myUWPControl.XamlRoot.Size;

Jangan gunakan properti CoreWindows.Bounds untuk mendapatkan persegi panjang pembatas .

// This will return incorrect information for a WinRT XAML control that is hosted in a XAML Island.
Rect windowSize = CoreWindow.GetForCurrentThread().Bounds;

Untuk tabel API terkait windowing umum yang harus Anda hindari dalam konteks Kepulauan XAML dan penggantian XamlRoot yang direkomendasikan, lihat tabel di bagian ini.

Untuk sampel yang menunjukkan cara menggunakan antarmuka ini di aplikasi WPF, lihat sampel ShareSource .

Sumber Daya Tambahan:

Untuk informasi latar belakang dan tutorial selengkapnya tentang menggunakan Kepulauan XAML, lihat artikel dan sumber daya berikut ini:

  • Memodernisasi tutorial aplikasi WPF: Tutorial ini menyediakan instruksi langkah demi langkah untuk menggunakan kontrol yang dibungkus dan kontrol host di Windows Community Toolkit untuk menambahkan kontrol WinRT XAML ke aplikasi lini bisnis WPF yang ada. Tutorial ini mencakup kode lengkap untuk aplikasi WPF serta instruksi terperinci untuk setiap langkah dalam proses.
  • Sampel kode Kepulauan XAML: Repositori ini berisi sampel Formulir Windows, WPF, dan desktop C++ (Win32) yang menunjukkan cara menggunakan Kepulauan XAML.
  • Kepulauan XAML v1 - Pembaruan dan Peta Jalan: Posting blog ini membahas banyak pertanyaan umum tentang Kepulauan XAML dan menyediakan peta jalan pengembangan terperinci.