将 Kotlin/JS 项目迁移到 IR 编译器

问题: 使用 Kotlin 接口和类 (包括数据类), 如果继承自纯 JS 类, 比如 React 的 State 和 Props, 可能导致 ClassCastException 异常. 出现这样的异常是因为, 编译器试图将这些类的实例象 Kotlin 对象一样使用, 然而它们实际上来自 JS.

// 替换以下代码
interface AppState : State { }
interface AppProps : Props { }
data class CustomComponentState(var name: String) : State

// 替换为
external interface AppState : State { }
external interface AppProps : Props { }
external interface CustomComponentState : State {
    var name: String
}

在 IntelliJ IDEA 中, 你可以使用这些结构化查找与替换模板, 将接口自动标记为 external:

将外部接口的属性转换为 var

问题: 在 Kotlin/JS 代码中, 外部接口的属性不能为只读(val )属性, 因为这些属性的赋值, 只能在使用 js() 或 jso() (来自 kotlin-wrappers 的帮助函数) 创建对象之后:

import kotlinx.js.jso

val myState = jso<CustomComponentState>()
myState.name = "name"

解决方案: 将外部接口的所有属性转换为 var:

// 替换以下代码
external interface CustomComponentState : State {
    val name: String
}

// 替换为
external interface CustomComponentState : State {
    var name: String
}

将外部接口中带接受者的函数转换为普通函数

// 替换以下代码
external interface ButtonProps : Props {
    var inside: StyledDOMBuilder<BUTTON>.() -> Unit
}

external interface ButtonProps : Props {
    var inside: (StyledDOMBuilder<BUTTON>) -> Unit
}

为与 JS 交互, 创建单纯 JS 对象

但属性仍然可以通过名称访问: obj.myProperty

external interface AppProps { var name: String }
data class AppPropsImpl(override var name: String) : AppProps
fun main() {
    val jsApp = js("{name: 'App1'}") as AppProps // 单纯 JS 对象
    println("Kotlin sees: ${jsApp.name}") // 结果为: "App1"
    println("JSON.stringify sees:" + JSON.stringify(jsApp)) // 结果为: {"name":"App1"} - OK

    val ktApp = AppPropsImpl("App2") // Kotlin 对象
    println("Kotlin sees: ${ktApp.name}") // "App2"
    // JSON 只能得到后端域, 不能得到属性
    println("JSON.stringify sees:" + JSON.stringify(ktApp)) // {"_name_3":"App2"}
}

解决方案 1: 使用 js() 或 jso() (来自 kotlin-wrappers 的帮助函数) 创建单纯 JavaScript 对象:

external interface AppProps { var name: String }
data class AppPropsImpl(override var name: String) : AppProps

// 替换以下代码
val ktApp = AppPropsImpl("App1") // Kotlin 对象

// 替换为
val jsApp = js("{name: 'App1'}") as AppProps // 或使用 jso {} 函数

解决方案 2: 使用 kotlin.js.json() 创建对象:

// 或者替换为
val jsonApp = kotlin.js.json(Pair("name", "App1")) as AppProps

将函数引用上的 toString() 调用替换为 .name

问题: 在 IR 后端中, 对函数引用调用 toString()不会输出唯一的值.

解决方案: 使用 name 属性代替 toString() 调用.

在构建脚本中明确指定 binaries.executable()

问题: 编译器不会产生可执行的 .js 文件.

解决方案: 在项目的 build.gradle(.kts) 文件中添加 binaries.executable().

kotlin {
    js(IR) {
        browser {
        }
        binaries.executable()
    }
}

关于使用 Kotlin/JS IR 编译器时其他问题的提示

将外部接口中的 boolean 属性标记为 nullable

问题: 当你对外部接口中的 Boolean 属性调用 toString 时, 你会得到 Uncaught TypeError: Cannot read properties of undefined (reading 'toString') 之类的错误. JavaScript 将 boolean 变量的 null 值或 undefined 值当作 false 处理. 如果你需要对可能为 null 或 undefined 的 Boolean 值调用 toString (比如, 如果你的代码被 JavaScript 代码调用, 而你无法控制这些 JavaScript 代码), 需要注意这个问题:

external interface SomeExternal {
    var visible: Boolean
}

fun main() {
    val empty: SomeExternal = js("{}")
    println(empty.visible.toString()) // Uncaught TypeError: Cannot read properties of undefined (reading 'toString')
}

如果你想要在 Kotlin 中覆盖的函数内(比如, 一个 React button), 使用这样的属性, 将会发生 ClassCastException 异常:

button {
    attrs {
        autoFocus = props.visible // 这里会发生 ClassCastException 异常
    }
}

解决方案: 你可以将你的外部接口的 Boolean 属性标记为 nullable (Boolean?):

// 替换以下代码
external interface SomeExternal {
    var visible: Boolean
}

// 替换为
external interface SomeExternal {
    var visible: Boolean?
}

将 Kotlin/JS 项目迁移到 IR 编译器﻿

tip

将 JS 和 React 相关的类和接口转换为外部接口(External Interface)﻿

将外部接口的属性转换为 var﻿

将外部接口中带接受者的函数转换为普通函数﻿

为与 JS 交互, 创建单纯 JS 对象﻿

将函数引用上的 toString() 调用替换为 .name﻿

在构建脚本中明确指定 binaries.executable()﻿

关于使用 Kotlin/JS IR 编译器时其他问题的提示﻿

将外部接口中的 boolean 属性标记为 nullable﻿

将 JS 和 React 相关的类和接口转换为外部接口(External Interface)