ScriptMediator: callJavaScriptFunction()

JavaScript側で登録された関数を呼び出し、その結果を取得します。

構文

suspend ScriptMediator.callJavaScriptFunction(functionName, args): Any?
suspend ScriptMediator.callJavaScriptFunction(dispose, handle, args): Any?
ScriptMediator.callJavaScriptFunction(functionName, args, completionHandler): Unit
ScriptMediator.callJavaScriptFunction(dispose, handle, args, completionHandler): Unit
ScriptMediator.callJavaScriptFunction(functionName, args) throws async -> Any?
ScriptMediator.callJavaScriptFunction(dispose, handle, args) throws async -> Any?
ScriptMediator.callJavaScriptFunction(functionName, args, completionHandler) throws -> Void
ScriptMediator.callJavaScriptFunction(dispose, handle, args, completionHandler) throws -> Void

引数

  • functionName: String

    呼び出す対象の、JavaScript側で登録した関数の名前です。

    関数名として、JavaScript側で Alier.registerFunction() で登録した関数の名前を指定します。

  • args: Array<out Any?>

    指定した関数へ渡す引数の配列です。

  • completionHandler: ((Any?) -> Unit)? （省略可）

    指定した関数の呼び出しが完了した後に呼び出されるコールバック関数です。 コールバック関数の引数として、JavaScriptの関数の返値が与えられます。

    null を指定した場合、何も行いません。

    この引数の指定は任意です。指定がない場合、この関数は suspend 関数として実行されます。

    suspend 関数の実行
    • suspend 関数の呼び出しは suspend 関数の定義部にのみ書けます。 通常の（suspend でない）関数から suspend 関数を実行するには、コルーチンビルダー（suspend 関数を受け取り Job を生成する関数）を使います。 詳細は Kotlin Documentation, Coroutines basics を参照してください。

  • dispose: Boolean

    呼び出した関数の登録を破棄するかを指定します。 true なら破棄し、そうでないなら破棄しません。

    この引数は引数 handle とともに指定します。 引数 functionName を使う場合には使用しません。

  • handle: HandleObject

    呼び出す関数のハンドルオブジェクトです。

    この引数は引数 dispose とともに指定します。 引数 functionName を使う場合には使用しません。

  • functionName: String

    呼び出す対象の、JavaScript側で登録した関数の名前です。

    関数名として、JavaScript側で Alier.registerFunction() で登録した関数の名前を指定します。

  • args: [Any?]

    指定した関数へ渡す引数の配列です。

  • completionHandler: ((Any?) -> Void)? （省略可）

    指定した関数の呼び出しが完了した後に呼び出されるコールバック関数です。 コールバック関数の引数として、JavaScript関数の返値が与えられます。

    nil を指定した場合、何も行いません。

    この引数の指定は任意です。指定がない場合、この関数は async 関数として実行されます。 async 関数は iOS 15 以上でのみサポートされています。

    async 関数の実行
    • async 関数の呼び出しは、async 関数の定義部かアプリケーションのエントリポイントとなる（つまりトップレベルの）関数の定義部にのみ書けます（エントリポイントは @main 属性の与えられたデータ型が持つ static main() 関数として定義します）。 通常の（async でない）関数から async 関数を実行するには、Task を使います。 詳細は The Swift Programming Language, Concurrency, The Swift Programming Language, Attributes を参照してください。

  • dispose: Bool

    呼び出した関数の登録を破棄するかを指定します。 true なら破棄し、そうでないなら破棄しません。

    この引数は引数 handle とともに指定します。 引数 functionName を使う場合には使用しません。

  • handle: HandleObject

    呼び出す関数のハンドルオブジェクトです。

    この引数は引数 dispose とともに指定します。 引数 functionName を使う場合には使用しません。

返値: Any?

JavaScript関数の呼び出し結果です。

返値は suspend 関数として呼び出した場合にのみに返ります。 引数 completionHandler を指定した場合、この関数は返値を持ちません。

JavaScript関数の呼び出し結果です。

返値は async 関数として呼び出した場合にのみに返ります。 引数 completionHandler を指定した場合、この関数は返値を持ちません。

例外

  • IllegalArgumentException
    • 引数 functionName で指定した名前に関数が登録されていない場合。
    • 引数 handle が登録されたJavaScriptの関数のハンドルではない場合。
    • 引数 args として指定した、JavaScriptの関数へ与える引数の型変換がサポートされていない場合。 この例外はJavaScript側で使用可能な値への変換ができない型の引数に対して発生します。
  • InvocationError.FUNCTION_NOT_REGISTERED
    • 引数 functionName で指定した名前にJavaScriptの関数が登録されていない場合。
    • 引数 handle が登録されたJavaScriptの関数のハンドルではない場合。
  • InvocationError.UNSUPPORTED_TYPE_CONVERSION
    • 引数 args として指定した、JavaScriptの関数へ与える引数の型変換がサポートされていない場合。 この例外はJavaScript側で使用可能な値への変換ができない型の引数に対して発生します。

例

ネイティブ側からJavaScriptの関数を呼び出すには、まずAlier.registerFunction() をJavaScript側で呼び出し、関数を登録します。

//  登録する関数を定義します
function add(x, y) {
    return x + y;
}

//  関数 add を登録します
Alier.registerFunction(add);

登録済みのJavaScriptの関数をKotlin側から呼び出すには、ScriptMediator の callJavaScriptFunction() メソッドを使います。

//  JavaScript側で定義した add() を呼び出します。
//  add() へ渡す引数は配列として、callJavaScriptFunction() の引数 args に与えます。
scriptMediator.callJavaScriptFunction(
    functionName = "add",
    args          = arrayOf(1, 2)
) { result ->
    println(result)
    //  ==> 3
}

suspend 関数の中では引数 completionHandler の代わりに async() から返される Deferred<T> を使います。

//  JavaScript側で定義した add() を呼び出します。
//  add() へ渡す引数は配列として、callJavaScriptFunction() の引数 args に与えます。
val result = async {
    scriptMediator.callJavaScriptFunction(
        functionName = "add",
        args          = arrayOf(1, 2)
    )
}.await()

println(result)
//  ==> 3

登録済みのJavaScriptの関数をSwift側から呼び出すには、ScriptMediator の callJavaScriptFunction() メソッドを使います。

//  JavaScript側で定義した add() を呼び出します。
//  add() へ渡す引数は配列として、callJavaScriptFunction() の引数 args に与えます。
try! scriptMediator.callJavaScriptFunction(
    functionName: "add",
    args        : [1, 2]
) { result in
    print(result)
    //  ==> 3
}

async 関数の中では引数 completionHandler の代わりに await キーワードを使い結果を取得します。

//  JavaScript側で定義した add() を呼び出します。
//  add() へ渡す引数は配列として、callJavaScriptFunction() の引数 args に与えます。
let result = try! await scriptMediator.callJavaScriptFunction(
    functionName = "add",
    args         = [1, 2]
)

print(result)
//  ==> 3

解説

JavaScript側で登録された関数を呼び出し、その結果を取得します。

関数の登録は、JavaScript側で Alier.registerFunction() を呼び出すことで行います。

このメソッドには2つの呼び出し方法があります。

  • 一つは呼び出したい関数を関数名によって指定する方法で、そのためには引数 functionName を指定します。
  • もう一つは呼び出したい関数を HandleObject によって指定する方法で、そのためには引数 handle を指定します。

引数 handle を指定する場合、関数の呼び出しを一回限り行い、関数の登録を破棄することができます。そのためには引数 dispose を指定します。関数の登録を破棄するには dispose を true にします。

JavaScript側で登録された関数を呼び出し、その結果を取得します。

関数の登録は、JavaScript側で Alier.registerFunction() を呼び出すことで行います。

このメソッドには2つの呼び出し方法があります。

  • 一つは呼び出したい関数を関数名によって指定する方法で、そのためには引数 functionName を指定します。
  • もう一つは呼び出したい関数を HandleObject によって指定する方法で、そのためには引数 handle を指定します。

引数 handle を指定する場合、関数の呼び出しを一回限り行い、関数の登録を破棄することができます。そのためには引数 dispose を指定します。関数の登録を破棄するには dispose を true にします。