Aplicación de ejemplo win32
La aplicación WebView2APISample muestra cómo usar el control WebView2 y las API de WebView2 para agregar características a una aplicación win32 de C++.
- Nombre de ejemplo: WebView2APISample
- Directorio del repositorio: WebView2APISample
- Archivo de solución:
WebView2Samples.sln
(ubicado en el directorio primario,\SampleApps\
) - Nombre del proyecto en Explorador de soluciones: WebView2APISample
WebView2APISample inserta un control WebView2 en una aplicación nativa win32.
Este ejemplo se compila como un proyecto de Visual Studio 2019 de Win32. Usa C++ y HTML/CSS/JavaScript en el entorno WebView2.
WebView2APISample muestra una selección de controladores de eventos y métodos de API de WebView2 que permiten que una aplicación win32 nativa interactúe directamente con un control WebView2 y viceversa.
Este ejemplo y su archivo de solución son únicos: contiene una copia de otros ejemplos, en Explorador de soluciones.
WebView2APISample es una aplicación híbrida creada con el control WebView2 de Microsoft Edge; es decir, esta aplicación combina un lado nativo y un lado de aplicación web del explorador. Consulte Enfoque de aplicaciones híbridas en Introducción a Microsoft Edge WebView2.
La ventana de la aplicación WebView2APISample en ejecución muestra la versión del SDK de WebView2 y también la versión y la ruta de acceso del entorno de ejecución de WebView2. Hay muchos menús útiles y menuitems proporcionados para usted:
Si es la primera vez que usa WebView, primero se recomienda seguir el tutorial Introducción a WebView2 en aplicaciones Win32, que explica cómo crear una aplicación WebView2 y le guía por algunas funciones básicas de WebView2. Ese tutorial en particular no comienza con la creación de un nuevo proyecto de Win32 mediante una plantilla de proyecto; en su lugar, comienza con un proyecto terminado en el repositorio WebView2Samples y le guía por el código WebView2 agregado.
Para obtener más información sobre los eventos y los controladores de API en WebView2, consulte WebView2 API Reference(Referencia de api de WebView2).
Paso 1: Instalación de Visual Studio
Microsoft Visual Studio es necesario (versión mínima: Visual Studio 2019). Microsoft Visual Studio Code no se admite para este ejemplo. Este ejemplo de repositorio es un proyecto de Visual Studio 2019. El ejemplo también se puede abrir con Visual Studio 2022.
- Si Visual Studio aún no está instalado con compatibilidad con C++, en una ventana o pestaña independiente, vea Instalar Visual Studio en Configurar el entorno de desarrollo para WebView2. Siga los pasos de esa sección para instalar Visual Studio con compatibilidad con C++, vuelva a esta página y continúe con los pasos siguientes.
Si desea usar Visual Studio 2017, después de abrir la solución en Visual Studio 2017, cambie el conjunto de herramientas de la plataforma del proyecto en propiedades > de la configuración de proyecto Conjunto de herramientas > general > de la plataforma.
Para usar Visual Studio 2017, es posible que también tenga que instalar una Windows SDK reciente en el equipo.
Paso 2: Clonación del repositorio WebView2Samples
Si aún no lo ha hecho, clone el repositorio en la
WebView2Samples
unidad local. En una ventana o pestaña independiente, consulte Descarga del repositorio WebView2Samples en Configuración del entorno de desarrollo para WebView2. Siga los pasos de esa sección y vuelva a esta página y continúe a continuación.Si previamente ha clonado el repositorio, extraiga las confirmaciones más recientes en la copia local del repositorio.
Paso 3: Abrir la solución en Visual Studio
En la unidad local, abra el
.sln
archivo en Visual Studio:<your-repos-directory>/WebView2Samples/SampleApps/WebView2Samples.sln
o bien:
<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2Samples.sln
El ejemplo y el proyecto WebView2APISample es el ejemplo principal de Win32.
A diferencia de otros ejemplos, no hay un archivo dedicado .sln
en el directorio del repositorio de ejemplo que contenga el archivo Léame de este ejemplo. En su lugar, el .sln
archivo de este ejemplo (incluidos también otros proyectos de ejemplo) está en el directorio primario.
Paso 4: Instalación de cargas de trabajo si se le solicita
Cargas de trabajo de Visual Studio : si se le solicita, instale las cargas de trabajo de Visual Studio que se soliciten. En una ventana o pestaña independiente, vea Instalar cargas de trabajo de Visual Studio en Configuración del entorno de desarrollo para WebView2. Siga los pasos de esa sección y vuelva a esta página y continúe a continuación.
Continúe con los pasos que se indican a continuación.
Paso 5: Visualización del proyecto abierto
En la unidad local, vuelva a abrir la solución WebView2Samples en la misma versión de Visual Studio que configuró:
<your-repos-directory>/WebView2Samples/SampleApps/WebView2Samples.sln
o bien:
<your-repos-directory>/WebView2Samples-main/SampleApps/WebView2Samples.sln
Haga clic en el botón Aceptar . El cuadro de diálogo Proyectos de redestinación podría abrir:
Ejemplo de versiones instaladas:
Haga clic en el botón Aceptar .
Explorador de soluciones muestra varios proyectos, incluido el proyecto WebView2APISample:
Paso 6: Compilación del proyecto con la versión instalada del SDK
En la parte superior de Visual Studio, establezca el destino de compilación, como se indica a continuación:
En la lista desplegable Configuraciones de solución , seleccione Depurar o Liberar.
En la lista desplegable Plataformas de soluciones, seleccione x86, x64 o ARM64.
En Explorador de soluciones, haga clic con el botón derecho en el proyecto WebView2APISample y, a continuación, seleccione Compilar.
De este modo, se compila el archivo
SampleApps/WebView2APISample/WebView2APISample.vcxproj
de proyecto .
Paso 7: Ejecución (depuración) del proyecto
Seleccione Depurar>iniciar depuración (F5).
Solución de problemas: si omite el paso de compilación y selecciona inmediatamente Depurar>iniciar depuración (F5), podría aparecer un cuadro de diálogo"No se puede iniciar el programa: No se puede encontrar la ruta de acceso especificada":
Para solucionar este problema: en Explorador de soluciones, haga clic con el botón derecho en el proyecto WebView2APISample y, a continuación, seleccione Compilar.
Se abre la ventana de la aplicación WebView2APISample :
En Visual Studio, seleccione Depurar>detener depuración. Visual Studio cierra la aplicación.
Paso 8: Actualización del SDK de WebView2 de versión preliminar
A continuación, actualizará el SDK de WebView2 y, a continuación, volverá a compilar el proyecto.
Si desea ver rápidamente qué versión del SDK de WebView2 está instalada en la copia del repositorio de la aplicación WebView2APISample en GitHub, consulte packages.config.
La versión del repositorio de este ejemplo tiene instalada una versión preliminar del SDK de WebView2. A continuación, lo actualizará a la versión preliminar más reciente del SDK de WebView2 o confirmará que está instalado el SDK más reciente. El uso de un SDK de versión preliminar le proporciona acceso a la funcionalidad más reciente.
Examine y, posiblemente, actualice los paquetes NuGet instalados, como se indica a continuación:
En Explorador de soluciones, haga clic con el botón derecho en el proyecto WebView2APISample (no en el nodo de solución situado encima) y, a continuación, seleccione Administrar paquetes NuGet.
El panel Administrador de paquetes NuGet se abre en Visual Studio.
A la derecha del cuadro de texto de búsqueda, active la casilla Incluir versión preliminar .
En el Administrador de paquetes NuGet, haga clic en la pestaña Instalado . En el lado derecho de cada paquete, compruebe si hay un número de versión más reciente, así como el número de versión existente.
Haga clic en la pestaña Actualizar . Si hay actualizaciones disponibles para paquetes WebView2 o WIL, si lo desea, puede actualizar el paquete aquí.
A la derecha, en la lista desplegable Versión , asegúrese de que la versión preliminar más reciente está seleccionada, si desea poder probar las API más recientes:
Haga clic en el botón Actualizar .
Aparece el cuadro de diálogo Vista previa de cambios :
La imagen anterior es de otro proyecto, pero es similar.
Haga clic en el botón Aceptar .
La versión más reciente del SDK de WebView2 ya está instalada para este proyecto.
Paso 9: Compilación y ejecución del proyecto con el SDK actualizado
En Explorador de soluciones, haga clic con el botón derecho en el proyecto WebView2APISample y, a continuación, seleccione Compilar.
Seleccione Depurar>iniciar depuración (F5).
Se abre la ventana de la aplicación WebView2APISample :
Use la aplicación WebView2APISample .
En Visual Studio, seleccione Depurar>detener depuración. Visual Studio cierra la aplicación.
Esto completa los pasos numerados para compilar y ejecutar la aplicación de ejemplo win32. A continuación, en el editor de código de Visual Studio, inspeccione el código, según las secciones siguientes.
Arquitectura de aplicaciones híbridas
La aplicación WebView2APISample es un ejemplo de una aplicación híbrida, con un elemento nativo win32 y un elemento WebView.
- La parte win32 puede acceder directamente a las API nativas de Windows.
- WebView es un contenedor para tecnologías web estándar (HTML, CSS y JavaScript).
Sección 1: La parte superior de la aplicación WebView2APISample es un componente win32 escrito en C++. Esta parte de la aplicación toma entradas de la interfaz de usuario del usuario y las usa para controlar WebView.
Sección 2: La parte principal de la aplicación WebView2APISample es un WebView que se puede reutilizar mediante tecnologías web estándar (HTML/CSS/JavaScript). Se puede navegar a sitios web o contenido local.
Este enfoque híbrido le permite crear e iterar más rápido mediante tecnologías web, a la vez que puede aprovechar las ventajas de la funcionalidad nativa. La aplicación WebView2APISample muestra cómo el componente Win32 y el componente WebView pueden interactuar entre sí.
Esta amplia aplicación de ejemplo ha crecido hasta incluir más de 150 menuitems, lo que muestra muchas API de WebView2 en el marco de Win32/C++. Las secciones siguientes se centran en los conceptos básicos de la implementación de aplicaciones híbridas.
Archivos de proyecto
En esta sección se explican brevemente algunos archivos clave dentro del repositorio. La aplicación WebView2APISample se divide verticalmente en componentes, en lugar de horizontalmente en capas. Cada componente implementa todo el flujo de trabajo de una categoría de características de ejemplo, desde la escucha de comandos de menú hasta la llamada a métodos de API WebView para implementarlos.
App.cpp
Este es el archivo de nivel superior que ejecuta la aplicación WebView2APISample . Lee las opciones de línea de comandos, configura el entorno de proceso y controla el modelo de subprocesos de la aplicación.
AppWindow.cpp (menú Ventana)
Este archivo implementa la ventana de la aplicación, haciendo lo siguiente:
Configure todos los controles de Win32.
Inicialice el entorno de WebView y el control WebView.
Agregue controladores de eventos a WebView y cree todos los componentes que controlan varias características de la aplicación.
La AppWindow
clase controla los comandos del menú Ventana de la aplicación de ejemplo.
Este archivo se describe con más detalle en Funciones clave en AppWindow.cpp, a continuación.
FileComponent.cpp (menú Archivo)
Este componente controla los comandos desde el menú Archivo (excepto exit), así como el DocumentTitleChanged
evento .
ScriptComponent.cpp (menú Script)
Este componente controla los comandos del menú Script , que implican la interacción con WebView mediante la inserción de JavaScript, la publicación de WebMessages, la adición de objetos nativos a la página web o el uso del protocolo DevTools para comunicarse con la página web.
ProcessComponent.cpp (menú Proceso)
Este componente controla los comandos del menú Proceso , que implican la interacción con el proceso del explorador. También controla el ProcessFailed
evento, en caso de que el proceso del explorador o uno de sus procesos de representación se bloquee o no responda.
SettingsComponent.cpp (menú Configuración)
Este componente controla los comandos del menú Configuración . Este componente también se encarga de copiar la configuración de una vista web antigua cuando se crea una nueva. La mayoría del código que interactúa con la ICoreWebView2Settings
interfaz se encuentra aquí.
ViewComponent.cpp (menú Ver)
Este componente controla los comandos del menú Ver y cualquier funcionalidad relacionada con el tamaño y la visibilidad de WebView. Cuando se cambia el tamaño de la ventana de la aplicación, se minimiza o se restaura, ViewComponent
se cambia el tamaño, se oculta o se muestra la vista web en respuesta. También responde al ZoomFactorChanged
evento.
ScenarioWebMessage.cpp y ScenarioWebMessage.html (menú Escenario)
El ScenarioWebMessage
componente se crea al seleccionar el elemento de menú Escenario>de mensajería web . Este componente implementa una aplicación de ejemplo con un elemento de C++ y un elemento HTML + JavaScript, que se comunican entre sí mediante la publicación y recepción asincrónica de mensajes.
Este componente se describe con más detalle en ScenarioWebMessage (.html, .cpp y .h), a continuación.
ScenarioAddHostObject.cpp y ScenarioAddHostObject.html (menú Escenario)
Este componente se crea al seleccionar el elemento de menúObjetos host de escenario>. Muestra la comunicación entre la aplicación nativa y la página web HTML mediante la inserción de objetos host. La interfaz del objeto host se declara en HostObjectSample.idl
y el propio objeto se implementa en HostObjectSampleImpl.cpp
.
Vea también:
Funciones clave en AppWindow.cpp
AppWindow.cpp
implementa la ventana de la aplicación, haciendo lo siguiente:
Configure todos los controles de Win32.
Inicialice el entorno de WebView y el control WebView.
Agregue controladores de eventos a WebView y cree todos los componentes que controlan varias características de la aplicación.
La AppWindow
clase controla los comandos del menú Ventana de la aplicación de ejemplo. A continuación se muestran algunas de las funciones clave de AppWindow.cpp
.
InitializeWebView()
En AppWindow.cpp
, la InitializeWebView()
función crea el entorno WebView2 mediante CreateCoreWebView2EnvironmentWithOptions.
Para ver estas llamadas API en acción, inspeccione el código siguiente desde 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()
Después de crear el entorno, creamos WebView mediante CreateCoreWebView2Controller
.
La OnCreateEnvironmentCompleted
función de devolución de llamada se pasa a CreateCoreWebView2EnvironmentWithOptions
en InitializeWebView()
. La devolución de llamada almacena el puntero de entorno y, a continuación, lo usa para crear un nuevo 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()
La OnCreateCoreWebView2ControllerCompleted
función de devolución de llamada se pasa a CreateCoreWebView2Controller
en InitializeWebView()
. Esta devolución de llamada:
- Inicializa el estado relacionado con WebView.
- Registra algunos controladores de eventos.
- Crea los componentes de la aplicación.
RegisterEventHandlers()
Se llama a la RegisterEventHandlers
función dentro de CreateCoreWebView2Controller
. Configura algunos de los controladores de eventos usados por la aplicación y los agrega a WebView.
Para obtener más información sobre los controladores de eventos en WebView2, vea ICoreWebView2.
A continuación se muestra un fragmento de código de RegisterEventHandlers()
, donde se configura un controlador de eventos para el NewWindowRequested
evento . Este evento se desencadena cuando JavaScript en la página web llama a window.open()
.
ICoreWebView2NewWindowRequestedEventHandler
hace un nuevo AppWindow
y pasa la vista web de la nueva ventana de vuelta al explorador, para que pueda devolverla de la window.open()
llamada. A diferencia de nuestras llamadas a CreateCoreWebView2EnvironmentWithOptions
y CreateCoreWebView2Controller
, en lugar de proporcionar un método para la devolución de llamada, simplemente proporcionamos una expresión lambda de C++ en ese momento y allí:
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 y .h)
Los ScenarioWebMessage
archivos muestran cómo el host win32 puede modificar WebView, cómo webview puede modificar el host win32 y cómo webview puede modificarse accediendo a la información desde el host win32. Esto se hace de forma asincrónica.
El ScenarioWebMessage
componente se crea al seleccionar el elemento de menú Escenario>de mensajería web . El ScenarioWebMessage
componente implementa una aplicación de ejemplo con un elemento de C++ y un elemento HTML+JavaScript, que se comunican entre sí mediante la publicación y recepción asincrónica de mensajes:
En las secciones siguientes se muestra cómo funciona cada función discreta mediante la aplicación WebView2APISample y, a continuación, se explica cómo implementar esta funcionalidad.
En primer lugar, vaya a la aplicación web ScenarioWebMessage dentro de la aplicación de ejemplo:
Abra (ejecute) la aplicación WebView2APISample .
En el menú Escenario , seleccione Mensajería web.
WebView muestra una página web titulada Página de ejemplo WebMessage (
ScenarioWebMessage.html
):
Para explorar la ScenarioWebMessage
funcionalidad, puede seguir las instrucciones de la página o seguir los pasos que se indican a continuación.
Publicación de mensajes desde el host Win32 en WebView
En los pasos siguientes se muestra cómo el host de Win32 puede modificar un WebView. En este ejemplo, convertirá el texto en azul:
Abra la página de ejemplo WebMessage (
ScenarioWebMessage.html
) como se describió anteriormente.En el menú Script , seleccione Post Web Message JSON (Publicar JSON de mensaje web).
Aparece un cuadro de diálogo que contiene el código
{"SetColor":"blue"}
escrito previamente.Haga clic en Aceptar.
El texto de la sección Mensajes de publicación de la página cambia de negro a azul.
Cómo funciona
En
ScriptComponent.cpp
, la llamada a PostWebMessageAsJson publica la entrada del usuario en laScenarioMessage.html
aplicación 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()); } }
Dentro de la aplicación web, los agentes de escucha de eventos se usan para recibir y responder al mensaje web. El fragmento de código siguiente es de
ScenarioWebMessage.html
. El agente de escucha de eventos cambia el color del texto si el argumento es "SetColor":window.chrome.webview.addEventListener('message', arg => { if ("SetColor" in arg.data) { document.getElementById("colorable").style.color = arg.data.SetColor; } });
Recepción de mensajes (desde WebView al host win32)
En los pasos siguientes se muestra cómo WebView puede modificar la aplicación host de Win32 cambiando el título de la aplicación Win32:
Abra la página de ejemplo WebMessage (
ScenarioWebMessage.html
) como se describió anteriormente.Observe el título de la aplicación WebView2APISample , que se muestra en la parte superior izquierda de la ventana situada junto al icono. Inicialmente es WebView2APISample: Microsoft Edge WebView2.
En la sección Recepción de mensajes de la página, escriba un nuevo título y, a continuación, haga clic en el botón Enviar .
Observe el nuevo título que se muestra en la barra de título de la aplicación WebView2APISample .
Cómo funciona
En
ScenarioWebMessage.html
, window.chrome.webview.postMessage() envía la entrada del usuario a la aplicación host:function SetTitleText() { let titleText = document.getElementById("title-text"); window.chrome.webview.postMessage(`SetTitleText ${titleText.value}`); }
En
ScenarioWebMessage.cpp
, usamos add_WebMessageReceived para registrar el controlador de eventos. Cuando recibimos el evento, después de validar la entrada, cambiamos el título de la ventana de la aplicación (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));
Mensajes de ida y vuelta (desde WebView al host de vuelta a WebView)
En los pasos siguientes se muestra cómo WebView puede obtener información del host de Win32 y modificarse a sí mismo mostrando el tamaño de la aplicación Win32.
Abra la página de ejemplo WebMessage (
ScenarioWebMessage.html
) como se describió anteriormente.En la sección Ida y vuelta de la página, haga clic en el botón GetWindowBounds .
El cuadro de texto situado debajo del botón muestra los límites de la aplicación WebView2APISample .
Cómo funciona
Cuando se hace clic en el botón Obtener límites de ventana , se llama a la
GetWindowBounds
función deScenarioWebMessage.html
.GetWindowBounds
llama a window.chrome.webview.postMessage() para enviar un mensaje a la aplicación host:function GetWindowBounds() { window.chrome.webview.postMessage("GetWindowBounds"); }
En
ScenarioWebMessage.cpp
, usamos add_WebMessageReceived para registrar el controlador de eventos recibidos. Después de validar la entrada, el controlador de eventos obtiene los límites de ventana de la ventana de la aplicación. PostWebMessageAsJson envía los límites a la aplicación 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())); }
En
ScenarioWebMessage.html
, un agente de escucha de eventos responde alWindowBounds
mensaje y muestra los límites de la ventana:window.chrome.webview.addEventListener('message', arg => { if ("WindowBounds" in arg.data) { document.getElementById("window-bounds").value = arg.data.WindowBounds; } });