Experimental

JS 純物件編譯器外掛程式

JavaScript (JS) 純物件編譯器外掛程式 (js-plain-objects) 讓您能夠以型別安全的方式建立和複製純 JS 物件。

您可以在此找到關於純 JS 物件的資訊，以及如何在您的 Kotlin/JS 專案中使用 js-plain-objects 編譯器外掛程式。

js-plain-objects 外掛程式僅適用於新的 K2 Kotlin 編譯器。

純 JS 物件

純物件是透過物件字面值 ({}) 建立的簡單 JS 物件，其中包含資料屬性。 許多 JS API 會接受或傳回純 JS 物件，用於配置或資料交換。

藉由 js-plain-objects 外掛程式，您可以宣告一個 Kotlin 外部介面來描述物件形狀，並使用 @JsPlainObject 註解它。 編譯器隨後會生成方便的函式來建構和複製這類物件，同時保留 Kotlin 的型別安全。

啟用外掛程式

將 js-plain-objects 外掛程式新增到您專案的 Gradle 配置檔中，如下方的 Kotlin DSL 所示：

KotlinGroovy

// build.gradle.kts
plugins {
    kotlin("multiplatform") version "2.2.20"
    kotlin("plugin.js-plain-objects") version "2.2.20"
}

kotlin {
    js {
        browser() // or nodejs()
    }
}

// build.gradle
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.2.20'
    id 'org.jetbrains.kotlin.plugin.js-plain-objects' version '2.2.20'
}

kotlin {
    js {
        browser() // or nodejs()
    }
}

宣告純物件型別

啟用 js-plain-objects 外掛程式後，您可以宣告一個純物件型別。 使用 @JsPlainObject 註解一個外部介面。例如：

@JsPlainObject
external interface User {
    val name: String
    val age: Int
    // You can use nullable types to declare a property as optional
    val email: String? 
}

當外掛程式處理這類介面時，它會生成一個伴生物件，其中包含兩個用於建立和複製物件的輔助函式：

@JsPlainObject
external interface User {
    val name: String
    val age: Int
    val email: String?

    // Generated by the plugin
    @JsExport.Ignore
    companion object {
        inline operator fun invoke(name: String, age: Int, email: String? = NOTHING): User =
            js("({ name: name, age: age, email: email })")

        inline fun copy(source: User, name: String = NOTHING, age: Int = NOTHING, email: String? = NOTHING): User =
            js("Object.assign({}, source, { name: name, age: age, email: email })")
    }
}

從上一個範例中：

• name 和 age 宣告時沒有可為 null 標記，因此它們是必填的。
• email 宣告為可為 null，因此它是選填的，在建立時可以省略。
• 操作符 invoke 使用提供的屬性建構一個新的純 JS 物件。
• copy 函式透過淺層複製 source 並覆寫任何指定的屬性來建立一個新物件。
• 伴生物件標記了 @JsExport.Ignore，以避免這些輔助函式洩漏到 JS 匯出中。

使用純物件

使用生成的輔助函式建立和複製物件：

fun main() {
    val user = User(name = "Name", age = 10)
    val copy = User.copy(user, age = 11, email = "[email protected]")

    println(JSON.stringify(user))
    // { "name": "Name", "age": 10 }
    println(JSON.stringify(copy))
    // { "name": "Name", "age": 11, "email": "[email protected]" }
}

Kotlin 程式碼會編譯成 JavaScript：

function main () {
    var user = { name: "Name", age: 10 };
    var copy = Object.assign({}, user, { age: 11, email: "[email protected]" });

    println(JSON.stringify(user));
    // { "name": "Name", "age": 10 }
    println(JSON.stringify(copy));
    // { "name": "Name", "age": 11, "email": "[email protected]" }
}

任何透過這種方法建立的 JavaScript 物件都是安全的。 當您使用錯誤的屬性名稱或值型別時，將會遇到編譯時期錯誤。這種方法也是零成本的，因為生成的程式碼會被行內化為簡單的物件字面值和 Object.assign 呼叫。

接下來

在 從 Kotlin 使用 JavaScript 程式碼 和 動態型別 文件中了解更多關於與 JavaScript 互通的資訊。