std::stringを受け入れるターボモジュールメソッドはJavaScriptのstringを使用してJavaScriptから呼び出すことができ、引数は自動的に変換されます。同様に、std::stringを返すターボモジュールメソッドはJavaScript環境にJavaScriptのstringを返します。それらの一部は、std::stringやint32_tなどのC++の基本型です。その他はVega固有の型で、主にcom::amazon::kepler::turbomodule名前空間の一部として利用できます。
型マップ
次の表は、TypeScript型とそれに対応するC++型とのマッピングを示しています。これはcodegenツールで使用されるマッピングです。 これらの型の中にはTypeScriptの基本型には含まれないものがあり、@amazon-devices/keplerscript-turbomodule-apiからインポートする必要があります。
[1]
int64_tはNumber.MAX_SAFE_INTEGERが原因で精度が失われる可能性があります。精度が求められる大きな整数にはBigIntを使用できます。
[2] 同種配列とは、要素の型が同じ配列です。
[3] BigIntは、直接渡されるメソッドパラメーターおよび戻り値の型として、符号付きおよび符号なし64ビット整数でサポートされています。サポートされている使用方法の詳細については、BigIntを参照してください。
[4] JsonContainerは、JSObjectの欠陥が解消された後、削除される予定です。これを使用する必要がある場合は、@amazon-devices/keplerscript-turbomodule-apiからJsonContainer型を汎用Objectとしてインポートするか、次のようなカスタム型エイリアスを定義できます。
Number.MAX_SAFE_INTEGERよりも大きい整数の場合は、ターボモジュールのパラメーターと戻り値の型として、std::string表現を使用してください。JavaScriptおよびC++の実装では、stringをより適切な型に変換できます。
JSArray
同種(T[])配列には、を使用できます。その他の配列には、JSArrayを使用できます。
JSArrayはstd::vectorで、nullポインター、boolean、さまざまなint、double、float、std::string、JSArray、JSObjectなどの多様な要素の型を受け入れます。したがって、その使用法はstd::vectorと同様です。
例
JSObject
JSObjectはstd::stringのキーを持つstd::mapで、nullポインター、boolean、さまざまなint、double、float、std::string、JSArray、JSObjectなどの多様な値の型を受け入れます。したがって、その使用法はstd::mapと同様です。
JSObjectには、静的なparseJsonメソッドが用意されています。parseJsonメソッドは、std::string型のJSON文字列を受け取り、同等のJSObjectを返します。
例
プロキシJSObjectとJSArray
Vegaターボモジュールは、JSObject型とJSArray型に加えて、プロキシ型であるproxy::JSObjectとproxy::JSArrayをサポートしています。プロキシ型の主な機能の1つは、動的なアクセスと変更です。コピーを作成しなくても、C++コードからJavaScriptオブジェクトや配列の読み取りと書き込みを直接行うことができます。
ただし、これらのプロキシ型を使用する際に留意すべき重要な点がいくつかあります。
- Threadに関する考慮事項: プロキシ型はJSThreadコンテキストとターボモジュールメソッド呼び出しの範囲内で使用する必要があります。これらを保存したり、任意のThreadからアクセスしたりすることはできません。Threadの安全性チェックはデバッグモードでのみ実行されるため、マルチスレッド環境でこれらのプロキシオブジェクトを操作する場合は注意が必要です。
-
ネイティブでの構築
新しいプロキシ項目はネイティブに構築することができます。ただし、必要なJSRuntimeをターボモジュール、またはHostCallbackメソッドからメソッドパラメーターとして取得する必要があります。
警告:デフォルトのコンストラクタは使用しないでください。これらのプロキシ型デフォルトコンストラクタは、
std::tupleやstd::variantなど構造体での現在の内部使用をサポートするためにのみ維持されています。これらのデフォルトコンストラクタには依存しないでください。JSThreadコンテキストを必要とするため、将来のリリースでは削除される予定です。
JSRuntime
JSRuntime型は、JavaScriptランタイム環境を表します。これはネイティブ専用の型で、任意のターボモジュールまたはHostCallbackメソッドによってパラメーターとしてリクエストできます。これは通常、C++で新しいプロキシ項目を作成するために使用されます。
注:JSRuntimeはJSThread以外からは構築できません。
proxy::JSObject
proxy::JSObject型を使用すると、ネイティブコードに渡すことができるJavaScriptオブジェクトを作成し、コピーを作成せずにネイティブ側からそのプロパティとメソッドに動的にアクセスして変更することができます。
注:proxy::JSObjectへのアクセスはJSThreadコンテキストに制限されており、ターボモジュールメソッド呼び出しの範囲内で行う必要があります。Threadの安全性チェックはデバッグモードでのみ実行されます。
proxy::JSArray
proxy::JSArray型を使用すると、ネイティブコードに渡すことができるJavaScript配列を作成し、その要素にネイティブ側から動的にアクセスして変更することができます。
注:proxy::JSArrayへのアクセスはJSThreadコンテキストに制限されており、ターボモジュールメソッド呼び出しの範囲内で行う必要があります。Threadの安全性チェックはデバッグモードでのみ実行されます。
Promise
Promiseは別のスレッドで実行する必要があります。Promiseは、PromiseOperationを入力として使用して作成されます。PromiseOperationは、を受け入れ、voidを返す関数です。
Promiseには、resolveメソッドとrejectメソッドがあります。Promiseは、Errorまたはstd::stringを使用して拒否することができ、型マップに示されている任意のC++ターボモジュール型を使用して解決できます。
例
Callback
コールバックは別のスレッドで実行する必要があります。Callbackオブジェクトはパラメーター値としてのみ使用でき、C++に渡されるJavaScriptコールバックを表します。戻り値の型としてのコールバックについては、HostCallbackを参照してください。
Callbackオブジェクトは、唯一のメソッドとしてinvokeを公開します。このメソッドは、指定された引数でJavaScriptコールバックを呼び出し、結果をC++に返します。
例
HostCallback
HostCallbackは戻り値にのみ指定でき、JavaScript環境にC++コールバックを返すために使用されます。パラメーターの型としてのコールバックについては、Callbackを参照してください。
例
HostCallbackを使用してCallbackを呼び出すこともできます。
ArrayBuffer
ArrayBufferは、汎用、固定長の生バイナリデータバッファーを表します。
例
BigInt
BigIntは整数を表します。JavaScriptでは、Number.MAX_SAFE_INTEGERより大きい整数またはNumber.MIN_SAFE_INTEGERより小さい整数に使用されます。Vegaでは、ターボモジュールは、int64_tおよびuint64_tベースのゲッターメソッドとコンストラクターメソッドを持つBigIntをサポートしています。
BigIntは、メソッドのパラメーターや戻り値、コールバックやPromiseに使用できますが、未加工の値としてのみ使用でき、JSArrayやJSObjectの一部としては使用できません。
JavaScriptのBigIntが大きすぎてVegaターボモジュールのBigInt型では表せない場合(たとえば、int64_tやuint64_tでは表現できない)、Vegaターボモジュールのすべての無効なパラメーターと同様に、アサーションに失敗します。詳細については、「ターボモジュールに関する高度なトピック」のエラー処理を参照してください。
utils::json::JsonContainer
JSObject型としてのJsonContainerの使用は置き換えられていますが、現時点ではまだいくつかの機能上のギャップがあります。サポートされている型の完全なリストについては、型マップを参照してください。
例
NativeObject
ネイティブコードからJavaScriptにデータを渡すときに、ほとんどの場合、JSONContainerまたはJSObjectで十分です。ただし、JavaScriptからメソッドを呼び出すことができるネイティブオブジェクトが必要な場合は、com::amazon::kepler::turbomodule::NativeObjectを実装するオブジェクトを作成する必要があります。
例

