Плагин компилятора для обычных JS-объектов

Обычные JS-объекты

Обычный объект — это простой объект JS, созданный с помощью литерала объекта ({}) и содержащий свойства данных. Многие API JS принимают или возвращают обычные JS-объекты для настройки или обмена данными.

С помощью плагина js-plain-objects можно объявить внешние интерфейсы Kotlin, описывающие форму объекта, и аннотировать их с помощью @JsPlainObject. Затем компилятор генерирует удобные функции для создания и копирования таких объектов с сохранением проверки типов Kotlin.

Подключение плагина

Добавьте плагин js-plain-objects в файл конфигурации Gradle проекта, как показано в следующем примере на Kotlin DSL:

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

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

// build.gradle
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.20'
    id 'org.jetbrains.kotlin.plugin.js-plain-objects' version '2.4.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 = "some@user.com")

    println(JSON.stringify(user))
    // { "name": "Name", "age": 10 }
    println(JSON.stringify(copy))
    // { "name": "Name", "age": 11, "email": "some@user.com" }
}

Код Kotlin компилируется в JavaScript:

function main () {
    var user = { name: "Name", age: 10 };
    var copy = Object.assign({}, user, { age: 11, email: "some@user.com" });

    println(JSON.stringify(user));
    // { "name": "Name", "age": 10 }
    println(JSON.stringify(copy));
    // { "name": "Name", "age": 11, "email": "some@user.com" }
}

Все объекты JavaScript, созданные таким способом, безопасны. Если указать неправильное имя свойства или тип значения, возникнет ошибка на этапе компиляции. Этот подход также не создаёт дополнительных затрат, поскольку сгенерированный код встраивается как простой литерал объекта и вызовы Object.assign.

Что дальше

Подробнее о взаимодействии с JavaScript читайте в документации Использование кода JavaScript в Kotlin и Динамический тип.