共用方式為

如何以 JavaScript 表示 WinRT 類型和成員

  • 發行項

以下是從 WebView2 應用程式呼叫原生端 WinRT 程式代碼時，如何在 WebView2 應用程式的 Web 端 JavaScript 程式代碼中使用 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物件表示。 每個列舉值都是 Number JavaScript 物件上的屬性。
Struct JavaScript 物件 Struct類型會轉換成具有對應至類型成員名稱之屬性名稱的 Struct JavaScript 物件。 這是雙向轉換。
Namespace JavaScript 物件 命名空間會以 JavaScript 物件表示，該物件具有任何子命名空間、列舉類型或 RuntimeClass的屬性。 命名空間可能有 0、1 或多個子命名空間、列舉或 Runtimeclass，而每個個別的子命名空間、列舉和 runtimeclass 都會取得自己的屬性。
Class JavaScript 物件 類別 RuntimeClass 會轉換成具有相同方法、屬性和事件的 JavaScript 物件。
Interface JavaScript 物件 RuntimeClass介面會轉換成具有相同方法、屬性和事件的 JavaScript 物件。 不支援在 JavaScript 中實作介面。
類別靜態成員 JavaScript 物件屬性 請參閱下方。
類別建構函式 JavaScript 建構函式和函式 請參閱下方。

將 JavaScript 物件傳遞至主機物件時：

  • 如果 JavaScript Date 物件需要以 形式傳遞至主物件 VT_DATE，請將主機物件的 shouldSerializeDates 屬性設定為 true。 根據預設，Date物件會使用 JSON.stringify，以形式傳遞至主機string。
  • 如果 JavaScript 具類型的陣列需要傳遞至主物件做為 array，請將主機物件的 shouldPassTypedArraysAsArrays 屬性設定為 true。 根據預設，具類型的陣列會以 傳遞至主機。IDispatch

另請參閱:

類別靜態成員

具有靜態屬性、靜態方法或靜態事件的運行時間類別會表示為命名空間的屬性。 每個靜態屬性、靜態方法和靜態事件都會以 Runtimeclass 的 JavaScript 物件上的屬性表示。

例如，針對 WinRT API 靜態方法 Windows.Foundation.Uri.EscapeComponent：

  • Windows.Foundation 是命名空間。
  • Uri 是 runtimeclass。
  • EscapeComponent 是靜態方法。

在 JavaScript 中，表示法看起來類似：： chrome.webview.hostObjects.Windows.Foundation.Uri.EscapeComponent

  • EscapeComponent 是 JavaScript 方法，它是 Runtimeclass 的 JavaScript 物件 Uri 上的屬性。
  • runtimeclass 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 參數。 例如，假設具有參數和非傳回型別的void WinRT 方法out定義如下，使用 MIDL3：

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。

另請參閱:

另請參閱