Compartilhar via

Usando quadros em aplicativos WebView2

  • Artigo

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

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

O WebView2 dá 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 eventos de navegação do computador de estado para aplicativos WebView2.
  • Comunique-se entre o aplicativo host e os iframes, enviando mensagens em ambas as direções.
  • Permitir que o aplicativo ignore o X-Frame-Options cabeçalho de resposta HTTP.

Veja também:

Assinar 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 frame 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 referenciar esse quadro. Os quadros são criados e destruídos durante cada nova navegação de página da Web. Use o CoreWebView2Frame.IsDestroyed método para marcar se o quadro ainda existe.

Veja também:

  • iframes em Visão geral de recursos e APIs do WebView2.

Depois que um quadro é criado, o quadro navega até a URL de origem do quadro. iframes usam eventos de navegação e navegação, como FrameNavigationStarting e NavigationCompleted. Quando o quadro navega até 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 potencialmente acontecer 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 quadro em si está navegando. Uma página da Web navega até uma URL. Da mesma forma, um quadro potencialmente navega.

Depois que o quadro é criado, o quadro navega conforme controlado pelo aplicativo host. Para monitorar o que está acontecendo na página main, eventos como NavigationStarting, NavigationCompletede HistoryChanged permitir que o aplicativo host navegue 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 o mesmo estilo de navegação é compatível. O usuário geralmente não pode navegar dentro de um quadro, embora o JavaScript habilite isso; um quadro geralmente é estático em relação à navegação.

Veja também:

Eventos de navegação:

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

Veja também:

Usando objetos host em um iframe

Para se comunicar entre o lado nativo do aplicativo host e JavaScript que está em um iframe, use objetos host. Um objeto host é um objeto que você cria no aplicativo host e, em seguida, usa 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 web/nativa, conforme explicado em Chamar código nativo do código web:

Para usar objetos host 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 no código do lado da Web, acesse este objeto host usando chrome.webview.hostObjects.<name> a API.

Para acessar e controlar objetos nativos 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 serão permitidas 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 poderá operar o objeto host; o quadro não poderá ler ou gravar nenhuma propriedade. Consulte a tabela Nome do método no AddHostObjectToScript método para sua estrutura. Confira as duas linhas a seguir:

  • applyHostFunction, getHostPropertye setHostProperty.
  • getLocalProperty e setLocalProperty.

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

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

Código de exemplo

Consulte Etapa 6: chame AddHostObjectToScript para passar o objeto host para o código do lado da Web em Chamar código nativo do código 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.

Enviar 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 maneira:

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, se ExecuteScript for chamado antes do ContentLoading evento ser gerado, o script não será executado e a cadeia de caracteres null será retornada.

Para obter informações sobre o ContentLoading evento, consulte Eventos de navegação para aplicativos WebView2, que são válidos 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:

Confira 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 opções de quadro X 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

Este 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 da Referência de API

Os seguintes recursos, listados em Visão geral dos recursos e APIs do WebView2, incluem APIs relacionadas a quadros:

Confira também

Páginas externas: