Bagikan melalui


WebView

UI Aplikasi Multi-platform .NET (.NET MAUI) WebView menampilkan halaman web jarak jauh, file HTML lokal, dan string HTML, dalam aplikasi. Konten yang WebView ditampilkan mencakup dukungan untuk Cascading Style Sheets (CSS), dan JavaScript. Secara default, proyek .NET MAUI menyertakan izin platform yang WebView diperlukan untuk menampilkan halaman web jarak jauh.

WebView menentukan properti berikut:

  • Cookies, dari jenis CookieContainer, menyediakan penyimpanan untuk kumpulan cookie.
  • CanGoBack, dari jenis bool, menunjukkan apakah pengguna dapat menavigasi ke halaman sebelumnya. Ini adalah properti baca-saja.
  • CanGoForward, dari jenis bool, menunjukkan apakah pengguna dapat menavigasi ke depan. Ini adalah properti baca-saja.
  • Source, dari jenis WebViewSource, mewakili lokasi yang WebView ditampilkan.
  • UserAgent, dari jenis string, mewakili agen pengguna. Nilai default adalah agen pengguna dari browser platform yang mendasar, atau null jika tidak dapat ditentukan.

Properti ini didukung oleh BindableProperty objek, yang berarti bahwa properti ini dapat menjadi target pengikatan data, dan ditata.

Properti Source dapat diatur ke UrlWebViewSource objek atau HtmlWebViewSource objek, yang keduanya berasal dari WebViewSource. UrlWebViewSource digunakan untuk memuat halaman web yang ditentukan dengan URL, sementara HtmlWebViewSource objek digunakan untuk memuat file HTML lokal, atau HTML lokal.

WebViewNavigating menentukan peristiwa yang dinaikkan saat navigasi halaman dimulai, dan Navigated peristiwa yang dinaikkan saat navigasi halaman selesai. Objek WebNavigatingEventArgs yang menyertai Navigating peristiwa menentukan Cancel properti jenis bool yang dapat digunakan untuk membatalkan navigasi. Objek WebNavigatedEventArgs yang menyertai Navigated peristiwa menentukan Result properti jenis WebNavigationResult yang menunjukkan hasil navigasi.

Penting

WebView harus menentukan properti dan WidthRequest miliknya HeightRequest ketika terkandung dalam HorizontalStackLayout, , StackLayoutatau VerticalStackLayout. Jika Anda gagal menentukan properti ini, WebView properti tidak akan dirender.

Menampilkan halaman web

Untuk menampilkan halaman web jarak jauh, atur Source properti ke string yang menentukan URI:

<WebView Source="https://learn.microsoft.com/dotnet/maui" />

Kode C# yang setara adalah:

WebView webvView = new WebView
{
    Source = "https://learn.microsoft.com/dotnet/maui"
};

URI harus sepenuhnya terbentuk dengan protokol yang ditentukan.

Catatan

Source Meskipun properti berjenis WebViewSource, properti dapat diatur ke URI berbasis string. Ini karena .NET MAUI menyertakan pengonversi jenis, dan operator konversi implisit, yang mengonversi URI berbasis string menjadi UrlWebViewSource objek.

Mengonfigurasi App Transport Security di iOS dan Mac Catalyst

Sejak versi 9, iOS hanya akan memungkinkan aplikasi Anda untuk berkomunikasi dengan server yang aman. Aplikasi harus memilih untuk mengaktifkan komunikasi dengan server yang tidak aman.

Konfigurasi Info.plist berikut menunjukkan cara mengaktifkan domain tertentu untuk melewati persyaratan Apple Transport Security (ATS):

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSExceptionDomains</key>
		<dict>
			<key>mydomain.com</key>
			<dict>
				<key>NSIncludesSubdomains</key>
				<true/>
				<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
				<true/>
				<key>NSTemporaryExceptionMinimumTLSVersion</key>
				<string>TLSv1.1</string>
			</dict>
		</dict>
	</dict>

Praktik terbaik adalah hanya mengaktifkan domain tertentu untuk melewati ATS, memungkinkan Anda menggunakan situs tepercaya sambil mendapat manfaat dari keamanan tambahan pada domain yang tidak tepercaya.

Konfigurasi Info.plist berikut menunjukkan cara menonaktifkan ATS untuk aplikasi:

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSAllowsArbitraryLoads</key>
		<true/>
	</dict>

Penting

Jika aplikasi Anda memerlukan koneksi ke situs web yang tidak aman, Anda harus selalu memasukkan domain sebagai pengecualian menggunakan NSExceptionDomains kunci alih-alih menonaktifkan ATS sepenuhnya menggunakan NSAllowsArbitraryLoads kunci.

Tampilkan HTML lokal

Untuk menampilkan HTML sebaris, atur Source properti ke HtmlWebViewSource objek:

<WebView>
    <WebView.Source>
        <HtmlWebViewSource Html="&lt;HTML&gt;&lt;BODY&gt;&lt;H1&gt;.NET MAUI&lt;/H1&gt;&lt;P&gt;Welcome to WebView.&lt;/P&gt;&lt;/BODY&gt;&lt;HTML&gt;" />
    </WebView.Source>
</WebView>

Di XAML, string HTML dapat menjadi tidak dapat dibaca karena melarikan < diri dari simbol dan > . Oleh karena itu, untuk keterbacaan yang lebih besar, HTML dapat di-inlin di bagian CDATA :

<WebView>
    <WebView.Source>
        <HtmlWebViewSource>
            <HtmlWebViewSource.Html>
                <![CDATA[
                <HTML>
                <BODY>
                <H1>.NET MAUI</H1>
                <P>Welcome to WebView.</P>
                </BODY>
                </HTML>
                ]]>
            </HtmlWebViewSource.Html>
        </HtmlWebViewSource>
    </WebView.Source>
</WebView>

Kode C# yang setara adalah:

WebView webView = new WebView
{
    Source = new HtmlWebViewSource
    {
        Html = @"<HTML><BODY><H1>.NET MAUI</H1><P>Welcome to WebView.</P></BODY></HTML>"
    }
};

Menampilkan file HTML lokal

Untuk menampilkan file HTML lokal, tambahkan file ke folder Resources\Raw proyek aplikasi Anda dan atur tindakan build-nya ke MauiAsset. Kemudian, file dapat dimuat dari HTML sebaris yang didefinisikan dalam HtmlWebViewSource objek yang ditetapkan sebagai nilai Source properti:

<WebView>
    <WebView.Source>
        <HtmlWebViewSource>
            <HtmlWebViewSource.Html>
                <![CDATA[
                <html>
                <head>
                </head>
                <body>
                <h1>.NET MAUI</h1>
                <p>The CSS and image are loaded from local files!</p>
                <p><a href="localfile.html">next page</a></p>
                </body>
                </html>                    
                ]]>
            </HtmlWebViewSource.Html>
        </HtmlWebViewSource>
    </WebView.Source>
</WebView>

File HTML lokal dapat memuat Cascading Style Sheets (CSS), JavaScript, dan gambar, jika juga telah ditambahkan ke proyek aplikasi Anda dengan tindakan build MauiAsset .

Untuk informasi selengkapnya tentang aset mentah, lihat Aset mentah.

Muat ulang konten

WebView memiliki Reload metode yang dapat dipanggil untuk memuat ulang sumbernya:

WebView webView = new WebView();
...
webView.Reload();

Reload Ketika metode dipanggilReloadRequested, peristiwa diaktifkan, menunjukkan bahwa permintaan telah dibuat untuk memuat ulang konten saat ini.

Melakukan navigasi

WebView mendukung navigasi terprogram dengan GoBack metode dan GoForward . Metode ini memungkinkan navigasi melalui WebView tumpukan halaman, dan hanya boleh dipanggil setelah memeriksa nilai CanGoBack properti dan CanGoForward :

WebView webView = new WebView();
...

// Go backwards, if allowed.
if (webView.CanGoBack)
{
    webView.GoBack();
}

// Go forwards, if allowed.
if (webView.CanGoForward)
{
    webView.GoForward();
}

Ketika navigasi halaman terjadi di WebView, baik dimulai secara terprogram atau oleh pengguna, peristiwa berikut terjadi:

  • Navigating, yang dinaikkan saat navigasi halaman dimulai. Objek WebNavigatingEventArgs yang menyertai Navigating peristiwa menentukan Cancel properti jenis bool yang dapat digunakan untuk membatalkan navigasi.
  • Navigated, yang dinaikkan ketika navigasi halaman selesai. Objek WebNavigatedEventArgs yang menyertai Navigated peristiwa menentukan Result properti jenis WebNavigationResult yang menunjukkan hasil navigasi.

Menangani izin di Android

Saat menelusuri ke halaman yang meminta akses ke perangkat keras perekaman perangkat, seperti kamera atau mikrofon, izin harus diberikan oleh WebView kontrol. Kontrol WebView menggunakan jenis di Android.Webkit.WebChromeClient Android untuk bereaksi terhadap permintaan izin. Namun, WebChromeClient implementasi yang disediakan oleh .NET MAUI mengabaikan permintaan izin. Anda harus membuat jenis baru yang mewarisi dan MauiWebChromeClient menyetujui permintaan izin.

Penting

Menyesuaikan WebView untuk menyetujui permintaan izin, menggunakan pendekatan ini, memerlukan Android API 26 atau yang lebih baru.

Permintaan izin dari halaman web ke WebView kontrol berbeda dari permintaan izin dari aplikasi .NET MAUI kepada pengguna. Izin aplikasi .NET MAUI diminta dan disetujui oleh pengguna, untuk seluruh aplikasi. Kontrol WebView tergantung pada kemampuan aplikasi untuk mengakses perangkat keras. Untuk mengilustrasikan konsep ini, pertimbangkan halaman web yang meminta akses ke kamera perangkat. Bahkan jika permintaan tersebut disetujui oleh WebView kontrol, namun aplikasi .NET MAUI tidak memiliki persetujuan oleh pengguna untuk mengakses kamera, halaman web tidak akan dapat mengakses kamera.

Langkah-langkah berikut menunjukkan cara mencegat permintaan izin dari WebView kontrol untuk menggunakan kamera. Jika Anda mencoba menggunakan mikrofon, langkah-langkahnya akan serupa kecuali Anda akan menggunakan izin terkait mikrofon alih-alih izin terkait kamera.

  1. Pertama, tambahkan izin aplikasi yang diperlukan ke manifes Android. Buka file Platforms/Android/AndroidManifest.xml dan tambahkan yang berikut ini di nodemanifest:

    <uses-permission android:name="android.permission.CAMERA" />
    
  2. Pada titik tertentu di aplikasi Anda, seperti saat halaman yang WebView berisi kontrol dimuat, minta izin dari pengguna untuk mengizinkan akses aplikasi ke kamera.

    private async Task RequestCameraPermission()
    {
        PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();
    
        if (status != PermissionStatus.Granted)
            await Permissions.RequestAsync<Permissions.Camera>();
    }
    
  3. Tambahkan kelas berikut ke folder Platforms/Android , mengubah namespace root agar sesuai dengan namespace proyek Anda:

    using Android.Webkit;
    using Microsoft.Maui.Handlers;
    using Microsoft.Maui.Platform;
    
    namespace MauiAppWebViewHandlers.Platforms.Android;
    
    internal class MyWebChromeClient: MauiWebChromeClient
    {
        public MyWebChromeClient(IWebViewHandler handler) : base(handler)
        {
    
        }
    
        public override void OnPermissionRequest(PermissionRequest request)
        {
            // Process each request
            foreach (var resource in request.GetResources())
            {
                // Check if the web page is requesting permission to the camera
                if (resource.Equals(PermissionRequest.ResourceVideoCapture, StringComparison.OrdinalIgnoreCase))
                {
                    // Get the status of the .NET MAUI app's access to the camera
                    PermissionStatus status = Permissions.CheckStatusAsync<Permissions.Camera>().Result;
    
                    // Deny the web page's request if the app's access to the camera is not "Granted"
                    if (status != PermissionStatus.Granted)
                        request.Deny();
                    else
                        request.Grant(request.GetResources());
    
                    return;
                }
            }
    
            base.OnPermissionRequest(request);
        }
    }
    

    Dalam cuplikan sebelumnya, MyWebChromeClient kelas mewarisi dari MauiWebChromeClient, dan mengambil alih OnPermissionRequest metode untuk mencegat permintaan izin halaman web. Setiap item izin dicentang untuk melihat apakah cocok dengan PermissionRequest.ResourceVideoCapture konstanta string, yang mewakili kamera. Jika izin kamera cocok, kode akan memeriksa untuk melihat apakah aplikasi memiliki izin untuk menggunakan kamera. Jika memiliki izin, permintaan halaman web akan diberikan.

  4. SetWebChromeClient Gunakan metode pada kontrol Android WebView untuk mengatur klien chrome ke MyWebChromeClient. Dua item berikut menunjukkan bagaimana Anda dapat mengatur klien chrome:

    • Mengingat kontrol .NET MAUI WebView bernama theWebViewControl, Anda dapat mengatur klien chrome langsung pada tampilan platform, yang merupakan kontrol Android:

      ((IWebViewHandler)theWebViewControl.Handler).PlatformView.SetWebChromeClient(new MyWebChromeClient((IWebViewHandler)theWebViewControl.Handler));
      
    • Anda juga dapat menggunakan pemetaan properti handler untuk memaksa semua WebView kontrol menggunakan klien chrome Anda. Untuk informasi selengkapnya, lihat Handler.

      Metode cuplikan CustomizeWebViewHandler berikut harus dipanggil saat aplikasi dimulai, seperti dalam MauiProgram.CreateMauiApp metode .

      private static void CustomizeWebViewHandler()
      {
      #if ANDROID26_0_OR_GREATER
          Microsoft.Maui.Handlers.WebViewHandler.Mapper.ModifyMapping(
              nameof(Android.Webkit.WebView.WebChromeClient),
              (handler, view, args) => handler.PlatformView.SetWebChromeClient(new MyWebChromeClient(handler)));
      #endif
      }
      

Mengatur cookie

Cookie dapat diatur pada WebView sehingga mereka dikirim dengan permintaan web ke URL yang ditentukan. Atur cookie dengan menambahkan Cookie objek ke CookieContainer, lalu atur kontainer sebagai nilai properti yang WebView.Cookies dapat diikat. Kode berikut menunjukkan contoh:

using System.Net;

CookieContainer cookieContainer = new CookieContainer();
Uri uri = new Uri("https://learn.microsoft.com/dotnet/maui", UriKind.RelativeOrAbsolute);

Cookie cookie = new Cookie
{
    Name = "DotNetMAUICookie",
    Expires = DateTime.Now.AddDays(1),
    Value = "My cookie",
    Domain = uri.Host,
    Path = "/"
};
cookieContainer.Add(uri, cookie);
webView.Cookies = cookieContainer;
webView.Source = new UrlWebViewSource { Url = uri.ToString() };

Dalam contoh ini, satu Cookie ditambahkan ke CookieContainer objek, yang kemudian ditetapkan sebagai nilai WebView.Cookies properti. WebView Ketika mengirim permintaan web ke URL yang ditentukan, cookie dikirim dengan permintaan.

Memanggil JavaScript

WebView termasuk kemampuan untuk memanggil fungsi JavaScript dari C# dan mengembalikan hasil apa pun ke kode C# panggilan. Interop ini dicapai dengan EvaluateJavaScriptAsync metode , yang ditunjukkan dalam contoh berikut:

Entry numberEntry = new Entry { Text = "5" };
Label resultLabel = new Label();
WebView webView = new WebView();
...

int number = int.Parse(numberEntry.Text);
string result = await webView.EvaluateJavaScriptAsync($"factorial({number})");
resultLabel.Text = $"Factorial of {number} is {result}.";

Metode WebView.EvaluateJavaScriptAsync mengevaluasi JavaScript yang ditentukan sebagai argumen, dan mengembalikan hasil apa pun sebagai string. Dalam contoh ini, factorial fungsi JavaScript dipanggil, yang mengembalikan faktorial number sebagai hasilnya. Fungsi JavaScript ini didefinisikan dalam file HTML lokal yang dimuat WebView , dan diperlihatkan dalam contoh berikut:

<html>
<body>
<script type="text/javascript">
function factorial(num) {
        if (num === 0 || num === 1)
            return 1;
        for (var i = num - 1; i >= 1; i--) {
            num *= i;
        }
        return num;
}
</script>
</body>
</html>

Mengonfigurasi WebView asli di iOS dan Mac Catalyst

Kontrol asli WebView adalah MauiWKWebView di iOS dan Mac Catalyst, yang berasal dari WKWebView. Salah MauiWKWebView satu overload konstruktor memungkinkan WKWebViewConfiguration objek ditentukan, yang menyediakan informasi tentang cara mengonfigurasi WKWebView objek. Konfigurasi umum termasuk mengatur agen pengguna, menentukan cookie untuk tersedia untuk konten web Anda, dan menyuntikkan skrip kustom ke dalam konten web Anda.

Anda dapat membuat WKWebViewConfiguration objek di aplikasi, lalu mengonfigurasi propertinya sesuai kebutuhan. Atau, Anda dapat memanggil metode statis MauiWKWebView.CreateConfiguration untuk mengambil objek .NET MAUI WKWebViewConfiguration dan kemudian memodifikasinya. Objek WKWebViewConfiguration kemudian dapat ditentukan sebagai argumen untuk MauiWKWebView konstruktor kelebihan beban.

Karena konfigurasi asli WebView tidak dapat diubah di iOS dan Mac Catalyst setelah tampilan platform handler dibuat, Anda harus membuat delegasi pabrik handler kustom untuk memodifikasinya:

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();
        config.ApplicationNameForUserAgent = "MyProduct/1.0.0";
        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

Catatan

Anda harus mengonfigurasi MauiWKWebView dengan WKWebViewConfiguration objek sebelum WebView ditampilkan di aplikasi Anda. Lokasi yang sesuai untuk melakukan ini ada di jalur startup aplikasi Anda, seperti di MauiProgram.cs atau App.xaml.cs.

Mengatur preferensi pemutaran media di iOS dan Mac Catalyst

Pemutaran media sebaris video HTML5, termasuk pemutaran otomatis dan gambar dalam gambar, diaktifkan secara default untuk WebView di iOS dan Mac Catalyst. Untuk mengubah default ini, atau mengatur preferensi pemutaran media lainnya, Anda harus membuat delegasi pabrik handler kustom karena preferensi pemutaran media tidak dapat diubah setelah tampilan platform handler dibuat. Kode berikut menunjukkan contoh melakukan ini:

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();

        // True to play HTML5 videos inliine, false to use the native full-screen controller.
        config.AllowsInlineMediaPlayback = false;

        // True to play videos over AirPlay, otherwise false.
        config.AllowsAirPlayForMediaPlayback = false;

        // True to let HTML5 videos play Picture in Picture.
        config.AllowsPictureInPictureMediaPlayback = false;

        // Media types that require a user gesture to begin playing.
        config.MediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypes.All;

        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

Untuk informasi selengkapnya tentang mengonfigurasi WebView di iOS, lihat Mengonfigurasi WebView asli di iOS dan Mac Catalyst.

Memeriksa WebView di Mac Catalyst

Untuk menggunakan alat pengembang Safari untuk memeriksa konten WebView di Mac Catalyst, tambahkan kode berikut ke aplikasi Anda:

#if MACCATALYST
        Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("Inspect", (handler, view) =>
        {
            if (OperatingSystem.IsMacCatalystVersionAtLeast(16, 6))
                handler.PlatformView.Inspectable = true;
        });
#endif

Kode ini menyesuaikan pemeta properti untuk WebViewHandler di Mac Catalyst, untuk membuat WebView konten dapat diperiksa oleh alat pengembang Safari. Untuk informasi selengkapnya tentang handler, lihat Handler.

Untuk menggunakan alat pengembang Safari dengan aplikasi Mac Catalyst:

  1. Buka Safari di Mac Anda.
  2. Di Safari, pilih kotak centang Safari > Pengaturan > Menu Kembangkan Peragaan Tingkat Lanjut > di bilah menu.
  3. Jalankan aplikasi .NET MAUI Mac Catalyst Anda.
  4. Di Safari, pilih menu Kembangkan > {Nama perangkat} , di mana {Device name} tempat penampung adalah nama perangkat Anda seperti Macbook Pro. Kemudian pilih entri di bawah nama aplikasi Anda, yang juga akan menyoroti aplikasi yang sedang berjalan. Ini akan menyebabkan jendela Pemeriksa Web muncul.

Luncurkan browser sistem

Dimungkinkan untuk membuka URI di browser web sistem dengan Launcher kelas , yang disediakan oleh Microsoft.Maui.Essentials. Panggil metode peluncur OpenAsync dan berikan string argumen atau Uri yang mewakili URI untuk membuka:

await Launcher.OpenAsync("https://learn.microsoft.com/dotnet/maui");

Untuk informasi selengkapnya, lihat Peluncur.