Win32 C++ WebView2 API 慣例

支援平台:Win32。

必要條件

  • 使用 Win32 API 的經驗。

非同步方法

WebView2 Win32 C++ API 中的非同步方法會使用代理介面來聯絡您,原因如下:

  • 非同步方法已完成。
  • 成功或失敗的密碼。
  • 這是非同步方法的結果。

所有非同步方法的最後一個參數是指向代理介面的指標,你提供該介面的實作。

代理介面僅有一個 Invoke 方法,將成功或失敗代碼的第一個參數 an HRESULT 作為參考。 此外,如果方法有結果,也可能有第二個參數是該方法的結果。

例如, ICoreWebView2::CapturePreview 方法 ICoreWebView2CapturePreviewCompletedHandler 以指標作為最後參數。 要發送 CapturePreview 方法請求,你必須提供你實作的 ICoreWebView2CapturePreviewCompletedHandler 指標實例。

以下程式碼使用此 Invoke 方法實作指標 ICoreWebView2CapturePreviewCompletedHandler :

HRESULT Invoke(HRESULT result)

你先實作Invoke方法,CoreWebView2然後在請求完成後CapturePreview請求你的Invoke方法。 單一參數是 HRESULT 描述請求成功 CapturePreview 或失敗代碼的部分。

或者,對於 ICoreWebView2::ExecuteScript,你提供一個實例,該實例擁有 Invoke 一個方法,能提供請求的 ExecuteScript 成功或失敗代碼。 也請提供第二個參數,也就是執行腳本後的 JSON。

你可以手動實作 CompleteHandler 代理介面,或者使用 WRL) (回調函 式。 WRL) (回調函式在以下 WebView2 程式碼中使用:

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

Events

WebView2 Win32 C++ API 中的事件使用 add_EventName and remove_EventName 方法對來訂閱與取消訂閱事件。 此 add_EventName 方法會使用事件處理代理介面,並以一個憑證作為輸出參數回傳 EventRegistrationToken 。 此方法會 remove_EventName 取 EventRegistrationToken 出一個代幣並取消訂閱相應的事件訂閱。

事件處理代理介面

事件處理代理介面的運作方式類似於非同步方法完成的處理程序代理介面。 你實作事件處理代理介面,並在 CoreWebView2 事件執行時發送回調。

每個事件處理代理介面都有一個 Invoke 方法,該方法包含一個發送者參數,後接一個事件 args 參數。 發送者是你訂閱事件的物件實例。 事件 args 參數是一個介面,包含當前觸發事件的資訊。

例如,NavigationCompleted事件 上的 ICoreWebView2 和 方法ICoreWebView2::add_NavigationCompletedICoreWebView2::remove_NavigationCompleted對。 當你發送請求時,你提供一個你先前實作Invoke過方法的實例ICoreWebView2NavigationCompletedEventHandler。

當事件執行時 NavigationCompleted ,會要求你的 Invoke 方法:

  • 第一個參數執行事件 NavigationCompleted 。
  • 第二個參數包含導航是否成功完成等資訊。

類似於非同步方法完成的處理器代理介面,請使用以下其中一個動作來設定:

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

字串

字串輸出參數為 LPWSTR 空終端字串。 請求者會用 提供字 CoTaskMemAlloc串。 所有權轉移給請求者,請求者需使用 CoTaskMemFree。

字串輸入參數為 LPCWSTR 空終止字串。 請求方確保該字串在同步函式請求期間有效。 如果接收端必須在函式請求完成後某個時間點儲存該值,接收端必須提供該字串值的相關副本。

URI 與 JSON 解析

各種方法提供或接受 URI 和 JSON 作為字串。 用你喜歡的函式庫來解析和產生字串。

如果你的應用程式有 WinRT,你可以用 and IJsonObjectStatics 方法來解析或產生 JSON 字串,或RuntimeClass_Windows_Foundation_Uri用 RuntimeClass_Windows_Data_Json_JsonObject 方法 IUriRuntimeClassFactory 來解析並產生 URI。 這兩種方法在 Win32 應用程式中都適用。

如果你使用 IUri 並 CreateUri 來解析 URI,建議使用以下 URI 建立標誌,讓 CreateUri 行為更接近 WebView2 控制項中的 URI 解析:

Uri_CREATE_ALLOW_IMPLICIT_FILE_SCHEME | Uri_CREATE_NO_DECODE_EXTRA_INFO

另請參閱