在 Kotlin 中使用 JavaScript 代码

内联 JavaScript

fun jsTypeOf(o: Any): String {
    return js("typeof o")
}

由于 js 函数的参数会在编译时解析, 然后原样的("as-is")翻译为 JavaScript 代码, 因此参数必须是字符串常量. 所以, 以下代码是不正确的:

fun jsTypeOf(o: Any): String {
    return js(getTypeof() + " o") // 这里会出错
}
fun getTypeof() = "typeof"

注意, 调用 js() 返回的值是 dynamic 类型, 这个类型在编译时不保证任何类型安全性.

external 修饰符

你可以对某个声明使用 external 修饰符, 来告诉 Kotlin 它是由纯 JavaScript 编写的. 编译器看到这样的声明后, 它会假定对应的类, 函数, 或属性的实现, 会由外部提供 (由开发者提供, 或由 npm 依赖项提供), 因此它不会为这个声明生成 JavaScript 代码. 由于同样的原因, external 声明不能带有 body 部. 比如:

external fun alert(message: Any?): Unit

external class Node {
    val firstChild: Node

    fun append(child: Node): Node

    fun removeChild(child: Node): Node

    // 等等
}

external val window: Window

注意, external 修饰符会被内嵌的声明继承下来, 因此, 在示例程序的 Node 类的内部, 在成员函数和属性之前没有添加 external 标记.

external 修饰符只允许用于包级声明. 对于非 external 的类, 不允许声明 external 的成员.

声明类的(静态)成员

function MyClass() { ... }
MyClass.sharedMember = function() { /* 实现代码 */ };
MyClass.prototype.ownMember = function() { /* 实现代码 */ };

在 Kotlin 中没有这样的语法. 但是, 在 Kotlin 中有 同伴 (companion) 对象. Kotlin 以特殊的方式处理 external 类的同伴对象: 它不是期待一个对象, 而是假设同伴对象的成员在 JavaScript 中是定义在类上的成员函数. 上例中的 MyClass, 在 Kotlin 中可以写为:

external class MyClass {
    companion object {
        fun sharedMember()
    }

    fun ownMember()
}

声明可选的参数

如果一个 JavaScript 函数带有可选的参数, 那么编写外部声明时请使用 definedExternally. 这个设置会将参数默认值的生成委托给 JavaScript 函数自身:

external fun myFunWithOptionalArgs(
    x: Int,
    y: String = definedExternally,
    z: String = definedExternally
)

通过这样的外部声明, 你就可以使用一个必须参数和两个可选参数来调用 myFunWithOptionalArgs 函数, 其中, 可选参数的默认值将由 myFunWithOptionalArgs 函数的 JavaScript 实现负责计算.

扩展 JavaScript 类

你可以很容易地扩展 JavaScript 类, 就好像它们是 Kotlin 类一样. 你只需要定义一个 external open 类, 然后通过一个非 external 类来扩展它. 比如:

open external class Foo {
    open fun run()
    fun stop()
}

class Bar : Foo() {
    override fun run() {
        window.alert("Running!")
    }

    fun restart() {
        window.alert("Restarting")
    }
}

external 接口

JavaScript 没有接口的概念. 如果一个函数要求它的参数支持 foo 和 bar 两个方法, 你只需要传递一个确实带有这些方法的对象.

external interface HasFooAndBar {
    fun foo()

    fun bar()
}

external fun myFunction(p: HasFooAndBar)

external 接口的另一种典型的使用场景, 是用来描述配置信息对象. 比如:

external interface JQueryAjaxSettings {
    var async: Boolean

    var cache: Boolean

    var complete: (JQueryXHR, String) -> Unit

    // 等等
}

fun JQueryAjaxSettings(): JQueryAjaxSettings = js("{}")

external class JQuery {
    companion object {
        fun get(settings: JQueryAjaxSettings): JQueryXHR
    }
}

fun sendQuery() {
    JQuery.get(JQueryAjaxSettings().apply {
        complete = { (xhr, data) ->
            window.alert("Request complete")
        }
    })
}

external 接口存在一些限制:

类型转换

"不安全的" 类型转换操作符 as 在转换失败时会抛出 ClassCastException 异常, 除此之外, Kotlin/JS 还提供了 unsafeCast<T>(). 如果使用 unsafeCast, 在运行时完全不进行任何类型检查. 比如, 对于下面两个方法:

fun usingUnsafeCast(s: Any) = s.unsafeCast<String>()
fun usingAsOperator(s: Any) = s as String

function usingUnsafeCast(s) {
    return s;
}

function usingAsOperator(s) {
    var tmp$;
    return typeof (tmp$ = s) === 'string' ? tmp$ : throwCCE();
}

相等判断

在 Kotlin/JS 中, Kotlin 引用相等操作符 (===) 永远会翻译为 JavaScript 的严格相等操作符 (===).

JavaScript === 操作符不仅检查两个值相等, 而且检查这两个值的类型也相等:

fun main() {
    val name = "kotlin"
    val value1 = name.substring(0, 1)
    val value2 = name.substring(0, 1)

    println(if (value1 === value2) "yes" else "no")
    // 在 Kotlin/JS 平台, 输出结果为 'yes'
    // 在其他平台, 输出结果为 'no'
}

而且, 在 Kotlin/JS 中, 数值类型 Byte, Short, Int, Float, 和 Double 在运行期都使用 JavaScript 类型 Number 表达. 因此, 这 5 种类型的值是无法区分的:

fun main() {
    println(1.0 as Any === 1 as Any)
    // 在 Kotlin/JS 平台, 输出结果为 'true'
    // 在其他平台, 输出结果为 'false'
}

在 Kotlin 中使用 JavaScript 代码﻿

内联 JavaScript﻿

external 修饰符﻿

声明类的(静态)成员﻿

声明可选的参数﻿

扩展 JavaScript 类﻿

external 接口﻿

类型转换﻿

相等判断﻿

tip