Взаимодействие с JavaScript

Внешние объявления

Внешний код JavaScript по умолчанию недоступен в Kotlin. Чтобы использовать код JavaScript в Kotlin, можно описать его API с помощью объявлений external.

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
}

import kotlin.js.nativeInvoke

@OptIn(ExperimentalWasmJsInterop::class)
external class JsAction {
    @nativeInvoke
    operator fun invoke(data: String)
}

fun main() {
    val action = JsAction() 
    action("Run task")
}

Функции Kotlin с кодом JavaScript

В код Kotlin/Wasm можно добавить фрагмент JavaScript, определив функцию с телом = js("code"):

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 })")

Вызовы функции js() обрабатываются в Kotlin/Wasm особым образом и имеют ряд ограничений:

• Вызову функции js() необходимо передать строковый литерал в качестве аргумента.

• Вызов функции js() должен быть единственным выражением в теле функции.

• Функцию js() можно вызывать только из функций уровня пакета.

• Возвращаемый тип функции необходимо указывать явно.

• Типы ограничены так же, как и для external fun.

Компилятор Kotlin помещает строку с кодом в функцию в сгенерированном файле JavaScript и импортирует её в формате WebAssembly. Компилятор Kotlin не проверяет эти фрагменты JavaScript. Если в них есть синтаксические ошибки JavaScript, они будут обнаружены при запуске кода JavaScript.

Модули JavaScript

По умолчанию внешние объявления соответствуют глобальной области видимости JavaScript. Если снабдить файл Kotlin аннотацией @JsModule, все внешние объявления в нем будут импортированы из указанного модуля.

Рассмотрим этот пример кода JavaScript:

// users.mjs
export let maxUsers = 10;

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

Используйте этот код JavaScript в Kotlin с аннотацией @JsModule:

// 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() }

// Uses .toJsArray() to convert List or Array to JsArray
val jsArray: JsArray<JsString> = list.toJsArray()

// Uses .toArray() and .toList() to convert it back to Kotlin types 
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)
    
    // Uses .toInt32Array() to convert Kotlin IntArray to JavaScript Int32Array
    val jsInt32Array: Int32Array = intArray.toInt32Array()
    
    // Uses toIntArray() to convert JavaScript Int32Array back to Kotlin IntArray
    val kotlinIntArray: IntArray = jsInt32Array.toIntArray()

Функции с аннотацией @JsExport

Чтобы сделать функцию Kotlin/Wasm доступной для кода JavaScript, используйте аннотацию @JsExport:

// Kotlin/Wasm

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

Функции Kotlin/Wasm, помеченные аннотацией @JsExport, доступны как свойства экспорта default сгенерированного модуля .mjs. После этого эту функцию можно использовать в JavaScript:

// JavaScript

import exports from "./module.mjs"

exports.addOne(10)

Компилятор Kotlin/Wasm умеет генерировать определения TypeScript для любых объявлений @JsExport в коде Kotlin. Эти определения можно использовать в IDE и инструментах JavaScript для автодополнения кода и проверки типов, а также для упрощения использования кода Kotlin из JavaScript и TypeScript.

Компилятор Kotlin/Wasm собирает все функции верхнего уровня, помеченные аннотацией @JsExport, и автоматически генерирует определения TypeScript в файле .d.ts.

Чтобы сгенерировать определения TypeScript, добавьте функцию generateTypeScriptDefinitions() в файл build.gradle.kts, в блок wasmJs{}:

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

Тип JsAny

Значения JavaScript представлены в Kotlin типом JsAny и его подтипами.

Стандартная библиотека Kotlin/Wasm предоставляет представления для некоторых из этих типов:

• Пакет kotlin.js:

  • JsAny

  • JsBoolean, JsNumber, JsString

  • JsArray

  • Promise

Можно также создавать собственные подтипы JsAny, объявляя интерфейс или класс external.

Тип JsReference

Значения Kotlin можно передавать в JavaScript как непрозрачные ссылки с помощью типа JsReference.

Например, если нужно предоставить этот класс 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 могут иметь параметры типа, если их верхняя граница — JsAny или его подтипы. Например:

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