Usando quadros em aplicativos WebView2

Os quadros permitem que você insira outras páginas da Web em sua própria página da Web. Um quadro é uma subpágina ou área dentro de uma página da Web, como uma página da Web dentro de uma página da Web.

Um iframe é um tipo de quadro. Outros tipos de quadros são frameset, portal, embed, fencedFramee object. O principal tipo de WebView2 para quadros é CoreWebView2Frame, que está atualmente habilitado para iframes de nível superior. O suporte para outros tipos de molduras está planejado.

O WebView2 oferece suporte a APIs para interagir com iframes. Você pode:

  • Descubra quando os iframes são criados.
  • Descubra quando os iframes estão navegando para uma URL diferente. Isso funciona da mesma forma que os eventos de navegação da máquina de estado para aplicativos WebView2.
  • Comunicar-se entre o aplicativo host e os iframes, enviando mensagens em ambas as direções.
  • Permita que o aplicativo ignore o cabeçalho de X-Frame-Options resposta HTTP.

Veja também:

Assine o evento FrameCreated para obter um quadro

Para interagir com quadros em seu aplicativo host, a primeira etapa é assinar o evento para que seu FrameCreated aplicativo host obtenha um objeto de quadro. O FrameCreated evento é gerado sempre que um novo quadro é criado. Depois que o aplicativo host tiver obtido um objeto de quadro, use o objeto de quadro para monitorar as alterações e interagir com esse quadro específico.

Seu aplicativo host deve monitorar o tempo de vida de um quadro assinando o CoreWebView2Frame.Destroyed evento, pois quando o quadro é destruído, seu aplicativo host não pode mais fazer referência a esse quadro. Os quadros são criados e destruídos durante cada nova navegação na página da Web. Use o CoreWebView2Frame.IsDestroyed método para marcar se o quadro ainda existe.

Veja também:

  • iframes na Visão geral das APIs do WebView2.

Depois que um quadro é criado, o quadro navega até a URL de origem do quadro. Os iframes usam eventos de navegação e navegação, como FrameNavigationStarting e NavigationCompleted. Quando o quadro navega para a URL de origem, os seguintes eventos de navegação são gerados:

  • NavigationStarting
  • ContentLoading
  • HistoryChanged
  • DOMContentLoaded
  • NavigationCompleted

Frequência de navegação dentro de um quadro

A navegação pode acontecer potencialmente dentro de um quadro. Como um caso de uso simples, o atributo de source um iframe elemento é uma URL, como wikipedia.com, e a URL é carregada em um iframe. Normalmente, a navegação acontece imediatamente após a criação do quadro. Os ContentLoadingeventos , DOMContentLoadede NavigationCompleted são então gerados.

O próprio quadro está navegando. Uma página da Web navega para uma URL. Da mesma forma, um quadro potencialmente navega.

Depois que o quadro é criado, o quadro navega conforme orientado pelo aplicativo host. Para monitorar o que está acontecendo na página principal, eventos como NavigationStarting, NavigationCompleted, e HistoryChanged permitir que o aplicativo host navegue para frente e para trás entre quadros ou páginas da Web. Os quadros são navegados para uma nova URL com menos frequência do que as páginas da Web, mas há suporte para o mesmo estilo de navegação. O usuário geralmente não pode navegar dentro de um quadro, embora o JavaScript permita isso; Um quadro geralmente é estático em relação à navegação.

Veja também:

Eventos de navegação:

Em relação ao equivalente NavigationStarting duplicado e NavigationCompleted eventos, os eventos em CoreWebView2Frame são recomendados em vez dos eventos equivalentes substituídos em CoreWebView2, porque o CoreWebView2Frame tipo dá suporte a mais cenários para permitir interações com quadros.

Veja também:

Usando objetos hospedeiros em um iframe

Para se comunicar entre o lado nativo do aplicativo host e o JavaScript que está em um iframe, use objetos host. Um objeto host é um objeto que você cria no aplicativo host e, em seguida, usa a partir do código JavaScript no lado da página da Web do aplicativo.

O uso de APIs do lado nativo do script dentro de um quadro, por meio de um objeto host, é semelhante à estrutura de página de interoperabilidade da Web/nativa, conforme explicado em Chamar código do lado nativo do código do lado da Web:

Para usar objetos hospedeiros em um iframe:

  1. Defina o objeto host e implemente IDispatch.
  2. Adicione o objeto host no lado nativo usando AddHostObjectToScriptWithOrigins (Win32) ou AddHostObjectToScript (.NET).
  3. No JavaScript em seu código do lado da Web, acesse esse objeto host usando a chrome.webview.hostObjects.<name> API.

Para acessar e controlar objetos do lado nativo do JavaScript do lado da Web em um quadro, use AddHostObjectToScriptWithOrigins (Win32) ou CoreWebView2Frame.AddHostObjectToScript (.NET), que tem um origins parâmetro. O origins parâmetro especifica quais URLs iframes terão permissão para acessar, por motivos de segurança. Esse parâmetro identifica as URLs para as quais os iframes terão acesso ao objeto host.

Se o quadro for navegado para uma URL que não está na origins lista, o quadro não será capaz de operar o objeto host; o quadro não será capaz de ler ou gravar nenhuma propriedade. Consulte a tabela Nome do método no método de AddHostObjectToScript sua estrutura. Confira as duas linhas a seguir:

  • applyHostFunction, getHostPropertye setHostProperty.
  • getLocalProperty e setLocalProperty.

O método acima funciona como o seguinte método:

  • CoreWebView2.AddHostObjectToScript. Consulte a tabela Nome do método . Leia esses dois tópicos de referência da API, embora para quadros, você use o método que dá suporte a um origins parâmetro.

Código de exemplo

Consulte Etapa 6: Chamar AddHostObjectToScript para passar o objeto host para o código do lado da Web em Chamar o código do lado nativo do código do lado da Web.

Veja também:

Enviar e receber mensagens

As mensagens podem ser enviadas entre o aplicativo nativo e o código JavaScript que está em um iframe:

  • Você pode enviar mensagens do JavaScript em um iframe em uma página HTML para o aplicativo host.
  • Você pode enviar mensagens do aplicativo host para JavaScript em um iframe em uma página HTML.

Enviando mensagens da Web de um iframe para o aplicativo host

Para enviar mensagens da Web de um iframe para o aplicativo host, use o window.chrome.webview.postMessage método:

window.chrome.webview.postMessage(`SetTitleText ${titleText.value}`);

Para receber essas mensagens no aplicativo host, o aplicativo host deve assinar o WebMessageReceived event.

Enviar mensagens do aplicativo host para o iframe

O aplicativo host envia mensagens para o iframe chamando o PostWebMessageAsJson método ou PostWebMessageAsString .

O iframe recebe a mensagem assinando o window.chrome.webview.addEventListener('message') evento, da seguinte forma:

window.chrome.webview.addEventListener('message', arg => {
    // implement event listener here
});

Veja também:

Executar código JavaScript em iframes usando ExecuteScript

Um aplicativo WebView2 pode executar qualquer JavaScript em um quadro, usando .ExecuteScript

Para que o script seja executado em um iframe, um contexto de execução deve ser criado. Um contexto de execução é criado após o ContentLoading evento, por isso if ExecuteScript é chamado antes que o ContentLoading evento seja gerado, o script não será executado e a string null será retornada.

Para obter informações sobre o ContentLoading evento, consulte Eventos de navegação para aplicativos WebView2, que é válido para quadros e páginas da Web.

Veja também:

Modificando eventos de rede usando o WebResourceRequested evento em iframes

Esse recurso é experimental

Para iframes, você pode ouvir eventos de rede e modificá-los usando o WebResourceRequested evento.

Veja também:

Consulte as APIs de pré-lançamento mais recentes. Os links a seguir contêm 1.0.1466-prerelease. Na lista suspensa Versão no canto superior esquerdo dos documentos de Referência da API, selecione o pré-lançamento mais recente.

Ignorando X-Frame-Options para renderizar uma página da Web dentro de um quadro

O X-Frame-Options cabeçalho de resposta HTTP é usado por páginas da Web para impedir que um aplicativo renderize essa página da Web dentro de um quadro. A AdditionalAllowedFrameAncestors propriedade permite que seu aplicativo ignore o X-Frame-Options cabeçalho para renderizar a página da Web dentro de um quadro.

Veja também:

Exemplo de uso de iframes em um aplicativo host

Este código de exemplo mostra como usar APIs de quadro, incluindo:

  • FrameCreated
    • CoreWebView2FrameCreatedEventArgs
  • DOMContentLoaded
    • CoreWebView2DOMContentLoadedEventArgs
  • ExecuteScript

Esse código de exemplo é condensado de MainWindow.xaml.cs no exemplo WebView2WpfBrowser .

        void DOMContentLoadedCmdExecuted(object target, ExecutedRoutedEventArgs e)
        {
            // Subscribe to the FrameCreated event to obtain the frame object when 
            // it's created.
            webView.CoreWebView2.FrameCreated += WebView_FrameCreatedDOMContentLoaded;
            webView.NavigateToString(@"<!DOCTYPE html>" +
                                      "<h1>DOMContentLoaded sample page</h1>" +
                                      "<h2>The content to the iframe and below will be added after DOM content is loaded </h2>" +
                                      "<iframe style='height: 200px; width: 100%;'/>");
        }

        void WebView_FrameCreatedDOMContentLoaded(object sender, CoreWebView2FrameCreatedEventArgs args)
        {
            // In order for ExecuteScriptAsync to successfully run inside the iframe, 
            // subscribe to the ContentLoading or DOMContentLoaded event.  Once these 
            // events are raised, you can call ExecuteScriptAsync.
            args.Frame.DOMContentLoaded += (frameSender, DOMContentLoadedArgs) =>
            {
                args.Frame.ExecuteScriptAsync(
                    "let content = document.createElement(\"h2\");" +
                    "content.style.color = 'blue';" +
                    "content.textContent = \"This text was added to the iframe by the host app\";" +
                    "document.body.appendChild(content);");
            };
        }

Visão geral de referência de API

Os seguintes recursos, listados na Visão geral das APIs do WebView2, incluem APIs relacionadas a quadros:

Confira também

Páginas externas:

  • Last updated on