Conventions de l’API WebView2 Win32 C++

Plateformes prises en charge : Win32.

Configuration requise

  • Expérience de l’utilisation de l’API Win32.

Méthodes asynchrones

Les méthodes asynchrones dans l’API WebView2 Win32 C++ utilisent une interface de délégué pour vous contacter pour l’une des raisons suivantes :

  • La méthode async est terminée.
  • Code de réussite ou d’échec.
  • Résultat de la méthode asynchrone.

Le dernier paramètre pour toutes les méthodes asynchrones est un pointeur vers une interface déléguée, dont vous fournissez une implémentation.

L’interface déléguée a une méthode unique Invoke qui prend comme premier paramètre un HRESULT du code de réussite ou d’échec. En outre, il peut y avoir un deuxième paramètre qui est le résultat de la méthode, si la méthode a un résultat.

Par exemple, la méthode ICoreWebView2 ::CapturePreview prend un ICoreWebView2CapturePreviewCompletedHandler pointeur comme paramètre final. Pour envoyer une CapturePreview demande de méthode, vous fournissez un instance du ICoreWebView2CapturePreviewCompletedHandler pointeur que vous implémentez.

Le code suivant utilise la Invoke méthode pour implémenter un ICoreWebView2CapturePreviewCompletedHandler pointeur :

HRESULT Invoke(HRESULT result)

Vous implémentez la Invoke méthode, puis CoreWebView2 vous demandez votre Invoke méthode une fois la CapturePreview requête terminée. Le paramètre unique est le HRESULT qui décrit le code de réussite ou d’échec de la CapturePreview demande.

Sinon, pour ICoreWebView2::ExecuteScript, vous fournissez un instance qui a une Invoke méthode qui vous fournit le code de réussite ou d’échec de la ExecuteScript demande. Fournissez également le deuxième paramètre, qui est le JSON du résultat de l’exécution du script.

Vous pouvez implémenter manuellement les CompleteHandler interfaces déléguées ou utiliser la fonction de rappel (WRL). La fonction de rappel (WRL) est utilisée dans le code WebView2 suivant :

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());
    }
}

Événements

Les événements dans l’API WebView2 Win32 C++ utilisent la add_EventName paire de méthodes et remove_EventName pour s’abonner et se désabonner des événements. La add_EventName méthode prend une interface de délégué de gestionnaire d’événements et renvoie un EventRegistrationToken jeton en tant que paramètre de sortie. La remove_EventName méthode prend un EventRegistrationToken jeton et annule l’abonnement aux événements correspondant.

Interfaces déléguées du gestionnaire d’événements

Les interfaces de délégué du gestionnaire d’événements fonctionnent de la même façon que les interfaces de délégué de gestionnaire terminées par la méthode asynchrone. Vous implémentez l’interface de délégué du gestionnaire d’événements et CoreWebView2 envoyez un rappel chaque fois que l’événement s’exécute.

Chaque interface de délégué de gestionnaire d’événements a une méthode unique Invoke qui a un paramètre d’expéditeur suivi d’un paramètre event args. L’expéditeur est le instance de l’objet sur lequel vous vous êtes abonné aux événements. Le paramètre event args est une interface qui contient des informations sur l’événement en cours de déclenchement.

Par instance, l’événement NavigationCompleted sur ICoreWebView2 a la ICoreWebView2::add_NavigationCompleted paire de méthodes et ICoreWebView2::remove_NavigationCompleted . Lorsque vous envoyez une requête, vous fournissez un instance de dans lequel vous avez implémenté Invoke précédemment la ICoreWebView2NavigationCompletedEventHandler méthode .

Lorsque l’événement NavigationCompleted s’exécute, votre Invoke méthode est demandée :

  • Le premier paramètre exécute l’événement NavigationCompleted .
  • Le deuxième paramètre contient des informations sur la réussite de la navigation, etc.

À l’instar de l’interface de délégué de gestionnaire terminée par la méthode asynchrone, utilisez l’une des actions suivantes pour la configurer :

// 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));

Chaînes

Les paramètres de sortie de chaîne sont LPWSTR des chaînes terminées par un caractère Null. Le demandeur fournit la chaîne à l’aide de CoTaskMemAlloc. La propriété est transférée au demandeur et il appartient au demandeur de libérer la mémoire à l’aide CoTaskMemFreede .

Les paramètres d’entrée de chaîne sont LPCWSTR des chaînes terminées par null. Le demandeur garantit que la chaîne est valide pendant la durée de la demande de fonction synchrone. Si le récepteur doit stocker la valeur à un moment donné une fois la demande de fonction terminée, le récepteur doit fournir une copie associée de la valeur de chaîne.

Analyse URI et JSON

Différentes méthodes fournissent ou acceptent des URI et JSON en tant que chaînes. Utilisez votre bibliothèque préférée pour analyser et générer les chaînes.

Si WinRT est disponible pour votre application, vous pouvez utiliser les RuntimeClass_Windows_Data_Json_JsonObject méthodes et IJsonObjectStatics pour analyser ou produire des chaînes JSON, ou RuntimeClass_Windows_Foundation_Uri des méthodes et IUriRuntimeClassFactory pour analyser et produire des URI. Ces deux approches fonctionnent dans les applications Win32.

Si vous utilisez IUri et CreateUri pour analyser les URI, vous pouvez utiliser les indicateurs de création d’URI suivants, pour que CreateUri le comportement corresponde davantage à l’analyse d’URI dans le contrôle WebView2 :

Uri_CREATE_ALLOW_IMPLICIT_FILE_SCHEME | Uri_CREATE_NO_DECODE_EXTRA_INFO

Voir aussi