与 JavaScript 交互

外部声明

在 Kotlin 中默认无法使用外部的 JavaScript 代码. 要在 Kotlin 中使用 JavaScript 代码, 你可以使用 external 声明来描述它的 API.

function greet (name) {
    console.log("Hello, " + name + "!");
}

external fun greet(name: String)

fun main() {
    greet("Alice")
}

let globalCounter = 0;

external var globalCounter: Int

class Rectangle {
    constructor (height, width) {
        this.height = height;
        this.width = width;
    }

    area () {
        return this.height * this.width;
    }
}

external class Rectangle(height: Double, width: Double) : JsAny {
    val height: Double
    val width: Double
    fun area(): Double
}

function createUser (name, age) {
    return { name: name, age: age };
}

external interface User : JsAny {
    val name: String
    val age: Int
}

external fun createUser(name: String, age: Int): User

let Counter = {
    value: 0,
    step: 1,
    increment () {
        this.value += this.step;
    }
};

external object Counter : JsAny {
    fun increment()
    val value: Int
    var step: Int
}

带有 JavaScript 代码的 Kotlin 函数

你可以定义一个函数, 函数体为 = js("code") 形式, 这样就可以将 JavaScript 代码段添加到 Kotlin/Wasm 代码中:

fun getCurrentURL(): String =
    js("window.location.href")

如果你想要运行多条 JavaScript 语句组成的代码段, 请将你的代码包含在大括号 {} 内, 再放在字符串中:

fun setLocalSettings(value: String): Unit = js(
    """{
        localStorage.setItem('settings', value);
}"""
)

如果你想要返回一个对象, 请在大括号 {} 之外加上小括号 ():

fun createJsUser(name: String, age: Int): JsAny =
    js("({ name: name, age: age })")

Kotlin/Wasm 会对 js() 函数调用特殊处理, 而且它的实现存在一些限制:

• js() 函数调用的参数必须是字符串字面值.

• js() 函数调用必须是函数体中唯一的表达式.

• 只允许在包级(package-level)函数中调用 js() 函数.

• 函数的返回值必须明确指定.

• 类型 存在限制, 与 external fun 类似.

Kotlin 编译器会生成 JavaScript 文件, 将代码字符串放入函数中, 并将 JavaScript 文件导入为 WebAssembly 格式. Kotlin 编译器不会验证这些 JavaScript 代码段. 如果存在 JavaScript 语法错误, 这些错误会在你运行 JavaScript 代码时报告.

note

@JsFun 注解的功能与此类似, 可能会被弃用.

JavaScript 模块

默认情况下, 外部声明对应于 JavaScript 的全局范围(global scope). 如果你对一个 Kotlin 文件标注 @JsModule 注解, 那么这个文件内的所有外部声明都会从指定的模块导入.

请看这个 JavaScript 代码示例:

// users.mjs
export let maxUsers = 10;

export class User {
    constructor (username) {
        this.username = username;
    }
}

在 Kotlin 中, 使用 @JsModule 注解来使用这段 JavaScript 代码:

// Kotlin
@file:JsModule("./users.mjs")

external val maxUsers: Int

external class User : JsAny {
    constructor(username: String)

    val username: String
}

数组互操作性

你可以将 JavaScript 的 JsArray<T> 复制到 Kotlin 的原生 Array 或 List 类型; 反过来也是如此, 你可以将这些 Kotlin 类型复制到 JsArray<T>.

要将 JsArray<T> 转换为 Array<T>, 或做反向的转换, 请使用 适配器函数.

下面是一个泛型类型之间转换的示例:

val list: List<JsString> =
    listOf("Kotlin", "Wasm").map { it.toJsString() }

// 使用 .toJsArray() 将 List 或 Array 转换为 JsArray
val jsArray: JsArray<JsString> = list.toJsArray()

// 使用 .toArray() 和 .toList() 转换回 Kotlin 类型
val kotlinArray: Array<JsString> = jsArray.toArray()
val kotlinList: List<JsString> = jsArray.toList()

类似的转换器函数可以将类型数组转换为等价的 Kotlin 类型 (例如, IntArray 和 Int32Array). 更多详细信息和具体实现, 请参见 kotlinx-browser 代码仓库.

下面是一个类型数组之间转换的示例:

import org.khronos.webgl.*

    // ...

    val intArray: IntArray = intArrayOf(1, 2, 3)

    // 使用 .toInt32Array() 将 Kotlin 的 IntArray 转换为 JavaScript 的 Int32Array
    val jsInt32Array: Int32Array = intArray.toInt32Array()

    // 使用 toIntArray() 将 JavaScript 的 Int32Array 转换回 Kotlin 的 IntArray
    val kotlnIntArray: IntArray = jsInt32Array.toIntArray()

带 @JsExport 注解的函数

要让一个 Kotlin/Wasm 函数可以被 JavaScript 代码使用, 请添加 @JsExport 注解:

// Kotlin/Wasm

@JsExport
fun addOne(x: Int): Int = x + 1

在生成的 .mjs 模块中, 标注了 @JsExport 注解的 Kotlin/Wasm 函数会成为一个 default export 上的属性. 然后你就可以在 JavaScript 中使用这个函数:

// JavaScript

import exports from "./module.mjs"

exports.addOne(10)

Kotlin/Wasm 编译器能够通过你的 Kotlin 代码中的任何 @JsExport 声明生成 TypeScript 定义. 这些定义能够被 IDE 和 JavaScript 工具使用, 提供代码自动完成, 帮助类型检查, 使得在 JavaScript 和 TypeScript 中可以更加容易的使用 Kotlin 代码.

Kotlin/Wasm 编译器会收集所有标注了 @JsExport 注解的顶层函数, 并自动在一个 .d.ts 文件中生成 TypeScript 定义.

要生成 TypeScript 定义, 请在你的 build.gradle.kts 文件的 wasmJs{} 代码块中, 添加 generateTypeScriptDefinitions() 函数:

kotlin {
    wasmJs {
        binaries.executable()
        browser {
        }
        generateTypeScriptDefinitions()
    }
}

warning

Kotlin/Wasm 的 TypeScript 声明文件生成功能是 实验性功能. 它随时有可能变更或被删除.

JsAny 类型

JavaScript 值在 Kotlin 中使用 JsAny 类型和它的子类型来表示.

Kotlin/Wasm 标准库提供了其中一些类型的表示:

• kotlin.js 包:

  • JsAny

  • JsBoolean, JsNumber, JsString

  • JsArray

  • Promise

你也可以声明一个 external 接口或类, 创建自定义的 JsAny 子类型.

JsReference 类型

使用 JsReference 类型, Kotlin 值可以作为不透明引用(Opaque Reference)传递给 JavaScript.

例如, 如果你想要将这个 Kotlin 类 User 公开给 JavaScript:

class User(var name: String)

你可以使用 toJsReference() 函数来创建 JsReference<User>, 并将它返回给 JavaScript:

@JsExport
fun createUser(name: String): JsReference<User> {
    return User(name).toJsReference()
}

这些引用在 JavaScript 中不能直接使用, 行为就像空的冻结 JavaScript 对象. 要操作这些对象, 你需要将更多函数导出到 JavaScript, 方法是, 使用 get() 方法解包这些引用值:

@JsExport
fun setUserName(user: JsReference<User>, name: String) {
    user.get().name = name
}

你可以在 JavaScript 中创建一个类, 并改变它的名称:

import UserLib from "./userlib.mjs"

let user = UserLib.createUser("Bob");
UserLib.setUserName(user, "Alice");

类型参数

与 JavaScript 互操作的声明, 可以拥有类型参数, 类型参数的上界(Upper Bound)是 JsAny 或它的子类型. 例如:

external fun <T : JsAny> processData(data: JsArray<T>): T