Aplicação de exemplo Win32
A aplicação WebView2APISample demonstra como utilizar o controlo WebView2 e as APIs WebView2 para adicionar funcionalidades a uma aplicação Win32 C++.
- Nome de exemplo: WebView2APISample
- Diretório de repositório: WebView2APISample
- Ficheiro de solução:
WebView2Samples.sln
(localizado no diretório principal,\SampleApps\
) - Nome do projeto no Gerenciador de Soluções: WebView2APISample
WebView2APISample incorpora um controlo WebView2 numa aplicação nativa win32.
Este exemplo foi criado como um projeto do Win32 Visual Studio 2019. Utiliza C++ e HTML/CSS/JavaScript no ambiente WebView2.
WebView2APISample apresenta uma seleção dos processadores de eventos e métodos de API do WebView2 que permitem que uma aplicação Win32 nativa interaja diretamente com um controlo WebView2 e vice-versa.
Este exemplo e o respetivo ficheiro de solução são exclusivos: contém uma cópia de outros exemplos, no Gerenciador de Soluções.
WebView2APISample é uma aplicação híbrida criada com o controlo Microsoft Edge WebView2; ou seja, esta aplicação combina um lado nativo e um lado da aplicação Web do browser. Veja Abordagem da aplicação híbrida em Introdução ao Microsoft Edge WebView2.
A janela da aplicação WebView2APISample mostra a versão do SDK WebView2 e também a versão e o caminho do WebView2 Runtime. Existem muitos menus e menuitems úteis fornecidos para si:
Se esta for a primeira vez que utiliza o WebView, recomendamos que siga primeiro o tutorial Introdução ao WebView2 nas aplicações Win32, que explica como criar uma aplicação WebView2 e explica algumas funcionalidades básicas do WebView2. Este tutorial específico não começa com a criação de um novo projeto Win32 com um modelo de projeto; Em vez disso, começa com um projeto concluído no repositório WebView2Samples e orienta-o através do código WebView2 adicionado.
Para obter detalhes sobre eventos e processadores de API no WebView2, veja Referência da API webView2.
Passo 1 – Instalar o Visual Studio
O Microsoft Visual Studio é obrigatório (versão mínima: Visual Studio 2019). O Microsoft Visual Studio Code não é suportado para este exemplo. Este exemplo de repositório é um projeto do Visual Studio 2019. O exemplo também pode ser aberto com o Visual Studio 2022.
- Se o Visual Studio ainda não estiver instalado com suporte C++, numa janela ou separador separador, consulte Instalar o Visual Studio em Configurar o ambiente de Programador para WebView2. Siga os passos nessa secção para instalar o Visual Studio com suporte C++ e, em seguida, regresse a esta página e continue os passos abaixo.
Se quiser utilizar o Visual Studio 2017, depois de abrir a solução no Visual Studio 2017, altere o Conjunto de Ferramentas de Plataforma do projeto nas propriedades de Configuração de Propriedades > do Projeto Conjunto de Ferramentas > de Plataforma Geral>.
Para utilizar o Visual Studio 2017, também poderá ter de instalar uma SDK do Windows recente no seu computador.
Passo 2 – Clonar o repositório WebView2Samples
Se ainda não tiver terminado, clone o
WebView2Samples
repositório para a unidade local. Numa janela ou separador separador, consulte Transferir o repositório WebView2Samples em Configurar o ambiente de Programador para WebView2. Siga os passos nessa secção e, em seguida, regresse a esta página e continue abaixo.Se clonou anteriormente o repositório, solicite as consolidações mais recentes para a cópia local do repositório.
Passo 3 – Abrir a solução no Visual Studio
Na unidade local, abra o
.sln
ficheiro no Visual Studio:<your-repos-directory>/WebView2Samples/SampleApps/WebView2Samples.sln
ou:
<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2Samples.sln
O exemplo e o projeto WebView2APISample são os main exemplo Win32.
Ao contrário de outros exemplos, não existe um ficheiro dedicado .sln
no diretório de repositório de exemplo que contenha o Readme deste exemplo. Em vez disso, o .sln
ficheiro para este exemplo (incluindo outros projetos de exemplo) está no diretório principal.
Passo 4 – Instalar cargas de trabalho, se lhe for pedido
Cargas de trabalho do Visual Studio – se lhe for pedido, instale quaisquer cargas de trabalho do Visual Studio pedidas. Numa janela ou separador separador, consulte Instalar cargas de trabalho do Visual Studio em Configurar o ambiente Dev para WebView2. Siga os passos nessa secção e, em seguida, regresse a esta página e continue abaixo.
Continue os passos abaixo.
Passo 5 – Ver o projeto aberto
Na unidade local, abra novamente a solução WebView2Samples na mesma versão do Visual Studio que configurou:
<your-repos-directory>/WebView2Samples/SampleApps/WebView2Samples.sln
ou:
<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2Samples.sln
Clique no botão OK . A caixa de diálogo Retarget Projects (Retarget Projects ) poderá abrir:
Exemplo de versões instaladas:
Clique no botão OK .
Gerenciador de Soluções mostra vários projetos, incluindo o projeto WebView2APISample:
Passo 6 – Criar o projeto com a versão do SDK instalada
Na parte superior do Visual Studio, defina o destino da criação da seguinte forma:
Na lista pendente Configurações de Soluções , selecione Depurar ou Versão.
Na lista pendente Plataformas de Soluções , selecione x86, x64 ou ARM64.
No Gerenciador de Soluções, clique com o botão direito do rato no projeto WebView2APISample e, em seguida, selecione Compilar.
Esta ação cria o ficheiro
SampleApps/WebView2APISample/WebView2APISample.vcxproj
de projeto .
Passo 7 – Executar (depurar) o projeto
Selecione Depurar>Iniciar Depuração (F5).
Resolução de problemas: se ignorar o passo de compilação e selecionar imediatamente Depurar>Iniciar Depuração (F5), poderá ser apresentada uma caixa de diálogo"Não é possível iniciar o programa: Não é possível localizar o caminho especificado":
Para corrigir este problema: no Gerenciador de Soluções, clique com o botão direito do rato no projeto WebView2APISample e, em seguida, selecione Compilar.
É aberta a janela da aplicação WebView2APISample :
No Visual Studio, selecione Depurar>Parar Depuração. O Visual Studio fecha a aplicação.
Passo 8 – Atualizar o SDK WebView2 de pré-lançamento
Em seguida, irá atualizar o SDK WebView2 e, em seguida, recriar o projeto.
Se quiser ver rapidamente que versão do SDK WebView2 está instalada na cópia do repositório da aplicação WebView2APISample no GitHub, consulte packages.config.
A versão de repositório deste exemplo tem uma versão de pré-lançamento do SDK WebView2 instalada. Abaixo, irá atualizá-lo para a versão de pré-lançamento mais recente do SDK WebView2 ou confirmar que o SDK mais recente está instalado. Utilizar um SDK de pré-lançamento dá-lhe acesso às funcionalidades mais recentes.
Examine e, possivelmente, atualize os pacotes NuGet instalados da seguinte forma:
No Gerenciador de Soluções, clique com o botão direito do rato no projeto WebView2APISample (não no nó de solução acima) e, em seguida, selecione Gerir Pacotes NuGet.
O painel Gestor de Pacotes NuGet é aberto no Visual Studio.
À direita da caixa de texto de pesquisa, selecione a caixa de marcar Incluir pré-lançamento.
No Gestor de Pacotes NuGet, clique no separador Instalado. No lado direito de cada pacote, marcar se existe um número de versão mais recente listado, bem como o número da versão existente.
Clique no separador Atualizar . Se estiverem disponíveis atualizações para pacotes WebView2 ou WIL, se quiser, pode atualizar o pacote aqui.
À direita, na lista pendente Versão , certifique-se de que a opção Pré-lançamento mais recente está selecionada se quiser experimentar as APIs mais recentes:
Clique no botão Atualizar .
É apresentada a caixa de diálogo Pré-visualizar Alterações :
A imagem acima é de outro projeto, mas é semelhante.
Clique no botão OK .
A versão mais recente do SDK WebView2 está agora instalada para este projeto.
Passo 9 – Criar e executar o projeto com o SDK atualizado
No Gerenciador de Soluções, clique com o botão direito do rato no projeto WebView2APISample e, em seguida, selecione Compilar.
Selecione Depurar>Iniciar Depuração (F5).
É aberta a janela da aplicação WebView2APISample :
Utilize a aplicação WebView2APISample .
No Visual Studio, selecione Depurar>Parar Depuração. O Visual Studio fecha a aplicação.
Isto conclui os passos numerados para criar e executar a aplicação de exemplo Win32. Em seguida, no editor de código do Visual Studio, inspecione o código, de acordo com as secções seguintes.
Arquitetura de aplicações híbridas
A aplicação WebView2APISample é um exemplo de uma aplicação híbrida, com uma peça nativa Win32 e uma peça WebView.
- A parte Win32 pode aceder diretamente às APIs nativas do Windows.
- O WebView é um contentor para tecnologias Web padrão (HTML, CSS e JavaScript).
Secção 1: a parte superior da aplicação WebView2APISample é um componente Win32 escrito em C++. Esta parte da aplicação recebe entradas de IU do utilizador e utiliza-as para controlar o WebView.
Secção 2: a parte main da aplicação WebView2APISample é uma WebView que pode ser reutilizada com tecnologias Web padrão (HTML/CSS/JavaScript). Pode ser navegado para sites ou conteúdos locais.
Esta abordagem híbrida permite-lhe criar e iterar mais rapidamente com tecnologias Web, ao mesmo tempo que pode tirar partido da funcionalidade nativa. A aplicação WebView2APISample demonstra como o componente Win32 e o componente WebView podem interagir entre si.
Esta aplicação de exemplo abrangente cresceu para incluir mais de 150 menuitems, demonstrando muitas APIs WebView2 na arquitetura Win32/C++. As secções seguintes focam-se nas noções básicas da implementação de aplicações híbridas.
Ficheiros do Project
Esta secção explica brevemente alguns ficheiros chave no repositório. A aplicação WebView2APISample está dividida verticalmente em componentes, em vez de horizontalmente em camadas. Cada componente implementa todo o fluxo de trabalho de uma categoria de funcionalidades de exemplo, desde escutar comandos de menu até chamar métodos da API WebView para implementá-los.
App.cpp
Este é o ficheiro de nível superior que executa a aplicação WebView2APISample . Lê as opções da linha de comandos, configura o ambiente de processo e processa o modelo de threading da aplicação.
AppWindow.cpp (menu Janela)
Este ficheiro implementa a janela da aplicação ao fazer o seguinte:
Configure todos os controlos Win32.
Inicialize o Ambiente webView e o WebView.
Adicione processadores de eventos ao WebView e crie todos os componentes que processam várias funcionalidades da aplicação.
A AppWindow
classe processa comandos do menu Janela da aplicação de exemplo.
Este ficheiro é descrito mais detalhadamente em Funções de chave no AppWindow.cpp, abaixo.
FileComponent.cpp (menu Ficheiro)
Este componente processa comandos do menu Ficheiro ( exceto sair), bem como do DocumentTitleChanged
evento.
ScriptComponent.cpp (menu Script)
Este componente processa comandos do menu Script , que envolvem interagir com o WebView ao injetar JavaScript, publicar WebMessages, adicionar objetos nativos à página Web ou utilizar o protocolo DevTools para comunicar com a página Web.
ProcessComponent.cpp (menu Processo)
Este componente processa comandos do menu Processo , que envolvem interação com o processo do browser. Também processa o ProcessFailed
evento, caso o processo do browser ou um dos processos de composição falhe ou não responda.
SettingsComponent.cpp (menu Definições)
Este componente processa comandos a partir do menu Definições . Este componente também é responsável pela cópia das definições de uma WebView antiga quando é criada uma nova. A maioria do código que interage com a ICoreWebView2Settings
interface encontra-se aqui.
ViewComponent.cpp (menu Ver)
Este componente processa comandos do menu Ver e quaisquer funcionalidades relacionadas com o dimensionamento e visibilidade do WebView. Quando a janela da aplicação é redimensionada, minimizada ou restaurada, ViewComponent
irá redimensionar, ocultar ou mostrar o WebView em resposta. Também responde ao ZoomFactorChanged
evento.
ScenarioWebMessage.cpp e ScenarioWebMessage.html (menu Cenário)
O ScenarioWebMessage
componente é criado quando seleciona o item de menu Cenário>de Mensagens Web . Este componente implementa uma aplicação de exemplo com uma parte C++ e uma parte HTML + JavaScript, que comunicam entre si ao publicar e receber mensagens de forma assíncrona.
Este componente é descrito mais detalhadamente em ScenarioWebMessage (.html, .cpp e .h), abaixo.
ScenarioAddHostObject.cpp e ScenarioAddHostObject.html (menu Cenário)
Este componente é criado quando seleciona o item de menuObjetos de Anfitrião do Cenário>. Demonstra a comunicação entre a aplicação nativa e a página Web HTML através da injeção de objeto anfitrião. A interface do objeto anfitrião é declarada em HostObjectSample.idl
e o próprio objeto é implementado no HostObjectSampleImpl.cpp
.
Veja também:
Funções-chave no AppWindow.cpp
AppWindow.cpp
implementa a janela da aplicação ao fazer o seguinte:
Configure todos os controlos Win32.
Inicialize o Ambiente webView e o WebView.
Adicione processadores de eventos ao WebView e crie todos os componentes que processam várias funcionalidades da aplicação.
A AppWindow
classe processa comandos do menu Janela da aplicação de exemplo. Seguem-se algumas das principais funções em AppWindow.cpp
.
InitializeWebView()
No AppWindow.cpp
, a InitializeWebView()
função cria o ambiente WebView2 com CreateCoreWebView2EnvironmentWithOptions.
Para ver estas chamadas à API em ação, inspecione o seguinte código em InitializeWebView()
:
HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
subFolder, nullptr, options.Get(),
Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
this, &AppWindow::OnCreateEnvironmentCompleted)
.Get());
if (!SUCCEEDED(hr))
{
if (hr == HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))
{
MessageBox(
m_mainWindow,
L"Couldn't find Edge installation. "
"Do you have a version installed that's compatible with this "
"WebView2 SDK version?",
nullptr, MB_OK);
}
else
{
ShowFailure(hr, L"Failed to create webview environment");
}
}
OnCreateEnvironmentCompleted()
Depois de criar o ambiente, criamos o WebView com CreateCoreWebView2Controller
.
A OnCreateEnvironmentCompleted
função de chamada de retorno é transmitida para CreateCoreWebView2EnvironmentWithOptions
em InitializeWebView()
. A chamada de retorno armazena o ponteiro do ambiente e, em seguida, utiliza-o para criar um novo WebView:
HRESULT AppWindow::OnCreateEnvironmentCompleted(
HRESULT result, ICoreWebView2Environment* environment)
{
CHECK_FAILURE(result);
m_webViewEnvironment = environment;
CHECK_FAILURE(m_webViewEnvironment->CreateCoreWebView2Controller(
m_mainWindow, Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
this, &AppWindow::OnCreateCoreWebView2ControllerCompleted)
.Get()));
return S_OK;
}
OnCreateCoreWebView2ControllerCompleted()
A OnCreateCoreWebView2ControllerCompleted
função de chamada de retorno é transmitida para CreateCoreWebView2Controller
em InitializeWebView()
. Esta chamada de retorno:
- Inicializa o estado relacionado com WebView.
- Regista alguns processadores de eventos.
- Cria os componentes da aplicação.
RegisterEventHandlers()
A RegisterEventHandlers
função é chamada dentro de CreateCoreWebView2Controller
. Configura alguns dos processadores de eventos utilizados pela aplicação e adiciona-os ao WebView.
Para obter mais informações sobre processadores de eventos no WebView2, consulte ICoreWebView2.
Segue-se um fragmento de código de RegisterEventHandlers()
, onde configuramos um processador de eventos para o NewWindowRequested
evento. Este evento é acionado quando o JavaScript na página Web chama window.open()
.
ICoreWebView2NewWindowRequestedEventHandler
cria um novo AppWindow
e transmite o WebView da nova janela para o browser, para que possa devolvê-lo a window.open()
partir da chamada. Ao contrário das nossas chamadas para CreateCoreWebView2EnvironmentWithOptions
e CreateCoreWebView2Controller
, em vez de fornecer um método para a chamada de retorno, apenas fornecemos um C++ lambda imediatamente e ali:
CHECK_FAILURE(m_webView->add_NewWindowRequested(
Callback<ICoreWebView2NewWindowRequestedEventHandler>(
[this](
ICoreWebView2* sender,
ICoreWebView2NewWindowRequestedEventArgs* args) {
wil::com_ptr<ICoreWebView2Deferral> deferral;
CHECK_FAILURE(args->GetDeferral(&deferral));
auto newAppWindow = new AppWindow(L"");
newAppWindow->m_isPopupWindow = true;
newAppWindow->m_onWebViewFirstInitialized = [args, deferral, newAppWindow]() {
CHECK_FAILURE(args->put_NewWindow(newAppWindow->m_webView.get()));
CHECK_FAILURE(args->put_Handled(TRUE));
CHECK_FAILURE(deferral->Complete());
};
return S_OK;
})
.Get(),
nullptr));
ScenarioWebMessage (.html, .cpp e .h)
Os ScenarioWebMessage
ficheiros mostram como o anfitrião Win32 pode modificar o WebView, como o WebView pode modificar o anfitrião Win32 e como o WebView se pode modificar ao aceder às informações do anfitrião Win32. Isto é feito de forma assíncrona.
O ScenarioWebMessage
componente é criado quando seleciona o item de menu Cenário>de Mensagens Web . O ScenarioWebMessage
componente implementa uma aplicação de exemplo com uma parte C++ e uma parte HTML+JavaScript, que comunicam entre si ao publicar e receber mensagens de forma assíncrona:
As secções seguintes demonstram como cada função discreta funciona com a aplicação WebView2APISample e, em seguida, explica como implementar esta funcionalidade.
Primeiro, aceda à aplicação Web ScenarioWebMessage na aplicação de exemplo:
Abra (execute) a aplicação WebView2APISample .
No menu Cenário , selecione Mensagens Web.
O WebView apresenta uma página Web intitulada Página de exemplo WebMessage (
ScenarioWebMessage.html
):
Para explorar a ScenarioWebMessage
funcionalidade, pode seguir as instruções na página ou seguir os passos abaixo.
Publicar Mensagens do anfitrião Win32 no WebView
Os passos seguintes mostram como o Anfitrião Win32 pode modificar um WebView. Neste exemplo, irá tornar o texto azul:
Abra a página de exemplo WebMessage (
ScenarioWebMessage.html
), conforme descrito acima.No menu Script , selecione Publicar Mensagem Web JSON.
É apresentada uma caixa de diálogo que contém o código
{"SetColor":"blue"}
pré-escrito.Clique em OK.
O texto na secção Mensagens de Publicação da página muda de preto para azul.
Como funciona
No
ScriptComponent.cpp
, a chamada para PostWebMessageAsJson publica a entrada do utilizador na aplicaçãoScenarioMessage.html
Web:// Prompt the user for some JSON and then post it as a web message. void ScriptComponent::SendJsonWebMessage() { TextInputDialog dialog( m_appWindow->GetMainWindow(), L"Post Web Message JSON", L"Web message JSON:", L"Enter the web message as JSON.", L"{\"SetColor\":\"blue\"}"); if (dialog.confirmed) { m_webView->PostWebMessageAsJson(dialog.input.c_str()); } }
Na aplicação Web, os serviços de escuta de eventos são utilizados para receber e responder à mensagem Web. O fragmento de código abaixo é de
ScenarioWebMessage.html
. O serviço de escuta de eventos altera a cor do texto se o argumento for "SetColor":window.chrome.webview.addEventListener('message', arg => { if ("SetColor" in arg.data) { document.getElementById("colorable").style.color = arg.data.SetColor; } });
Receber mensagens (do WebView para o anfitrião Win32)
Os passos seguintes mostram como o WebView pode modificar a Aplicação Anfitriã Win32 ao alterar o título da aplicação Win32:
Abra a página de exemplo WebMessage (
ScenarioWebMessage.html
), conforme descrito acima.Tenha em atenção o título da aplicação WebView2APISample , apresentado no canto superior esquerdo da janela junto ao ícone. Inicialmente, é WebView2APISample – Microsoft Edge WebView2.
Na secção Receber Mensagens da página, introduza um novo título e, em seguida, clique no botão Enviar .
Tenha em atenção o novo título que é apresentado na barra de título da aplicação WebView2APISample .
Como funciona
No
ScenarioWebMessage.html
, window.chrome.webview.postMessage() envia a entrada do utilizador para a aplicação anfitriã:function SetTitleText() { let titleText = document.getElementById("title-text"); window.chrome.webview.postMessage(`SetTitleText ${titleText.value}`); }
No
ScenarioWebMessage.cpp
, utilizamos add_WebMessageReceived para registar o processador de eventos. Quando recebermos o evento, depois de validar a entrada, alteramos o título da Janela da Aplicação (m_appWindow
):// Setup the web message received event handler before navigating to // ensure we don't miss any messages. CHECK_FAILURE(m_webview->add_WebMessageReceived( Microsoft::WRL::Callback<ICoreWebView2WebMessageReceivedEventHandler>( [this](ICoreWebView2* sender, ICoreWebView2WebMessageReceivedEventArgs* args) { wil::unique_cotaskmem_string uri; CHECK_FAILURE(args->get_Source(&uri)); // Always validate that the origin of the message is what you expect. if (uri.get() != m_sampleUri) { return S_OK; } wil::unique_cotaskmem_string messageRaw; CHECK_FAILURE(args->TryGetWebMessageAsString(&messageRaw)); std::wstring message = messageRaw.get(); if (message.compare(0, 13, L"SetTitleText ") == 0) { m_appWindow->SetTitleText(message.substr(13).c_str()); } return S_OK; }).Get(), &m_webMessageReceivedToken));
Mensagens de ida e volta (do WebView para o anfitrião de volta para o WebView)
Os passos seguintes mostram como o WebView pode obter informações do Anfitrião Win32 e modificar-se ao apresentar o tamanho da Aplicação Win32.
Abra a página de exemplo WebMessage (
ScenarioWebMessage.html
), conforme descrito acima.Na secção Ida e volta da página, clique no botão GetWindowBounds .
A caixa de texto abaixo do botão apresenta os limites da aplicação WebView2APISample .
Como funciona
Quando o botão Obter limites da janela é clicado, a
GetWindowBounds
função emScenarioWebMessage.html
é chamada.GetWindowBounds
chama window.chrome.webview.postMessage() para enviar uma mensagem para a aplicação anfitriã:function GetWindowBounds() { window.chrome.webview.postMessage("GetWindowBounds"); }
No
ScenarioWebMessage.cpp
, utilizamos add_WebMessageReceived para registar o processador de eventos recebido. Depois de validar a entrada, o processador de eventos obtém limites de janela a partir da Janela da Aplicação. PostWebMessageAsJson envia os limites para a aplicação Web:if (message.compare(L"GetWindowBounds") == 0) { RECT bounds = m_appWindow->GetWindowBounds(); std::wstring reply = L"{\"WindowBounds\":\"Left:" + std::to_wstring(bounds.left) + L"\\nTop:" + std::to_wstring(bounds.top) + L"\\nRight:" + std::to_wstring(bounds.right) + L"\\nBottom:" + std::to_wstring(bounds.bottom) + L"\"}"; CHECK_FAILURE(sender->PostWebMessageAsJson(reply.c_str())); }
No
ScenarioWebMessage.html
, um serviço de escuta de eventos responde àWindowBounds
mensagem e apresenta os limites da janela:window.chrome.webview.addEventListener('message', arg => { if ("WindowBounds" in arg.data) { document.getElementById("window-bounds").value = arg.data.WindowBounds; } });