Visualizador da Web

A interface do usuário do aplicativo .NET multiplataforma (.NET MAUI) WebView exibe páginas da Web remotas, arquivos HTML locais e cadeias de caracteres HTML, em um aplicativo. O conteúdo exibido em WebView inclui suporte para CSS (Folhas de Estilo em Cascata) e JavaScript. Por padrão, os projetos MAUI do .NET incluem as permissões de plataforma necessárias para um WebView exibir uma página da Web remota.

WebView define as seguintes propriedades:

• Cookies, do tipo CookieContainer, fornece armazenamento para uma coleção de cookies.
• CanGoBack, do tipo bool, indica se o usuário pode navegar até páginas anteriores. Esta é uma propriedade somente leitura.
• CanGoForward, do tipo bool, indica se o usuário pode navegar para frente. Esta é uma propriedade somente leitura.
• Source, do tipo WebViewSource, representa o local exibido pelo WebView.
• UserAgent, do tipo string, representa o agente de usuário. O valor padrão é o agente do usuário do navegador da plataforma subjacente ou null se ele não puder ser determinado.

Essas propriedades são apoiadas por objetos BindableProperty, o que significa que eles podem ser alvos de associações de dados e estilizados.

A propriedade Source pode ser definida como um objeto UrlWebViewSource ou um objeto HtmlWebViewSource, que derivam de WebViewSource. Um UrlWebViewSource é usado para carregar uma página da Web especificada com uma URL, enquanto um objeto HtmlWebViewSource é usado para carregar um arquivo HTML local ou HTML local.

WebView define os seguintes eventos:

• Navigating, que é acionado quando a navegação da página é iniciada. O objeto WebNavigatingEventArgs que acompanha esse evento define uma propriedade Cancel do tipo bool que pode ser usada para cancelar a navegação.
• Navigated, isso é acionado quando a navegação de página é concluída. O objeto WebNavigatedEventArgs que acompanha esse evento define uma propriedade Result do tipo WebNavigationResult que indica o resultado da navegação.
• ProcessTerminated, isso é gerado quando um processo de WebView termina inesperadamente. O objeto WebViewProcessTerminatedEventArgs que acompanha esse evento define propriedades específicas da plataforma que indicam por que o processo falhou.

Importante

Um WebView deve especificar suas propriedades HeightRequest e WidthRequest quando contido em um HorizontalStackLayout, StackLayoutou VerticalStackLayout. Se você não especificar essas propriedades, o WebView não será renderizado.

Exibir uma página da Web

Para exibir uma página da Web remota, defina a propriedade Source como uma string que especifica o URI:

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

O código C# equivalente é:

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

As URIs devem ser totalmente formadas com o protocolo especificado.

Nota

Apesar da propriedade Source ser do tipo WebViewSource, a propriedade pode ser definida como um URI baseado em cadeia de caracteres. Isso ocorre porque o .NET MAUI inclui um conversor de tipo e um operador de conversão implícita, que converte o URI baseado em cadeia de caracteres em um objeto UrlWebViewSource.

Configurar a Segurança de Transporte de Aplicativo no iOS e no Mac Catalyst

Desde a versão 9, o iOS só permitirá que seu aplicativo se comunique com servidores seguros. Um aplicativo precisa optar por habilitar a comunicação com servidores inseguros.

A seguinte configuração Info.plist mostra como habilitar um domínio específico para ignorar os requisitos de ATS (Segurança de Transporte da Apple):

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

É uma prática recomendada habilitar apenas domínios específicos para ignorar o ATS, permitindo que você use sites confiáveis enquanto se beneficia de segurança adicional em domínios não confiáveis.

A seguinte configuração do Info.plist mostra como desabilitar o ATS para um aplicativo:

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

Importante

Se seu aplicativo exigir uma conexão com um site inseguro, você sempre deverá inserir o domínio como uma exceção usando a chave NSExceptionDomains em vez de desativar o ATS completamente usando a chave NSAllowsArbitraryLoads.

Exibir HTML local

Para exibir HTML inline, defina a propriedade Source como um objeto HtmlWebViewSource:

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

No XAML, as cadeias de caracteres HTML podem se tornar ilegível devido ao escape dos símbolos < e >. Portanto, para maior legibilidade, o HTML pode ser embutido em uma seção 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>

O código C# equivalente é:

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

Exibir um arquivo HTML local

Para exibir um arquivo HTML local, adicione o arquivo à pasta Resources\Raw do seu projeto de aplicativo e defina sua ação de build para mauiAsset. Em seguida, o arquivo pode ser carregado a partir de HTML em linha definido em um objeto HtmlWebViewSource configurado como o valor da propriedade Source.

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

O arquivo HTML local pode carregar Cascading Style Sheets (Folhas de Estilo em Cascata - CSS), JavaScript e imagens, se eles também tiverem sido adicionados ao seu projeto de aplicativo com a ação de compilação MauiAsset.

Para obter mais informações sobre ativos brutos, consulte ativos brutos.

Recarregar conteúdo

WebView tem um método Reload que pode ser chamado para recarregar sua fonte.

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

Quando o método Reload é invocado, o evento ReloadRequested é acionado, indicando que uma solicitação foi feita para recarregar o conteúdo atual.

Executar navegação

WebView dá suporte à navegação programática com os métodos GoBack e GoForward. Esses métodos habilitam a navegação por meio da pilha de páginas WebView e só devem ser chamados depois de inspecionar os valores das propriedades CanGoBack e CanGoForward:

WebView webView = new WebView();
...

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

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

Quando a navegação de página ocorre em uma WebView, iniciada programaticamente ou pelo usuário, ocorrem os seguintes eventos:

• Navigating, que é gerado quando a navegação da página é iniciada. O objeto WebNavigatingEventArgs que acompanha o evento Navigating define uma propriedade Cancel do tipo bool que pode ser usada para cancelar a navegação.
• Navigated, que é gerado quando a navegação de página é concluída. O objeto WebNavigatedEventArgs que acompanha o evento Navigated define uma propriedade Result do tipo WebNavigationResult que indica o resultado da navegação.

Navegue até o conteúdo que abre uma nova janela no Android

No Android, a navegação não ocorrerá em um WebView quando um hiperlink que especifica target="_blank" (para abrir o conteúdo em uma nova janela) for pressionado. Isso ocorre porque abrir um hiperlink em uma nova janela requer que OnCreateWindow seja implementado, o que o .NET MAUI não faz. Portanto, para esse cenário, você deve decidir se deseja implementar OnCreateWindow por conta própria, abrir a URL no navegador do sistema ou fazer outra coisa.

Como alternativa, para forçar que todos os hiperlinks abram no mesmo WebView, modifique o WebViewHandler em seu aplicativo para que o WebView nativo desabilite o suporte para várias janelas:

#if ANDROID
    Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("SupportMultipleWindows", (handler, view) =>
    {
        handler.PlatformView.Settings.SetSupportMultipleWindows(false);
    });
#endif

Esse código personaliza o mapeador de propriedades para o WebViewHandler no Android chamando o método SetSupportMultipleWindows com um argumento false e deve ser executado antes que um usuário possa navegar até um hiperlink que especifica target="_blank". Para obter mais informações sobre manipuladores, consulte manipuladores.

Manipular permissões no Android

Ao navegar até uma página que solicita acesso ao hardware de gravação do dispositivo, como a câmera ou o microfone, a permissão deve ser concedida pelo controle WebView. O controle WebView usa o tipo Android.Webkit.WebChromeClient no Android para reagir às solicitações de permissão. No entanto, a implementação de WebChromeClient fornecida pelo .NET MAUI ignora solicitações de permissão. Você deve criar um novo tipo que herda de MauiWebChromeClient e aprova as solicitações de permissão.

Importante

Personalizar o WebView para aprovar solicitações de permissão, usando essa abordagem, requer a API do Android 26 ou posterior.

As solicitações de permissão de uma página da Web para o controle WebView são diferentes das solicitações de permissão do aplicativo .NET MAUI para o usuário. As permissões de aplicativo .NET MAUI são solicitadas e aprovadas pelo usuário para todo o aplicativo. O controle WebView depende da capacidade dos aplicativos de acessar o hardware. Para ilustrar esse conceito, considere uma página da Web que solicita acesso à câmera do dispositivo. Mesmo que essa solicitação seja aprovada pelo controle WebView, mas o aplicativo MAUI do .NET não tenha aprovação do usuário para acessar a câmera, a página da Web não seria capaz de acessar a câmera.

As etapas a seguir demonstram como interceptar solicitações de permissão do controle WebView para usar a câmera. Se você estiver tentando usar o microfone, as etapas serão semelhantes, exceto que você usaria permissões relacionadas ao microfone em vez de permissões relacionadas à câmera.

1. Primeiro, adicione as permissões de aplicativo necessárias ao manifesto do Android. Abra o arquivo Platforms/Android/AndroidManifest.xml e adicione o seguinte no nó manifest:

   <uses-permission android:name="android.permission.CAMERA" />
   

2. Em algum momento do aplicativo, como quando a página que contém um controle WebView é carregada, solicite permissão do usuário para permitir que o aplicativo acesse a câmera.

   private async Task RequestCameraPermission()
   {
       PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();
   
       if (status != PermissionStatus.Granted)
           await Permissions.RequestAsync<Permissions.Camera>();
   }
   

3. Adicione a seguinte classe à pasta Platforms/Android, alterando o namespace raiz para corresponder ao namespace do projeto (não acrescente .Platforms.Android ao namespace):

   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);
       }
   }
   

   No snippet anterior, a classe MyWebChromeClient herda de MauiWebChromeCliente substitui o método OnPermissionRequest para interceptar solicitações de permissão de página da Web. Cada item de permissão é verificado para ver se ele corresponde à constante de cadeia de caracteres PermissionRequest.ResourceVideoCapture, que representa a câmera. Se uma permissão de câmera for correspondida, o código verificará se o aplicativo tem permissão para usar a câmera. Se ele tiver permissão, a solicitação da página da Web será concedida.

4. Use o método SetWebChromeClient no controle WebView do Android para definir o cliente chrome como MyWebChromeClient. Os dois itens a seguir demonstram como você pode definir o cliente chrome:

   • Considerando um controle .NET MAUI WebView chamado theWebViewControl, você pode definir o cliente do Chrome diretamente na visualização da plataforma, que é o controle Android.

     ((IWebViewHandler)theWebViewControl.Handler).PlatformView.SetWebChromeClient(new MyWebChromeClient((IWebViewHandler)theWebViewControl.Handler));
     

   • Você também pode usar o mapeamento de propriedades do manipulador para forçar todos os controles WebView a usar o cliente chrome. Para mais informações, consulte manipuladores.

     O método CustomizeWebViewHandler do snippet a seguir deve ser chamado quando o aplicativo é iniciado, como no método MauiProgram.CreateMauiApp.

     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
     }
     

Definir cookies

Os cookies podem ser definidos em um WebView para que sejam enviados com a solicitação web para a URL especificada. Configure os cookies adicionando objetos Cookie a um CookieContainere defina o contêiner como o valor da propriedade vinculável WebView.Cookies. O código a seguir mostra um exemplo:

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() };

Neste exemplo, um único Cookie é adicionado ao objeto CookieContainer, que é definido como o valor da propriedade WebView.Cookies. Quando o WebView envia uma solicitação da Web para a URL especificada, o cookie é enviado com a solicitação.

Invocar JavaScript

WebView inclui a capacidade de invocar uma função JavaScript de C# e retornar qualquer resultado para o código chamador C#. Essa interoperabilidade é realizada com o método EvaluateJavaScriptAsync, que é mostrado no exemplo a seguir:

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}.";

O método WebView.EvaluateJavaScriptAsync avalia o JavaScript especificado como o argumento e retorna qualquer resultado como um string. Neste exemplo, a função JavaScript factorial é invocada, o que retorna o fatorial de number como resultado. Essa função JavaScript é definida no arquivo HTML local que o WebView carrega e é mostrada no exemplo a seguir:

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

Configurar o WebView nativo no iOS e no Mac Catalyst

O controle de WebView nativo é um MauiWKWebView no iOS e no Mac Catalyst, que deriva de WKWebView. Uma das sobrecargas do construtor MauiWKWebView permite especificar um objeto WKWebViewConfiguration, que fornece informações sobre como configurar o objeto WKWebView. As configurações típicas incluem a configuração do agente do usuário, a especificação de cookies a serem disponibilizados para o conteúdo da Web e a injeção de scripts personalizados no conteúdo da Web.

Você pode criar um objeto WKWebViewConfiguration em seu aplicativo e, em seguida, configurar suas propriedades conforme necessário. Como alternativa, você pode chamar o método de MauiWKWebView.CreateConfiguration estático para recuperar o objeto WKWebViewConfiguration do .NET MAUI e modificá-lo. O objeto WKWebViewConfiguration pode ser especificado como um argumento para a sobrecarga do construtor MauiWKWebView.

Como a configuração do WebView nativo não pode ser alterada no iOS e no Mac Catalyst depois que a exibição da plataforma do manipulador é criada, você deve criar um representante de fábrica de manipulador personalizado para modificá-lo:

#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

Nota

Você deve configurar MauiWKWebView com um objeto WKWebViewConfiguration antes que um WebView seja exibido em seu aplicativo. Locais adequados para fazer isso estão no caminho de inicialização do aplicativo, como em MauiProgram.cs ou App.xaml.cs.

Definir preferências de reprodução de mídia no iOS e no Mac Catalyst

A reprodução de mídia embutida do vídeo HTML5, incluindo a reprodução automática e a imagem na imagem, é habilitada por padrão para o WebView no iOS e no Mac Catalyst. Para alterar esse padrão ou definir outras preferências de reprodução de mídia, você deve criar um delegado de fábrica de manipulador personalizado, pois as preferências de reprodução de mídia não podem ser alteradas depois que a exibição da plataforma do manipulador é criada. O código a seguir mostra um exemplo de como fazer isso:

#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

Para obter mais informações sobre como configurar um WebView no iOS, consulte Configurar o WebView nativo no iOS e no Mac Catalyst.

Inspecionar um WebView no Mac Catalyst

Para usar as ferramentas de desenvolvedor do Safari para inspecionar o conteúdo de um WebView no Mac Catalyst, adicione o seguinte código ao seu aplicativo:

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

Esse código personaliza o mapeador de propriedades para o WebViewHandler no Mac Catalyst, tornando o conteúdo WebView inspecionável pelas ferramentas de desenvolvedor do Safari. Para obter mais informações sobre manipuladores, consulte manipuladores.

Para usar ferramentas de desenvolvedor do Safari com um aplicativo Mac Catalyst:

1. Abra o Safari em seu Mac.
2. No Safari, selecione o menu Configurações >> Avançado > Mostrar Desenvolver na barra de menus caixa de seleção.
3. Execute seu aplicativo .NET MAUI Mac Catalyst.
4. No Safari, selecione o menu > {Nome do dispositivo} , em que o marcador {Device name} é o nome do dispositivo, como Macbook Pro. Em seguida, selecione a entrada associada ao nome do aplicativo, o que também destacará seu aplicativo em execução. Isso fará com que a janela do inspetor web apareça.

Iniciar o navegador do sistema

É possível abrir um URI no navegador da Web do sistema com a classe Launcher, que é fornecida pelo Microsoft.Maui.Essentials. Chame o método OpenAsync do inicializador e passe um argumento string ou Uri que representa o URI a ser aberto:

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

Para obter mais informações, consulte Launcher.