Convenciones de la API De C++ WebView2 de Win32

  • Artículo

Plataformas admitidas: Win32.

Requisitos previos

  • Experiencia con la API win32.

Métodos asincrónicos

Los métodos asincrónicos de la API de C++ Win32 de WebView2 usan una interfaz de delegado para ponerse en contacto con usted por cualquiera de los siguientes motivos:

  • Se ha completado el método asincrónico.
  • Código correcto o de error.
  • Resultado del método asincrónico.

El parámetro final de todos los métodos asincrónicos es un puntero a una interfaz de delegado, de la que se proporciona una implementación.

La interfaz de delegado tiene un único Invoke método que toma como primer parámetro un HRESULT código correcto o de error. Además, puede haber un segundo parámetro que sea el resultado del método, si el método tiene un resultado.

Por ejemplo, el método ICoreWebView2::CapturePreview toma un ICoreWebView2CapturePreviewCompletedHandler puntero como parámetro final. Para enviar una CapturePreview solicitud de método, proporcione una instancia del ICoreWebView2CapturePreviewCompletedHandler puntero que implemente.

El código siguiente usa el Invoke método para implementar un ICoreWebView2CapturePreviewCompletedHandler puntero:

HRESULT Invoke(HRESULT result)

Implemente el Invoke método y, a continuación, CoreWebView2 solicite el Invoke método cuando CapturePreview se complete la solicitud. El único parámetro es el HRESULT que describe el código correcto o incorrecto de la CapturePreview solicitud.

Como alternativa, para ICoreWebView2::ExecuteScript, se proporciona una instancia que tiene un Invoke método que proporciona el código correcto o de error de la ExecuteScript solicitud. Proporcione también el segundo parámetro, que es el JSON del resultado de ejecutar el script.

Puede implementar manualmente las CompleteHandler interfaces de delegado o puede usar la función devolución de llamada (WRL). La función de devolución de llamada (WRL) se usa en el código WebView2 siguiente:

void ScriptComponent::InjectScript()
{
    TextInputDialog dialog(
        m_appWindow->GetMainWindow(),
        L"Inject Script",
        L"Enter script code:",
        L"Enter the JavaScript code to run in the WebView2 control.",
        L"window.getComputedStyle(document.body).backgroundColor");
    if (dialog.confirmed)
    {
        m_webView->ExecuteScript(dialog.input.c_str(),
            Callback<ICoreWebView2ExecuteScriptCompletedHandler>(
                [](HRESULT error, PCWSTR result) -> HRESULT
        {
            if (error != S_OK) {
                ShowFailure(error, L"ExecuteScript failed");
            }
            MessageBox(nullptr, result, L"ExecuteScript Result", MB_OK);
            return S_OK;
        }).Get());
    }
}

Eventos

Los eventos de la API de C++ de Win32 de WebView2 usan el add_EventName par de métodos y remove_EventName para suscribirse y cancelar la suscripción a eventos. El add_EventName método toma una interfaz de delegado del controlador de eventos y devuelve un EventRegistrationToken token como parámetro de salida. El remove_EventName método toma un EventRegistrationToken token y cancela la suscripción de eventos correspondiente.

Interfaces de delegado del controlador de eventos

Las interfaces de delegado del controlador de eventos funcionan de forma similar a las interfaces de delegado de controlador completadas por el método asincrónico. Implemente la interfaz de delegado del controlador de eventos y CoreWebView2 envíe una devolución de llamada cada vez que se ejecute el evento.

Cada interfaz de delegado del controlador de eventos tiene un único Invoke método que tiene un parámetro sender seguido de un parámetro de argumentos de evento. El remitente es la instancia del objeto en el que se suscribió para eventos. El parámetro event args es una interfaz que contiene información sobre el evento que se activa actualmente.

Por ejemplo, el NavigationCompleted evento en ICoreWebView2 tiene el par de ICoreWebView2::add_NavigationCompleted métodos y ICoreWebView2::remove_NavigationCompleted . Al enviar una solicitud, proporciona una instancia de en la ICoreWebView2NavigationCompletedEventHandler que implementó Invoke previamente el método .

Cuando se ejecuta el NavigationCompleted evento, se solicita el Invoke método:

  • El primer parámetro ejecuta el NavigationCompleted evento.
  • El segundo parámetro contiene información sobre si la navegación se completó correctamente, etc.

De forma similar a la interfaz de delegado del controlador completada por el método asincrónico, use una de las siguientes acciones para configurarla:

// Register a handler for the NavigationCompleted event.
// Check whether the navigation succeeded, and if not, do something.
// Also update the Cancel buttons.
CHECK_FAILURE(m_webView->add_NavigationCompleted(
    Callback<ICoreWebView2NavigationCompletedEventHandler>(
        [this](ICoreWebView2* sender, ICoreWebView2NavigationCompletedEventArgs* args)
            -> HRESULT {
            BOOL success;
            CHECK_FAILURE(args->get_IsSuccess(&success));
            if (!success)
            {
                COREWEBVIEW2_WEB_ERROR_STATUS webErrorStatus;
                CHECK_FAILURE(args->get_WebErrorStatus(&webErrorStatus));
                if (webErrorStatus == COREWEBVIEW2_WEB_ERROR_STATUS_DISCONNECTED)
                {
                    // Do something here if you want to handle a specific error case.
                    // In most cases it is not necessary, because the WebView2 control
                    // displays an error page automatically.
                }
            }
            m_toolbar->SetItemEnabled(Toolbar::Item_CancelButton, false);
            m_toolbar->SetItemEnabled(Toolbar::Item_ReloadButton, true);
            return S_OK;
        })
        .Get(),
    &m_navigationCompletedToken));

Cadenas

Los parámetros de salida de cadena son LPWSTR cadenas terminadas en null. El solicitante proporciona la cadena mediante CoTaskMemAlloc. La propiedad se transfiere al solicitante y depende del solicitante liberar la memoria mediante CoTaskMemFree.

Los parámetros de entrada de cadena son LPCWSTR cadenas terminadas en null. El solicitante garantiza que la cadena sea válida mientras dure la solicitud de función sincrónica. Si el receptor debe almacenar el valor en algún momento después de que se complete la solicitud de función, el receptor debe proporcionar una copia asociada del valor de cadena.

Análisis de URI y JSON

Varios métodos proporcionan o aceptan URI y JSON como cadenas. Use la biblioteca que prefiera para analizar y generar las cadenas.

Si WinRT está disponible para la aplicación, puede usar los RuntimeClass_Windows_Data_Json_JsonObject métodos y IJsonObjectStatics para analizar o generar cadenas JSON, o RuntimeClass_Windows_Foundation_Uri métodos y IUriRuntimeClassFactory para analizar y generar URI. Ambos enfoques funcionan en aplicaciones Win32.

Si usa IUri y CreateUri para analizar uri, es posible que desee usar las siguientes marcas de creación de URI para que el comportamiento coincida CreateUri más estrechamente con el análisis de URI en el control WebView2:

Uri_CREATE_ALLOW_IMPLICIT_FILE_SCHEME | Uri_CREATE_NO_DECODE_EXTRA_INFO

Consulte también