webview.yml

### YamlMime:TSType
name: WebView
uid: 'WebView2Script!WebView:class'
package: WebView2Script!
fullName: WebView
summary: >-
  `window.chrome.webview` is the class to access the WebView2-specific APIs that are available to the script running
  within WebView2 Runtime.
remarks: ''
isPreview: false
isDeprecated: false
type: class
properties:
  - name: hostObjects
    uid: 'WebView2Script!WebView#hostObjects:member'
    package: WebView2Script!
    fullName: hostObjects
    summary: >-
      Contains asynchronous proxies for all host objects added via `CoreWebView2.AddHostObjectToScript` as well as
      options to configure those proxies, and the container for synchronous proxies.


      If you call `coreWebView2.AddHostObjectToScript("myObject", object);` in your native code, an asynchronous proxy
      for `object` is available to your web-side code, by using `chrome.webview.hostObjects.myObject`.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'hostObjects: HostObjectsAsyncRoot;'
      return:
        type: '<xref uid="WebView2Script!HostObjectsAsyncRoot:class" />'
        description: >-


          #### Examples



          For example, suppose you have a COM object with the following interface:


          ```

          [uuid(3a14c9c0-bc3e-453f-a314-4ce4a0ec81d8), object, local]

          interface IHostObjectSample : IUnknown

          {
              // Demonstrate basic method call with some parameters and a return value.
              HRESULT MethodWithParametersAndReturnValue([in] BSTR stringParameter, [in] INT integerParameter, [out, retval] BSTR* stringResult);

              // Demonstrate getting and setting a property.
              [propget] HRESULT Property([out, retval] BSTR* stringResult);
              [propput] HRESULT Property([in] BSTR stringValue);

              [propget] HRESULT IndexedProperty(INT index, [out, retval] BSTR * stringResult);
              [propput] HRESULT IndexedProperty(INT index, [in] BSTR stringValue);

              // Demonstrate native calling back into JavaScript.
              HRESULT CallCallbackAsynchronously([in] IDispatch* callbackParameter);

              // Demonstrate a property which uses Date types
              [propget] HRESULT DateProperty([out, retval] DATE * dateResult);
              [propput] HRESULT DateProperty([in] DATE dateValue);

              // Creates a date object on the native side and sets the DateProperty to it.
              HRESULT CreateNativeDate();
          };

          ```


          Add an instance of this interface into your JavaScript with `AddHostObjectToScript`. In this case, name it
          `sample`.


          In the native host app code:


          ```cpp

          VARIANT remoteObjectAsVariant = {};

          m_hostObject.query_to<IDispatch>(&remoteObjectAsVariant.pdispVal);

          remoteObjectAsVariant.vt = VT_DISPATCH;


          // We can call AddHostObjectToScript multiple times in a row without
          // calling RemoveHostObject first. This will replace the previous object
          // with the new object. In our case, this is the same object, and everything
          // is fine.

          CHECK_FAILURE(
              m_webView->AddHostObjectToScript(L"sample", &remoteObjectAsVariant));
          remoteObjectAsVariant.pdispVal->Release();

          ```


          In the HTML document, use the COM object using `chrome.webview.hostObjects.sample`.


          ```html

          document.getElementById("getPropertyAsyncButton").addEventListener("click", async () => {
              const propertyValue = await chrome.webview.hostObjects.sample.property;
              document.getElementById("getPropertyAsyncOutput").textContent = propertyValue;
          });


          document.getElementById("getPropertySyncButton").addEventListener("click", () => {
              const propertyValue = chrome.webview.hostObjects.sync.sample.property;
              document.getElementById("getPropertySyncOutput").textContent = propertyValue;
          });


          document.getElementById("setPropertyAsyncButton").addEventListener("click", async () => {
              const propertyValue = document.getElementById("setPropertyAsyncInput").value;
              // The following line will work but it will return immediately before the property value has actually been set.
              // If you need to set the property and wait for the property to change value, use the setHostProperty function.
              chrome.webview.hostObjects.sample.property = propertyValue;
              document.getElementById("setPropertyAsyncOutput").textContent = "Set";
          });


          document.getElementById("setPropertyExplicitAsyncButton").addEventListener("click", async () => {
              const propertyValue = document.getElementById("setPropertyExplicitAsyncInput").value;
              // If you care about waiting until the property has actually changed value, use the setHostProperty function.
              await chrome.webview.hostObjects.sample.setHostProperty("property", propertyValue);
              document.getElementById("setPropertyExplicitAsyncOutput").textContent = "Set";
          });


          document.getElementById("setPropertySyncButton").addEventListener("click", () => {
              const propertyValue = document.getElementById("setPropertySyncInput").value;
              chrome.webview.hostObjects.sync.sample.property = propertyValue;
              document.getElementById("setPropertySyncOutput").textContent = "Set";
          });


          document.getElementById("getIndexedPropertyAsyncButton").addEventListener("click", async () => {
              const index = parseInt(document.getElementById("getIndexedPropertyAsyncParam").value);
              const resultValue = await chrome.webview.hostObjects.sample.IndexedProperty[index];
              document.getElementById("getIndexedPropertyAsyncOutput").textContent = resultValue;
          });

          document.getElementById("setIndexedPropertyAsyncButton").addEventListener("click", async () => {
              const index = parseInt(document.getElementById("setIndexedPropertyAsyncParam1").value);
              const value = document.getElementById("setIndexedPropertyAsyncParam2").value;;
              chrome.webview.hostObjects.sample.IndexedProperty[index] = value;
              document.getElementById("setIndexedPropertyAsyncOutput").textContent = "Set";
          });

          document.getElementById("invokeMethodAsyncButton").addEventListener("click", async () => {
              const paramValue1 = document.getElementById("invokeMethodAsyncParam1").value;
              const paramValue2 = parseInt(document.getElementById("invokeMethodAsyncParam2").value);
              const resultValue = await chrome.webview.hostObjects.sample.MethodWithParametersAndReturnValue(paramValue1, paramValue2);
              document.getElementById("invokeMethodAsyncOutput").textContent = resultValue;
          });


          document.getElementById("invokeMethodSyncButton").addEventListener("click", () => {
              const paramValue1 = document.getElementById("invokeMethodSyncParam1").value;
              const paramValue2 = parseInt(document.getElementById("invokeMethodSyncParam2").value);
              const resultValue = chrome.webview.hostObjects.sync.sample.MethodWithParametersAndReturnValue(paramValue1, paramValue2);
              document.getElementById("invokeMethodSyncOutput").textContent = resultValue;
          });


          let callbackCount = 0;

          document.getElementById("invokeCallbackButton").addEventListener("click", async () => {
              chrome.webview.hostObjects.sample.CallCallbackAsynchronously(() => {
                  document.getElementById("invokeCallbackOutput").textContent = "Native object called the callback " + (++callbackCount) + " time(s).";
              });
          });


          // Date property

          document.getElementById("setDateButton").addEventListener("click", () => {
              chrome.webview.hostObjects.options.shouldSerializeDates = true;
              chrome.webview.hostObjects.sync.sample.dateProperty = new Date();
              document.getElementById("dateOutput").textContent = "sample.dateProperty: " + chrome.webview.hostObjects.sync.sample.dateProperty;
          });

          document.getElementById("createRemoteDateButton").addEventListener("click", () => {
              chrome.webview.hostObjects.sync.sample.createNativeDate();
              document.getElementById("dateOutput").textContent = "sample.dateProperty: " + chrome.webview.hostObjects.sync.sample.dateProperty;
          });

          ```
methods:
  - name: 'addEventListener(type, listener, options)'
    uid: 'WebView2Script!WebView#addEventListener:member(2)'
    package: WebView2Script!
    fullName: 'addEventListener(type, listener, options)'
    summary: >-
      The standard `EventTarget.addEventListener` method. Use it to subscribe to the `message` event or
      `sharedbufferreceived` event. The `message` event receives messages posted from the WebView2 host via
      `CoreWebView2.PostWebMessageAsJson` or `CoreWebView2.PostWebMessageAsString`<!-- -->. The `sharedbufferreceived`
      event receives shared buffers posted from the WebView2 host via `CoreWebView2.PostSharedBufferToScript`<!-- -->.

      See CoreWebView2.PostWebMessageAsJson(
      [Win32/C++](https://learn.microsoft.com/microsoft-edge/webview2/reference/win32/icorewebview2#postwebmessageasjson)<!--
      -->,
      [.NET](https://learn.microsoft.com/dotnet/api/microsoft.web.webview2.core.corewebview2.postwebmessageasjson)<!--
      -->,
      [WinRT](https://learn.microsoft.com/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2#postwebmessageasjson)<!--
      -->).
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean |
        AddEventListenerOptions): void;
      parameters:
        - id: type
          description: >-
            The name of the event to subscribe to. Valid values are `message`<!-- -->, and `sharedbufferreceived`<!--
            -->.
          type: string
        - id: listener
          description: The callback to invoke when the event is raised.
          type: EventListenerOrEventListenerObject
        - id: options
          description: Options to control how the event is handled.
          type: boolean | AddEventListenerOptions
      return:
        type: void
        description: ''
  - name: postMessage(message)
    uid: 'WebView2Script!WebView#postMessage:member(1)'
    package: WebView2Script!
    fullName: postMessage(message)
    summary: >-
      When the page calls `postMessage`<!-- -->, the `message` parameter is converted to JSON and is posted
      asynchronously to the WebView2 host process. This will result in either the `CoreWebView2.WebMessageReceived`
      event or the `CoreWebView2Frame.WebMessageReceived` event being raised, depending on if `postMessage` is called
      from the top-level document in the WebView2 or from a child frame. See CoreWebView2.WebMessageReceived(
      [Win32/C++](https://learn.microsoft.com/microsoft-edge/webview2/reference/win32/icorewebview2#add_webmessagereceived)<!--
      -->,
      [.NET](https://learn.microsoft.com/dotnet/api/microsoft.web.webview2.core.corewebview2.webmessagereceived)<!--
      -->,
      [WinRT](https://learn.microsoft.com/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2#webmessagereceived)<!--
      -->). See CoreWebView2Frame.WebMessageReceived(
      [Win32/C++](https://learn.microsoft.com/microsoft-edge/webview2/reference/win32/icorewebview2frame2#add_webmessagereceived)<!--
      -->,
      [.NET](https://learn.microsoft.com/dotnet/api/microsoft.web.webview2.core.corewebview2frame.webmessagereceived)<!--
      -->,
      [WinRT](https://learn.microsoft.com/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2frame#webmessagereceived)<!--
      -->).
    remarks: |-
        #### Examples

        Post a message to the `CoreWebView2`:

        ```javascript
        const inTopLevelFrame = (window === window.parent);
        if (inTopLevelFrame) {
            // The message can be any JSON serializable object.
            window.chrome.webview.postMessage({
                myMessage: 'Hello from the script!',
                otherValue: 1}
            );
            // A simple string is an example of a JSON serializable object.
            window.chrome.webview.postMessage("example");
        }
        ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'postMessage(message: any) : void;'
      parameters:
        - id: message
          description: The message to send to the WebView2 host. This can be any object that can be serialized to JSON.
          type: any
      return:
        type: void
        description: ''
  - name: 'postMessageWithAdditionalObjects(message, additionalObjects)'
    uid: 'WebView2Script!WebView#postMessageWithAdditionalObjects:member(1)'
    package: WebView2Script!
    fullName: 'postMessageWithAdditionalObjects(message, additionalObjects)'
    summary: >-
      When the page calls `postMessageWithAdditionalObjects`<!-- -->, the `message` parameter is sent to WebView2 in the
      same fashion as 'postMessage'. Objects passed as 'additionalObjects' are converted to their native types and will
      be available in the `CoreWebView2WebMessageReceivedEventArgs.AdditionalObjects` property.
    remarks: |-
      #### Examples

      Post a message that includes File objects from an input element to the CoreWebView2:

      ```javascript
      const input = document.getElementById('files');
      input.addEventListener('change', function() {
          // Note that postMessageWithAdditionalObjects does not accept a single object,
          // but only accepts an ArrayLike object.
          // However, input.files is type FileList, which is already an ArrayLike object so
          // no conversion to array is needed.
          const currentFiles = input.files;
          chrome.webview.postMessageWithAdditionalObjects("FilesDropped",
              currentFiles);
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'postMessageWithAdditionalObjects(message: any, additionalObjects: ArrayLike<any>) : void;'
      parameters:
        - id: message
          description: The message to send to the WebView2 host. This can be any object that can be serialized to JSON.
          type: any
        - id: additionalObjects
          description: |-
            A sequence of DOM objects that have native representations in WebView2. This parameter needs to be
            ArrayLike. The following DOM types are mapped to native:

            DOM      | Win32       | .NET     | WinRT
            -------- | ------------|----------| --------
            [File](https://developer.mozilla.org/docs/Web/API/File) | ICoreWebView2File | [System.IO.FileInfo](https://learn.microsoft.com/dotnet/api/system.io.fileinfo) | [Windows.Storage.StorageFile](https://learn.microsoft.com/uwp/api/windows.storage.storagefile)

            `null` or `undefined` entries will be passed as `null` type in WebView2. Otherwise if an invalid or
            unsupported object is passed via this API, an exception will be thrown and the message will fail to post.
          type: ArrayLike&lt;any&gt;
      return:
        type: void
        description: ''
  - name: releaseBuffer(buffer)
    uid: 'WebView2Script!WebView#releaseBuffer:member(1)'
    package: WebView2Script!
    fullName: releaseBuffer(buffer)
    summary: >-
      Call with the `ArrayBuffer` from the `chrome.webview.sharedbufferreceived` event to release the underlying shared
      memory resource.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'releaseBuffer(buffer: ArrayBuffer): void;'
      parameters:
        - id: buffer
          description: An `ArrayBuffer` from the `chrome.webview.sharedbufferreceived` event.
          type: ArrayBuffer
      return:
        type: void
        description: ''
  - name: 'removeEventListener(type, listener, options)'
    uid: 'WebView2Script!WebView#removeEventListener:member(2)'
    package: WebView2Script!
    fullName: 'removeEventListener(type, listener, options)'
    summary: >-
      The standard `EventTarget.removeEventListener` method. Use it to unsubscribe to the `message` or
      `sharedbufferreceived` event.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean |
        EventListenerOptions): void;
      parameters:
        - id: type
          description: The name of the event to unsubscribe from. Valid values are `message` and `sharedbufferreceived`<!-- -->.
          type: string
        - id: listener
          description: The callback to remove from the event.
          type: EventListenerOrEventListenerObject
        - id: options
          description: Options to control how the event is handled.
          type: boolean | EventListenerOptions
      return:
        type: void
        description: ''
extends: <a href="https://developer.mozilla.org/docs/Web/API/EventTarget">EventTarget</a>