Bagikan melalui

Tampilan web

  • Artikel

Kontrol tampilan web menyematkan tampilan ke dalam aplikasi Anda yang merender konten web menggunakan mesin penyajian Lama Microsoft Edge. Hyperlink juga dapat muncul dan berfungsi dalam kontrol tampilan web.

Penting

Kontrol WebView2 tersedia sebagai bagian dari WinUI3. WebView2 menggunakan Microsoft Edge (Chromium) sebagai mesin penyajian untuk menampilkan konten web di aplikasi. Untuk informasi selengkapnya, lihat Pengenalan Microsoft Edge WebView2, Mulai menggunakan WebView2 di WinUI 3 (Pratinjau), dan WebView2 dalam referensi API WinUI.

Apakah ini kontrol yang tepat?

Gunakan kontrol tampilan web untuk menampilkan konten HTML yang diformat dengan kaya dari server web jarak jauh, kode yang dihasilkan secara dinamis, atau file konten dalam paket aplikasi Anda. Konten kaya juga dapat berisi kode skrip dan berkomunikasi antara skrip dan kode aplikasi Anda.

Rekomendasi

  • Pastikan bahwa situs web yang dimuat diformat dengan benar untuk perangkat dan menggunakan warna, tipografi, dan navigasi yang konsisten dengan aplikasi Anda lainnya.
  • Bidang input harus berukuran tepat. Pengguna mungkin tidak menyadari bahwa mereka dapat memperbesar untuk memasukkan teks.
  • Jika tampilan web tidak terlihat seperti aplikasi Lainnya, pertimbangkan kontrol atau cara alternatif untuk menyelesaikan tugas yang relevan. Jika tampilan web Anda cocok dengan aplikasi Anda lainnya, pengguna akan melihat semuanya sebagai satu pengalaman yang mulus.

Membuat tampilan web

Mengubah tampilan tampilan web

WebView bukan subkelas Kontrol , sehingga tidak memiliki templat kontrol. Namun, Anda dapat mengatur berbagai properti untuk mengontrol beberapa aspek visual tampilan web.

Mendapatkan judul halaman web

Anda bisa mendapatkan judul dokumen HTML yang saat ini ditampilkan dalam tampilan web dengan menggunakan properti DocumentTitle .

Peristiwa input dan urutan tab

Meskipun WebView bukan subkelas Kontrol, WebView akan menerima fokus input keyboard dan berpartisipasi dalam urutan tab. Ini menyediakan metode Fokus , dan peristiwa GotFocus dan LostFocus , tetapi tidak memiliki properti terkait tab. Posisinya dalam urutan tab sama dengan posisinya dalam urutan dokumen XAML. Urutan tab menyertakan semua elemen dalam konten tampilan web yang dapat menerima fokus input.

Seperti yang ditunjukkan dalam tabel Peristiwa di halaman kelas WebView , tampilan web tidak mendukung sebagian besar peristiwa input pengguna yang diwariskan dari UIElement, seperti KeyDown, KeyUp, dan PointerPressed. Sebagai gantinya, Anda dapat menggunakan InvokeScriptAsync dengan fungsi evaluasi JavaScript untuk menggunakan penanganan aktivitas HTML, dan untuk menggunakan window.external.notify dari penanganan aktivitas HTML untuk memberi tahu aplikasi menggunakan WebView.ScriptNotify.

Menavigasi ke konten

Tampilan web menyediakan beberapa API untuk navigasi dasar: GoBack, GoForward, Stop, Refresh, CanGoBack, dan CanGoForward. Anda dapat menggunakannya untuk menambahkan kemampuan penjelajahan web biasa ke aplikasi Anda.

Untuk mengatur konten awal tampilan web, atur properti Sumber di XAML. Pengurai XAML secara otomatis mengonversi string menjadi Uri.

<!-- Source file is on the web. -->
<WebView x:Name="webView1" Source="http://www.contoso.com"/>

<!-- Source file is in local storage. -->
<WebView x:Name="webView2" Source="ms-appdata:///local/intro/welcome.html"/>

<!-- Source file is in the app package. -->
<WebView x:Name="webView3" Source="ms-appx-web:///help/about.html"/>

Properti Sumber dapat diatur dalam kode, tetapi daripada melakukannya, Anda biasanya menggunakan salah satu metode Navigasi untuk memuat konten dalam kode.

Untuk memuat konten web, gunakan metode Navigasi dengan Uri yang menggunakan skema http atau https.

webView1.Navigate(new Uri("http://www.contoso.com"));

Untuk menavigasi ke URI dengan permintaan POST dan header HTTP, gunakan metode NavigateWithHttpRequestMessage . Metode ini hanya mendukung HttpMethod.Post dan HttpMethod.Get untuk nilai properti HttpRequestMessage.Method .

Untuk memuat konten yang tidak dikompresi dan tidak terenkripsi dari penyimpanan data LocalFolder atau TemporaryFolder aplikasi Anda, gunakan metode Navigasi dengan Uri yang menggunakan skema ms-appdata. Dukungan tampilan web untuk skema ini mengharuskan Anda menempatkan konten Anda dalam subfolder di bawah folder lokal atau sementara. Ini memungkinkan navigasi ke URI seperti file ms-appdata:///local/folder/.html dan ms-appdata:///temp/folder/.html . (Untuk memuat file terkompresi atau terenkripsi, lihat NavigateToLocalStreamUri.)

Masing-masing subfolder tingkat pertama ini diisolasi dari konten di subfolder tingkat pertama lainnya. Misalnya, Anda dapat menavigasi ke ms-appdata:///temp/folder1/file.html, tetapi Anda tidak dapat memiliki tautan dalam file ini ke ms-appdata:///temp/folder2/file.html. Namun, Anda masih dapat menautkan ke konten HTML dalam paket aplikasi menggunakan skema ms-appx-web, dan ke konten web menggunakan skema URI http dan https .

webView1.Navigate(new Uri("ms-appdata:///local/intro/welcome.html"));

Untuk memuat konten dari paket aplikasi Anda, gunakan metode Navigasi dengan Uri yang menggunakan skema ms-appx-web.

webView1.Navigate(new Uri("ms-appx-web:///help/about.html"));

Anda dapat memuat konten lokal melalui pemecah masalah kustom menggunakan metode NavigateToLocalStreamUri . Ini memungkinkan skenario tingkat lanjut seperti mengunduh dan men-cache konten berbasis web untuk penggunaan offline, atau mengekstrak konten dari file terkompresi.

Merespons peristiwa navigasi

Kontrol tampilan web menyediakan beberapa peristiwa yang dapat Anda gunakan untuk merespons navigasi dan status pemuatan konten. Peristiwa terjadi dalam urutan berikut untuk konten tampilan web akar: NavigationStarting, ContentLoading, DOMContentLoaded, NavigationCompleted

NavigationStarting - Terjadi sebelum tampilan web menavigasi ke konten baru. Anda dapat membatalkan navigasi di handler untuk kejadian ini dengan mengatur properti WebViewNavigationStartingEventArgs.Cancel ke true.

webView1.NavigationStarting += webView1_NavigationStarting;

private void webView1_NavigationStarting(object sender, WebViewNavigationStartingEventArgs args)
{
    // Cancel navigation if URL is not allowed. (Implementation of IsAllowedUri not shown.)
    if (!IsAllowedUri(args.Uri))
        args.Cancel = true;
}

ContentLoading - Terjadi ketika tampilan web telah mulai memuat konten baru.

webView1.ContentLoading += webView1_ContentLoading;

private void webView1_ContentLoading(WebView sender, WebViewContentLoadingEventArgs args)
{
    // Show status.
    if (args.Uri != null)
    {
        statusTextBlock.Text = "Loading content for " + args.Uri.ToString();
    }
}

DOMContentLoaded - Terjadi ketika tampilan web telah selesai mengurai konten HTML saat ini.

webView1.DOMContentLoaded += webView1_DOMContentLoaded;

private void webView1_DOMContentLoaded(WebView sender, WebViewDOMContentLoadedEventArgs args)
{
    // Show status.
    if (args.Uri != null)
    {
        statusTextBlock.Text = "Content for " + args.Uri.ToString() + " has finished loading";
    }
}

NavigationCompleted - Terjadi ketika tampilan web telah selesai memuat konten saat ini atau jika navigasi gagal. Untuk menentukan apakah navigasi telah gagal, periksa properti IsSuccess dan WebErrorStatus dari kelas WebViewNavigationCompletedEventArgs .

webView1.NavigationCompleted += webView1_NavigationCompleted;

private void webView1_NavigationCompleted(WebView sender, WebViewNavigationCompletedEventArgs args)
{
    if (args.IsSuccess == true)
    {
        statusTextBlock.Text = "Navigation to " + args.Uri.ToString() + " completed successfully.";
    }
    else
    {
        statusTextBlock.Text = "Navigation to: " + args.Uri.ToString() +
                               " failed with error " + args.WebErrorStatus.ToString();
    }
}

Peristiwa serupa terjadi dalam urutan yang sama untuk setiap iframe dalam konten tampilan web:

Menanggapi potensi masalah

Anda dapat menanggapi potensi masalah dengan konten seperti skrip yang berjalan lama, konten yang tidak dapat dimuat tampilan web, dan peringatan konten yang tidak aman.

Aplikasi Anda mungkin tampak tidak responsif saat skrip berjalan. Peristiwa LongRunningScriptDetected terjadi secara berkala saat tampilan web menjalankan JavaScript dan memberikan kesempatan untuk mengganggu skrip. Untuk menentukan berapa lama skrip telah berjalan, periksa properti ExecutionTime dari WebViewLongRunningScriptDetectedEventArgs. Untuk menghentikan skrip, atur properti Event Args StopPageScriptExecution ke true. Skrip yang dihentikan tidak akan dijalankan lagi kecuali dimuat ulang selama navigasi tampilan web berikutnya.

Kontrol tampilan web tidak dapat menghosting tipe file sewenang-wenang. Ketika upaya dilakukan untuk memuat konten yang tidak dapat dihosting oleh tampilan web, peristiwa UnviewableContentIdentified terjadi. Anda dapat menangani peristiwa ini dan memberi tahu pengguna, atau menggunakan kelas Peluncur untuk mengalihkan file ke browser eksternal atau aplikasi lain.

Demikian pula, peristiwa UnsupportedUriSchemeIdentified terjadi ketika skema URI yang tidak didukung dipanggil dalam konten web, seperti fbconnect:// atau mailto://. Anda dapat menangani kejadian ini untuk memberikan perilaku kustom alih-alih mengizinkan peluncur sistem default meluncurkan URI.

UnsafeContentWarningDisplayingevent terjadi ketika tampilan web memperlihatkan halaman peringatan untuk konten yang dilaporkan tidak aman oleh Filter LayarPintar. Jika pengguna memilih untuk melanjutkan navigasi, navigasi berikutnya ke halaman tidak akan menampilkan peringatan atau mengaktifkan peristiwa.

Menangani kasus khusus untuk konten tampilan web

Anda dapat menggunakan properti ContainsFullScreenElement dan peristiwa ContainsFullScreenElementChanged untuk mendeteksi, merespons, dan mengaktifkan pengalaman layar penuh dalam konten web, seperti pemutaran video layar penuh. Misalnya, Anda dapat menggunakan peristiwa ContainsFullScreenElementChanged untuk mengubah ukuran tampilan web untuk menempati keseluruhan tampilan aplikasi Anda, atau, seperti yang diilustrasikan contoh berikut, menempatkan aplikasi berjendela dalam mode layar penuh saat pengalaman web layar penuh diinginkan.

// Assume webView is defined in XAML
webView.ContainsFullScreenElementChanged += webView_ContainsFullScreenElementChanged;

private void webView_ContainsFullScreenElementChanged(WebView sender, object args)
{
    var applicationView = ApplicationView.GetForCurrentView();

    if (sender.ContainsFullScreenElement)
    {
        applicationView.TryEnterFullScreenMode();
    }
    else if (applicationView.IsFullScreenMode)
    {
        applicationView.ExitFullScreenMode();
    }
}

Anda dapat menggunakan peristiwa NewWindowRequested untuk menangani kasus di mana konten web yang dihosting meminta jendela baru untuk ditampilkan, seperti jendela popup. Anda dapat menggunakan kontrol WebView lain untuk menampilkan konten jendela yang diminta.

Gunakan peristiwa PermissionRequested untuk mengaktifkan fitur web yang memerlukan kemampuan khusus. Saat ini termasuk geolokasi, penyimpanan IndexedDB, dan audio dan video pengguna (misalnya, dari mikrofon atau webcam). Jika aplikasi Anda mengakses lokasi pengguna atau media pengguna, Anda masih diharuskan untuk mendeklarasikan kemampuan ini dalam manifes aplikasi. Misalnya, aplikasi yang menggunakan geolokasi memerlukan deklarasi kemampuan berikut minimal di Package.appxmanifest:

  <Capabilities>
    <Capability Name="internetClient" />
    <DeviceCapability Name="location" />
  </Capabilities>

Selain aplikasi yang menangani peristiwa PermissionRequested , pengguna harus menyetujui dialog sistem standar untuk aplikasi yang meminta lokasi atau kemampuan media agar fitur ini diaktifkan.

Berikut adalah contoh bagaimana aplikasi akan mengaktifkan geolokasi dalam peta dari Bing:

// Assume webView is defined in XAML
webView.PermissionRequested += webView_PermissionRequested;

private void webView_PermissionRequested(WebView sender, WebViewPermissionRequestedEventArgs args)
{
    if (args.PermissionRequest.PermissionType == WebViewPermissionType.Geolocation &&
        args.PermissionRequest.Uri.Host == "www.bing.com")
    {
        args.PermissionRequest.Allow();
    }
}

Jika aplikasi Anda memerlukan input pengguna atau operasi asinkron lainnya untuk merespons permintaan izin, gunakan metode Defer WebViewPermissionRequest untuk membuat WebViewDeferredPermissionRequest yang dapat ditindaklanjuti di lain waktu. Lihat WebViewPermissionRequest.Defer.

Jika pengguna harus keluar dari situs web yang dihosting dengan aman dalam tampilan web, atau dalam kasus lain ketika keamanan penting, panggil metode statis ClearTemporaryWebDataAsync untuk menghapus semua konten yang di-cache secara lokal dari sesi tampilan web. Ini mencegah pengguna berbahaya mengakses data sensitif.

Berinteraksi dengan konten tampilan web

Anda dapat berinteraksi dengan konten tampilan web dengan menggunakan metode InvokeScriptAsync untuk memanggil atau menyuntikkan skrip ke dalam konten tampilan web, dan peristiwa ScriptNotify untuk mendapatkan informasi kembali dari konten tampilan web.

Untuk memanggil JavaScript di dalam konten tampilan web, gunakan metode InvokeScriptAsync . Skrip yang dipanggil hanya dapat mengembalikan nilai string.

Misalnya, jika konten tampilan web bernama webView1 berisi fungsi bernama setDate yang mengambil 3 parameter, Anda dapat memanggilnya seperti ini.

string[] args = {"January", "1", "2000"};
string returnValue = await webView1.InvokeScriptAsync("setDate", args);

Anda dapat menggunakan InvokeScriptAsync dengan fungsi eval JavaScript untuk menyuntikkan konten ke halaman web.

Di sini, teks kotak teks XAML (nameTextBox.Text) ditulis ke div di halaman HTML yang dihosting di webView1.

private async void Button_Click(object sender, RoutedEventArgs e)
{
    string functionString = String.Format("document.getElementById('nameDiv').innerText = 'Hello, {0}';", nameTextBox.Text);
    await webView1.InvokeScriptAsync("eval", new string[] { functionString });
}

Skrip dalam konten tampilan web dapat menggunakan window.external.notify dengan parameter string untuk mengirim informasi kembali ke aplikasi Anda. Untuk menerima pesan ini, tangani peristiwa ScriptNotify .

Untuk mengaktifkan halaman web eksternal untuk mengaktifkan peristiwa ScriptNotify saat memanggil window.external.notify, Anda harus menyertakan URI halaman di bagian ApplicationContentUriRules dari manifes aplikasi. (Anda dapat melakukan ini di Microsoft Visual Studio pada tab URI Konten dari perancang Package.appxmanifest.) URI dalam daftar ini harus menggunakan HTTPS, dan mungkin berisi kartubebas subdomain (misalnya, https://*.microsoft.com) tetapi tidak dapat berisi kartubebas domain (misalnya, https://*.com dan https://*.*). Persyaratan manifes tidak berlaku untuk konten yang berasal dari paket aplikasi, menggunakan ms-local-stream:// URI, atau dimuat menggunakan NavigateToString.

Mengakses Windows Runtime dalam tampilan web

Anda dapat menggunakan metode AddWebAllowedObject untuk menyuntikkan instans kelas asli dari komponen Windows Runtime ke dalam konteks JavaScript tampilan web. Ini memungkinkan akses penuh ke metode asli, properti, dan peristiwa objek tersebut dalam konten JavaScript dari tampilan web tersebut. Kelas harus dihiasi dengan atribut AllowForWeb .

Misalnya, kode ini menyuntikkan instans MyClass yang diimpor dari komponen Windows Runtime ke dalam tampilan web.

private void webView_NavigationStarting(WebView sender, WebViewNavigationStartingEventArgs args)
{
    if (args.Uri.Host == "www.contoso.com")
    {
        webView.AddWebAllowedObject("nativeObject", new MyClass());
    }
}

Untuk informasi selengkapnya, lihat WebView.AddWebAllowedObject.

Selain itu, konten JavaScript tepercaya dalam tampilan web dapat diizinkan untuk langsung mengakses WINDOWS Runtime API. Ini menyediakan kemampuan asli yang kuat untuk aplikasi web yang dihosting dalam tampilan web. Untuk mengaktifkan fitur ini, URI untuk konten tepercaya harus diizinkan dalam ApplicationContentUriRules aplikasi di Package.appxmanifest, dengan WindowsRuntimeAccess secara khusus diatur ke "semua".

Contoh ini memperlihatkan bagian manifes aplikasi. Di sini, URI lokal diberikan akses ke Windows Runtime.

  <Applications>
    <Application Id="App"
      ...

      <uap:ApplicationContentUriRules>
        <uap:Rule Match="ms-appx-web:///Web/App.html" WindowsRuntimeAccess="all" Type="include"/>
      </uap:ApplicationContentUriRules>
    </Application>
  </Applications>

Opsi untuk hosting konten web

Anda dapat menggunakan properti WebView.Settings (jenis WebViewSettings) untuk mengontrol apakah JavaScript dan IndexedDB diaktifkan. Misalnya, jika Anda menggunakan tampilan web untuk menampilkan konten statis yang ketat, Anda mungkin ingin menonaktifkan JavaScript untuk performa terbaik.

Menangkap konten tampilan web

Untuk mengaktifkan berbagi konten tampilan web dengan aplikasi lain, gunakan metode CaptureSelectedContentToDataPackageAsync , yang mengembalikan konten yang dipilih sebagai DataPackage. Metode ini asinkron, jadi Anda harus menggunakan penundaan untuk mencegah penanganan aktivitas DataRequested Anda kembali sebelum panggilan asinkron selesai.

Untuk mendapatkan gambar pratinjau konten tampilan web saat ini, gunakan metode CapturePreviewToStreamAsync . Metode ini membuat gambar konten saat ini dan menulisnya ke aliran yang ditentukan.

Perilaku threading

Secara default, konten tampilan web dihosting di utas UI pada perangkat di keluarga perangkat desktop, dan di luar utas UI di semua perangkat lain. Anda dapat menggunakan properti statis WebView.DefaultExecutionMode untuk mengkueri perilaku utas default untuk klien saat ini. Jika perlu, Anda dapat menggunakan konstruktor WebView(WebViewExecutionMode) untuk mengambil alih perilaku ini.

Catatan Mungkin ada masalah performa saat menghosting konten di utas UI pada perangkat seluler, jadi pastikan untuk menguji pada semua perangkat target saat Anda mengubah DefaultExecutionMode.

Tampilan web yang menghosting konten dari utas UI tidak kompatibel dengan kontrol induk yang memerlukan gerakan untuk menyebarkan dari kontrol tampilan web ke induk, seperti FlipView, ScrollViewer, dan kontrol terkait lainnya. Kontrol ini tidak akan dapat menerima gerakan yang dimulai dalam tampilan web off-thread. Selain itu, mencetak konten web off-thread tidak didukung secara langsung - Anda harus mencetak elemen dengan isi WebViewBrush sebagai gantinya.

Mendapatkan kode sampel

  • Sampel Galeri WinUI 2 - Lihat semua kontrol XAML dalam format interaktif.