如何在 JavaScript 中表示 WinRT 类型和成员

下面介绍如何从 WebView2 应用中的 Web 端 JavaScript 代码中使用 WinRT 类型和成员（从 Web 端代码调用本机 WinRT 代码）。

语言等效项

webView2 WinRT JS 投影工具 (wv2winrt) 从 WinRT 转换为 JavaScript 语言构造，如下所示。

WinRT 语言构造	JavaScript 表示形式	注释
UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double	Number
Char, String	String	JavaScript String 实例将转换为 WinRT String 实例。
Boolean	Boolean
Windows.Foundation.DateTime 结构	Date
Windows.Foundation.TimeSpan 结构	Number
Guid	String	包含 UUID (的字符串表示形式的 JavaScript String 实例（无论是否带有分隔符 { 和 } 大括号) ）将转换为相应的 UUID。 UUID 转换为其字符串表示形式，开头和结尾处有分隔符 { 和 } 大括号字符。 有关 UUID 的信息，请参阅 RFC 4122。
IVector<T>, IVectorView<T>, IObservableVector<T>	Array 和 JavaScript 对象	如果实例 RuntimeClass 实现 vector 接口，则它在 JavaScript 中表示为下面所述的常用对象，但也将充当 JavaScript 数组。 读取和写入是在基础 WinRT 矢量对象上实时执行的。
IMap<K,V>, IMapView<K,V>, IObservableMap<K,V>	JavaScript 对象	如果实例 RuntimeClass 实现 map 接口，则它在 JavaScript 中表示为下面所述的常用对象，但也具有具有来自基础 WinRT 映射对象的名称和值的属性。 读取和写入是在基础 WinRT 映射对象上实时执行的。
Enum	JavaScript 对象	枚举类型表示为 JavaScript 对象。 每个枚举值都是 JavaScript 对象上的属性 Number 。
Struct	JavaScript 对象	类型 Struct 转换为具有对应于类型成员名称的属性名称的 Struct JavaScript 对象。 这是一种双向转换。
Namespace	JavaScript 对象	命名空间表示为 JavaScript 对象，该对象具有任何子命名空间、枚举类型或 RuntimeClass的属性。 命名空间可能有 0 个、1 个或多个子命名空间、枚举或运行时类，每个单独的子命名空间、枚举和运行时类获取其自己的属性。
Class	JavaScript 对象	类 RuntimeClass 转换为具有相同方法、属性和事件的 JavaScript 对象。
Interface	JavaScript 对象	接口 RuntimeClass 转换为具有相同方法、属性和事件的 JavaScript 对象。 不支持在 JavaScript 中实现接口。
类静态成员	JavaScript 对象属性	请参阅下文。
类构造函数	JavaScript 构造函数和函数	请参阅下文。

将 JavaScript 对象传递给宿主对象时：

• 如果需要将 JavaScript Date 对象作为 VT_DATE传递给宿主对象，请将主机对象的 shouldSerializeDates 属性设置为 true。 默认情况下，Date通过使用 将对象作为 stringJSON.stringify传递到主机。
• 如果需要将 JavaScript 类型化数组作为 array传递给宿主对象，请将主机对象的 shouldPassTypedArraysAsArrays 属性设置为 true。 默认情况下，类型化数组作为 IDispatch传递给主机。

另请参阅：

• Microsoft 接口定义语言 3.0 简介

类静态成员

具有静态属性、静态方法或静态事件的运行时类表示为 命名空间的属性。 每个静态属性、静态方法和静态事件都表示为运行时类的 JavaScript 对象上的属性。

例如，对于 WinRT API 静态方法 Windows.Foundation.Uri.EscapeComponent：

• Windows.Foundation 是 命名空间。
• Uri 是运行时类。
• EscapeComponent 是静态方法。

在 JavaScript 中，表示形式类似： chrome.webview.hostObjects.Windows.Foundation.Uri.EscapeComponent：

• EscapeComponent 是一个 JavaScript 方法，它是运行时类的 JavaScript 对象 Uri 上的属性。
• Uri运行时类是命名空间的 JavaScript 对象Foundation上的属性。

例如，若要调用静态方法 Windows.Foundation.Uri.EscapeComponent，请调用：

`chrome.webview.hostObjects.Windows.Foundation.Uri.EscapeComponent("example");`

此处的 JavaScript 命名空间对象是 chrome.webview.hostObjects.Windows.Foundation。

类构造函数

类的 RuntimeClass 构造函数表示为 JavaScript 对象上的单个属性，可通过两种方式调用：

• 作为 JavaScript 命名空间对象的构造函数。
• 作为 JavaScript 命名空间对象上的函数。

例如，若要创建新 Windows.Foundation.Uri 对象，可以使用 将其作为构造函数 new调用：

`let uri = new chrome.webview.hostObjects.Windows.Foundation.Uri("https://example.com/");`

或者，将它作为函数调用，而不使用 new：

`let uri = chrome.webview.hostObjects.Windows.Foundation.Uri("https://example.com/");`

此处的 JavaScript 命名空间对象是 chrome.webview.hostObjects.Windows.Foundation。

方法重载

如果 WinRT 方法名称为多个方法重载，则从 JavaScript 调用该方法名称将调用具有匹配参数数的重载。

如果有多个重载具有匹配数量的参数，则会调用元数据中找到的第一个重载。

方法输出参数

如果 WinRT 方法具有 out 参数，则从 JavaScript 调用该方法时，返回的结果将是一个 JavaScript 对象，该对象是每个 out 参数的属性。 如果方法具有非void 返回类型，则返回的结果对象也将具有名为 value 的属性，该属性包含方法的返回值。

调用具有 out 参数的 WinRT 方法时，除非它们是数组类型) ，否则将在方法调用 (的参数列表中跳过任何 out 参数。 例如，假设使用 MIDL3 定义具有 out 参数和非void 返回类型的 WinRT 方法，如下所示：

String MethodWithOutParams(String stringParam1, 
                           out Int32 intParam2, 
                           out Int32 intParam3, 
                           String stringParam4);

从 JavaScript 调用该方法时，请省略 out 参数：

let result = object.MethodWithOutParams("stringParam1", 
                                        "stringParam4");

然后，若要读取 WinRT 方法的返回值，请读取 value JavaScript result 对象上的 属性。 若要读取 WinRT 方法 out 的参数，请读取 JavaScript result 对象上相应的命名属性：

console.assert(result.value == "return value");

console.assert(result.intParam2 == 1);

console.assert(result.intParam3 == 2);

对于数组类型 out 参数，调用 方法时，需要将数组传递到方法的参数列表中。 对于非void 返回类型，结果数组将替换为方法调用传入的数组。 void对于返回类型，结果数组将是方法调用的结果。

// Both methods update input array values to index values
String NonVoidMethodWithArrayOutParam(out Int[] intArrayParam);

Void VoidMethodWithArrayOutParam(out Int[] intArrayParam);

let input_array1 = [0, 0, 0];

let result1 = object.NonVoidMethodWithArrayOutParam(input_array1);

console.assert(input_array1 == [0, 1, 2])

let input_array2 = [0, 0, 0];

let result2 = object.VoidMethodWithArrayOutParam(input_array2);

console.assert(result2 == [0, 1, 2]);

如果将类型化数组作为数组 out 参数传递， chrome.webview.hostObjects.options.shouldPassTypedArraysAsArrays 则需要将 设置为 true。

另请参阅：

• 有关 C++ WinRT 中的 WebView2 SDK 和 Windows 应用 SDK (WinUI3) 的问题 #2788

另请参阅

• 从 Web 端代码调用本机 WinRT 代码
• Microsoft 接口定义语言 3.0 简介