Usando conteúdo local em aplicativos WebView2

Além de carregar o conteúdo remoto, o conteúdo também pode ser carregado localmente no WebView2. Há várias abordagens que podem ser usadas para carregar conteúdo local em um controle WebView2, incluindo:

  • Navegando até uma URL de arquivo.
  • Navegando para uma cadeia de caracteres HTML.
  • Mapeamento de nome de host virtual.
  • Manipulando o WebResourceRequested evento.

Essas abordagens são descritas abaixo.

Selecionando uma abordagem

As várias maneiras de carregar conteúdo local em um controle WebView2 dão suporte aos seguintes cenários:

Cenário Ao navegar até uma URL de arquivo Navegando para uma cadeia de caracteres HTML Usando o mapeamento de nome de host virtual Usando WebResourceRequested
APIs DOM baseadas na origem ✔️ ❌ ✔️ ✔️
APIs DOM que exigem contexto seguro ❌ ❌ ✔️ ✔️
Conteúdo dinâmico ❌ ✔️ ❌ ✔️
Recursos adicionais da Web ✔️ ❌ ✔️ ✔️
Recursos adicionais da Web resolvidos no processo WebView2 ✔️ ❌ ✔️ ❌

Esses cenários são descritos em mais detalhes abaixo.

Carregando conteúdo local navegando até uma URL de arquivo

O WebView2 permite navegações para URLs de arquivos, para carregar HTML básico ou PDF. Essa é a abordagem mais simples e eficiente para carregar conteúdo local. No entanto, é menos flexível do que as outras abordagens. Como em um navegador da Web, as URLs de arquivo são limitadas em alguns recursos:

  • O documento tem uma origem única para seu caminho de arquivo. Isso significa que as APIs Web que exigem uma origem como localStorage OR indexedDB funcionarão, mas os dados armazenados não estarão disponíveis para outros documentos locais carregados de outros caminhos de arquivo.

  • Algumas APIs da Web são limitadas apenas a URLs HTTPS seguras e não estão disponíveis para documentos carregados por URLs de arquivo. Isso inclui APIs para navigator.mediaDevices.getUserMedia() adquirir vídeo ou som, navigator.geolocation.getCurrentPosition() acessar a localização do dispositivo ou Notification.requestPermission() solicitar a permissão do usuário para exibir notificações.

  • Para cada recurso, o caminho completo deve ser especificado.

  • Para permitir referências a outros arquivos locais de URIs de arquivos ou para exibir arquivos XML com transformações XSL aplicadas, você pode definir o argumento do --allow-file-access-from-files navegador. Consulte a propriedade CoreWebView2EnvironmentOptions.AdditionalBrowserArguments.

Considerações sobre o carregamento de conteúdo local navegando até uma URL de arquivo

As URLs de arquivo se comportam como no navegador. Por exemplo, você não pode criar um XMLHttpRequest (XHR) em uma URL de arquivo, porque não está trabalhando no contexto de uma página da Web.

Você deve especificar o caminho completo do arquivo para cada recurso. Por exemplo:

file:///C:/Users/username/Documents/GitHub/Demos/demo-to-do/index.html
Recursos entre origens

Ao especificar uma URL de arquivo, o aplicativo navega para um arquivo no disco, não para um domínio na rede. Como resultado, não é possível usar recursos de origem cruzada no documento resultante.

APIs DOM baseadas na origem

Um documento carregado por meio de uma URL de arquivo tem uma origem exclusiva para seu caminho de arquivo, assim como no navegador. APIs Web que exigem uma origem como localStorage OR indexedDB funcionarão. No entanto, diferentes documentos carregados de diferentes URLs de arquivo não são considerados da mesma origem e não terão acesso aos mesmos dados armazenados.

APIs DOM que exigem contexto seguro

Algumas APIs da Web são limitadas apenas a URLs HTTPS seguras e não estão disponíveis para documentos carregados por URLs de arquivo. Isso inclui APIs para navigator.mediaDevices.getUserMedia() adquirir vídeo ou som, navigator.geolocation.getCurrentPosition() acessar a localização do dispositivo ou Notification.requestPermission() solicitar a permissão do usuário para exibir notificações. Veja Contextos seguros no MDN para obter mais informações.

Conteúdo dinâmico

Ao carregar um documento por meio de uma URL de arquivo, o conteúdo do documento é proveniente de arquivos estáticos no disco. Isso significa que não é possível modificar dinamicamente esse conteúdo local. Isso é diferente de carregar documentos de um servidor Web, onde cada resposta pode ser gerada dinamicamente.

Recursos adicionais da Web

A resolução de URL relativa também funciona para documentos carregados por meio de uma URL de arquivo. Isso significa que o documento carregado pode ter referências a recursos adicionais da Web, como CSS, script ou arquivos de imagem, que também são servidos por URLs de arquivo.

Recursos adicionais da Web resolvidos no processo WebView2

URLs de arquivo são resolvidas em processos do WebView2. Essa é uma opção mais rápida do que WebResourceRequested, que é resolvida no thread da interface do usuário do processo do aplicativo host.

APIs para carregar conteúdo local navegando até uma URL de arquivo

Exemplo de uma URL de arquivo

Esta seção mostra a aparência de uma URL de arquivo para um caminho de arquivo de conteúdo local de maneira independente de plataforma.

Um aplicativo WebView2 precisa codificar URLs de arquivo local usando um file:/// prefixo e barras. Por exemplo, para o exemplo de Demonstração para fazer, o caminho seria:

file:///C:/Users/username/Documents/GitHub/Demos/demo-to-do/index.html

Para copiar o caminho completo com o prefixo "file" para um arquivo local:

  1. Opcionalmente, clone o repositório Demos para que você tenha uma cópia local. Consulte Etapa 5: Clonar o repositório Demos em Instalando a extensão DevTools para o Visual Studio Code.

  2. No Microsoft Edge, pressione Ctrl+O para abrir um arquivo. Abra um arquivo local .html , como o arquivo Demos/demo-to-do/index.htmlclonado localmente :

    C:\Users\username\Documents\GitHub\Demos\demo-to-do\index.html

    Inicialmente, a barra de endereços não mostra o prefixo file:/// , mas começa com a letra da unidade:

    C:/Users/username/Documents/GitHub/Demos/demo-to-do/index.html

    Barra de endereços do Microsoft Edge ocultando inicialmente o prefixo file:///

  3. Clique na barra de endereços e pressione a tecla Home ou pressione Ctrl+A para selecionar todo o caminho.

    A barra de endereços do Microsoft Edge agora mostrando o prefixo file:///

    Todo o caminho do arquivo, inclusive file:/// , é copiado para o buffer da área de transferência, para que você possa colar o caminho completo, incluindo o prefixo file:/// :

    file:///C:/Users/username/Documents/GitHub/Demos/demo-to-do/index.html

Veja também:

Exemplo de navegação para uma URL de arquivo

webView.CoreWebView2.Navigate(
          "file:///C:/Users/username/Documents/GitHub/Demos/demo-to-do/index.html");

Carregando conteúdo local navegando até uma string HTML

Outro método para carregar conteúdo local é o NavigateToString método. Essa abordagem carrega o conteúdo no WebView2 diretamente de uma cadeia de caracteres. Isso pode ser útil se você for empacotar o conteúdo por meio do código do aplicativo ou se quiser criar o conteúdo dinamicamente.

Outro cenário em que navegar até uma cadeia de caracteres pode ser útil é se você quiser carregar conteúdo que não está acessível por meio de uma URL. Por exemplo, se você tiver uma representação na memória de um documento HTML, poderá usar o NavigateToString método para carregar esse conteúdo no controle WebView2. Isso pode ser útil se você quiser evitar a necessidade de gravar o conteúdo em um arquivo ou servidor antes de carregá-lo no controle.

Considerações sobre o carregamento de conteúdo local navegando até uma cadeia de caracteres HTML

A cadeia de caracteres de conteúdo HTML passada para o NavigateToString método tem um limite de tamanho de 2 MB. Esse limite de tamanho pode ser fácil de ser excedido quando a cadeia de caracteres inclui recursos adicionais embutidos. Se esse limite de tamanho for excedido, um erro será retornado: "O valor não está dentro do intervalo esperado".

APIs DOM baseadas na origem

Um documento carregado usando o NavigateToString método tem sua localização definida como about:blank e sua origem definida como null. Isso significa que as APIs Web que dependem de uma origem que está sendo definida, como localStorage ou indexedDB, não podem ser usadas.

APIs DOM que exigem contexto seguro

Algumas APIs da Web são limitadas apenas a URLs HTTPS seguras e não estão disponíveis para documentos carregados por meio do NavigateToString método porque seu local está definido como about:blank. Isso inclui APIs para navigator.mediaDevices.getUserMedia() adquirir vídeo ou som, navigator.geolocation.getCurrentPosition() acessar a localização do dispositivo ou Notification.requestPermission() solicitar a permissão do usuário para exibir notificações. Veja Contextos seguros no MDN para obter mais informações.

Conteúdo dinâmico

Ao carregar conteúdo local por meio do NavigateToString método, você fornece diretamente o conteúdo como um parâmetro para o método. Isso significa que você está no controle do conteúdo em tempo de execução e pode gerá-lo dinamicamente, se necessário.

Recursos adicionais da Web

Carregar conteúdo local usando o NavigateToString método não possibilita que o documento resultante faça referência a recursos adicionais da Web, como arquivos CSS, de imagem ou de script. O método permite especificar apenas o conteúdo da cadeia de caracteres do documento HTML. Para fazer referência a recursos da Web adicionais do documento HTML, use uma das outras abordagens descritas neste artigo ou represente esses recursos da Web adicionais embutidos no documento HTML.

Recursos adicionais da Web resolvidos no processo WebView2

NavigateToString Não dá suporte a recursos adicionais da Web, conforme mencionado acima.

APIs para carregar conteúdo local navegando até uma cadeia de caracteres HTML

Exemplo de representação de cadeia de caracteres de uma página da Web

A seguir está a representação da cadeia de caracteres da página da Web Demo To Do . A listagem abaixo adicionou quebra de linha para legibilidade. Na prática, essas linhas são concatenadas em uma única linha longa:

`<html lang="en"><head>\n    
<meta charset="UTF-8">\n    
<meta name="viewport" content="width=device-width, initial-scale=1.0">\n    
<title>TODO app</title>\n    
<link rel="stylesheet" href="styles/light-theme.css" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)">\n    
<link rel="stylesheet" href="styles/dark-theme.css" media="(prefers-color-scheme: dark)">\n    
<link rel="stylesheet" href="styles/base.css">\n    
<link rel="stylesheet" href="styles/to-do-styles.css">\n    
<link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📋
</text></svg>">\n  
</head>\n\n  
<body>\n    
<h1>📋 My tasks</h1>\n    
<form>\n      
<div class="new-task-form" tabindex="0">\n        
<label for="new-task">➕ Add a task</label>\n        
<input id="new-task" autocomplete="off" type="text" placeholder="Try typing 'Buy milk'" title="Click to start adding a task">\n        
<input type="submit" value="➡️">\n      
</div>\n      
<ul id="tasks"><li class="divider">No tasks defined</li></ul>\n    
</form>\n\n    \x3Cscript src="to-do.js">\x3C/script>\n  \n\n
</body>
</html>`

Para obter a cadeia de caracteres acima:

  1. Vá para Demo To Do.

  2. Clique com o botão direito do mouse na página da Web e selecione Inspecionar para abrir o DevTools.

  3. No Console do DevTools, insira: document.body.parentElement.outerHTML. O Console gera uma representação de cadeia de caracteres da página da Web:

    Uma representação em cadeia de caracteres da página da Web Demo To Do

Exemplo de navegação para uma cadeia de caracteres HTML

// Define htmlString with the string representation of HTML as above.
webView.CoreWebView2.NavigateToString(htmlString);

Carregando conteúdo local usando o mapeamento de nome de host virtual

Outra maneira de carregar conteúdo local em um controle WebView2 é usar o mapeamento de nome de host virtual. Isso envolve o mapeamento de um nome de domínio local para uma pasta local, de modo que, quando o controle WebView2 tentar carregar um recurso para esse domínio, ele carregará o conteúdo do local da pasta local especificado. A origem do documento também será o nome do host virtual.

Essa abordagem permite especificar o acesso entre origens, usando a CoreWebView2HostResourceAccessKind enumeração.

Devido a uma limitação atual, os arquivos de mídia acessados usando um nome de host virtual podem ser lentos para carregar.

Considerações sobre o carregamento de conteúdo local usando o mapeamento de nome de host virtual

APIs DOM baseadas na origem

O conteúdo local carregado por meio do mapeamento de nome de host virtual resulta em um documento que tem uma URL HTTP ou HTTPS e uma origem correspondente. Isso significa que as APIs Web que exigem uma origem como localStorage ou indexedDB funcionarão e outros documentos que pertencem à mesma origem poderão usar os dados armazenados. Para obter mais informações, consulte Política de mesma origem no MDN.

APIs DOM que exigem contexto seguro

Algumas APIs Web são limitadas apenas para proteger URLs HTTPS. O uso do mapeamento de nome de host virtual fornece uma URL HTTPS para seu conteúdo local. Isso significa que as APIs para navigator.mediaDevices.getUserMedia() adquirir vídeo ou som, navigator.geolocation.getCurrentPosition() acessar a localização do dispositivo ou Notification.requestPermission() solicitar a permissão do usuário para exibir notificações estão disponíveis. Veja Contextos seguros no MDN para obter mais informações.

Conteúdo dinâmico

Ao carregar conteúdo local por meio de um mapeamento de nome de host virtual, você está mapeando um nome de host virtual para uma pasta local que contém arquivos estáticos no disco. Isso significa que não é possível modificar dinamicamente esse conteúdo local. Isso é diferente de carregar documentos de um servidor Web, onde cada resposta pode ser gerada dinamicamente.

Recursos adicionais da Web

O conteúdo local carregado por meio do mapeamento de nome de host virtual tem uma URL HTTP ou HTTPS que dá suporte à resolução de URL relativa. Isso significa que o documento carregado pode ter referências a recursos adicionais da Web, como CSS, script ou arquivos de imagem, que também são servidos por meio de mapeamento de nome de host virtual, exceto mapas de origem; consulte Mapas de origem com mapeamento de nome de host virtual, abaixo.

Recursos adicionais da Web resolvidos no processo WebView2

URLs de nome de host virtual são resolvidas em processos do WebView2. Essa é uma opção mais rápida do que WebResourceRequested, que é resolvida no thread da interface do usuário do processo do aplicativo host.

Mapas de origem com mapeamento de nome de host virtual

Os mapas de origem são necessários para depurar o código-fonte do conteúdo compilado, incluindo:

  • JavaScript transpilado, como TypeScript ou JavaScript minificado.
  • CSS compilado, como SASS ou SCSS.

O WebView2 não carrega mapas de origem referenciados pelo conteúdo que foi carregado usando o mapeamento de nome de host virtual.

Por exemplo, suponha que o WebView2 seja carregado main.js por meio do mapeamento de nome de host virtual. Se main.js referências main.js.map como seu mapa de origem, main.js.map não serão carregadas automaticamente.

Para usar mapas de origem junto com o mapeamento de nome de host virtual, gere mapas de origem embutidos durante a compilação do conteúdo. Os mapas de origem em linha são incorporados no arquivo compilado correspondente.

APIs para carregar conteúdo local usando o mapeamento de nome de host virtual

Exemplo de mapeamento de nome de host virtual

webView.CoreWebView2.SetVirtualHostNameToFolderMapping("demo", 
         "C:\Github\Demos\demo-to-do", CoreWebView2HostResourceAccessKind.DenyCors);
webView.CoreWebView2.Navigate("https://demo/index.html");

Carregando conteúdo local manipulando o WebResourceRequested evento

Outra maneira de hospedar conteúdo local em um controle WebView2 é confiando no WebResourceRequested evento. Esse evento é disparado quando o controle tenta carregar um recurso. Você pode usar esse evento para interceptar a solicitação e fornecer o conteúdo local, conforme descrito em Gerenciamento personalizado de solicitações de rede.

WebResourceRequested Permite personalizar o comportamento do conteúdo local por solicitação. Isso significa que você pode decidir para quais solicitações interceptar e fornecer seu próprio conteúdo e para quais solicitações permitir que o controle WebView2 lide normalmente. No entanto, personalizar o comportamento requer mais código, como mapeamento de host virtual, e requer conhecimento de HTTP, para poder construir uma resposta adequada.

Da perspectiva do WebView2, o recurso virá pela rede e o WebView2 aderirá aos cabeçalhos definidos pelo aplicativo como parte da resposta. O uso do WebResourceRequested evento também é mais lento do que outras abordagens, devido à comunicação e ao processamento entre processos necessários para cada solicitação.

Registro de esquema personalizado

Se você quiser usar um esquema personalizado para fazer a Solicitação de Recursos da Web que gera o WebResourceRequested evento, consulte Registro de esquema personalizado em Visão geral das APIs do WebView2.

Considerações sobre o carregamento de conteúdo local manipulando o WebResourceRequested evento

APIs DOM baseadas na origem

O conteúdo local carregado via WebResourceRequested resulta em um documento que tem uma URL HTTP ou HTTPS e uma origem correspondente. Isso significa que as APIs Web que exigem uma origem como localStorage ou indexedDB funcionarão e outros documentos que pertencem à mesma origem poderão usar os dados armazenados. Para obter mais informações, consulte Política de mesma origem no MDN.

APIs DOM que exigem contexto seguro

Algumas APIs Web são limitadas apenas para proteger URLs HTTPS. O uso WebResourceRequested permite que você substitua as solicitações de recursos da Web da URL HTTPS pelo seu próprio conteúdo local. Isso significa que as APIs para navigator.mediaDevices.getUserMedia() adquirir vídeo ou som, navigator.geolocation.getCurrentPosition() acessar a localização do dispositivo ou Notification.requestPermission() solicitar a permissão do usuário para exibir notificações estão disponíveis. Veja Contextos seguros no MDN para obter mais informações.

Conteúdo dinâmico

Ao carregar conteúdo local por meio WebResourceRequestedde , você especifica o conteúdo local a ser carregado em seu manipulador de eventos. Isso significa que você está no controle do conteúdo em tempo de execução e pode gerá-lo dinamicamente, se necessário.

Recursos adicionais da Web

WebResourceRequested modifica o conteúdo carregado por meio de URLs HTTP ou HTTPS, que dão suporte à resolução de URL relativa. Isso significa que o documento resultante pode ter referências a recursos adicionais da Web, como CSS, script ou arquivos de imagem que também são servidos por meio WebResourceRequestedde , exceto mapas de origem; consulte Mapas de origem com o WebResourceRequested evento, abaixo.

Recursos adicionais da Web resolvidos no processo WebView2

Ao carregar conteúdo por meio de uma URL de arquivo ou um mapeamento de nome de host virtual, a resolução ocorre nos processos do WebView2. No entanto, o WebResourceRequested evento é gerado no thread da interface do usuário WebView2 do processo do aplicativo host, o que pode levar a um carregamento mais lento do documento resultante.

  1. O WebView2 primeiro pausa o carregamento da página da Web para aguardar o evento ser enviado ao processo do aplicativo host.
  2. O WebView2 aguarda até que o thread da interface do usuário esteja disponível.
  3. O WebView2 aguarda o código do aplicativo manipular o evento.

Isso pode levar algum tempo. Certifique-se de limitar as chamadas apenas aos AddWebResourceRequestedFilter recursos da Web que devem gerar o WebResourceRequested evento.

Mapas de origem com o WebResourceRequested evento

Os mapas de origem são necessários para depurar o código-fonte do conteúdo compilado, incluindo:

  • JavaScript transpilado, como TypeScript ou JavaScript minificado.
  • CSS compilado, como SASS ou SCSS.

O WebView2 não carrega mapas de origem referenciados pelo conteúdo que foi carregado usando o WebResourceRequested evento.

Por exemplo, suponha que você carregue main.js seu WebResourceRequested manipulador de eventos definindo a Response propriedade de CoreWebView2WebResourceRequestedEventArgs. Se main.js referências main.js.map como mapa de origem:

  • main.js.map não serão carregadas automaticamente.
  • Seu WebResourceRequested manipulador de eventos não será chamado novamente para carregar main.js.map.

Para usar mapas de origem junto com WebResourceRequested, use uma das seguintes abordagens:

  • Gere mapas de origem embutidos durante a compilação do conteúdo. Os mapas de origem em linha são incorporados no arquivo compilado correspondente.

  • Ou mapas de origem separados embutidos para o conteúdo em tempo de execução no manipulador WebResourceRequested de eventos. Use essa abordagem somente se o sistema de build não der suporte a mapas de origem embutidos.

APIs para carregar conteúdo local manipulando o WebResourceRequested evento

Exemplo de manipulação do evento WebResourceRequested

// Reading of response content stream happens asynchronously, and WebView2 does not 
// directly dispose the stream once it read.  Therefore, use the following stream
// class, which properly disposes when WebView2 has read all data.  For details, see
// [CoreWebView2 does not close stream content](https://github.com/MicrosoftEdge/WebView2Feedback/issues/2513).
class ManagedStream : Stream {
    public ManagedStream(Stream s)
    {
        s_ = s;
    }

    public override bool CanRead => s_.CanRead;

    public override bool CanSeek => s_.CanSeek;

    public override bool CanWrite => s_.CanWrite;

    public override long Length => s_.Length;

    public override long Position { get => s_.Position; set => s_.Position = value; }

    public override void Flush()
    {
        throw new NotImplementedException();
    }

    public override long Seek(long offset, SeekOrigin origin)
    {
        return s_.Seek(offset, origin);
    }

    public override void SetLength(long value)
    {
        throw new NotImplementedException();
    }

    public override int Read(byte[] buffer, int offset, int count)
    {
        int read = 0;
        try
        {
            read = s_.Read(buffer, offset, count);
            if (read == 0)
            {
                s_.Dispose();
            }
        } 
        catch
        {
            s_.Dispose();
            throw;
        }
        return read;
    }

    public override void Write(byte[] buffer, int offset, int count)
    {
        throw new NotImplementedException();
    }

   private Stream s_;
}
webView.CoreWebView2.AddWebResourceRequestedFilter("https://demo/*", 
                                                CoreWebView2WebResourceContext.All);
webView.CoreWebView2.WebResourceRequested += delegate (object sender, 
                                     CoreWebView2WebResourceRequestedEventArgs args)
{
    string assetsFilePath = "C:\\Demo\\" + 
                            args.Request.Uri.Substring("https://demo/*".Length - 1);
    try
    {
        FileStream fs = File.OpenRead(assetsFilePath);
        ManagedStream ms = new ManagedStream(fs);
        string headers = "";
        if (assetsFilePath.EndsWith(".html"))
        {
            headers = "Content-Type: text/html";
        }
        else if (assetsFilePath.EndsWith(".jpg"))
        {
            headers = "Content-Type: image/jpeg";
        } else if (assetsFilePath.EndsWith(".png"))
        {
            headers = "Content-Type: image/png";
        }
        else if (assetsFilePath.EndsWith(".css"))
        {
            headers = "Content-Type: text/css";
        }
        else if (assetsFilePath.EndsWith(".js"))
        {
            headers = "Content-Type: application/javascript";
        }

        args.Response = webView.CoreWebView2.Environment.CreateWebResourceResponse(
                                                            ms, 200, "OK", headers);
    }
    catch (Exception)
    {
        args.Response = webView.CoreWebView2.Environment.CreateWebResourceResponse(
                                                        null, 404, "Not found", "");
    }
};

Confira também

  • Last updated on