Использование кода Kotlin из JavaScript

@JsName аннотация

В некоторых случаях (например, для поддержки перегрузок) компилятор Kotlin изменяет имена сгенерированных функций и атрибутов в коде JavaScript. Чтобы управлять сгенерированными именами, можно использовать аннотацию @JsName:

// Module 'kjs'
class Person(val name: String) {
    fun hello() {
        println("Hello $name!")
    }

    @JsName("helloWithGreeting")
    fun hello(greeting: String) {
        println("$greeting $name!")
    }
}

Теперь этот класс можно использовать из JavaScript следующим образом:

// If necessary, import 'kjs' according to chosen module system
var person = new kjs.Person("Dmitry");   // refers to module 'kjs'
person.hello();                          // prints "Hello Dmitry!"
person.helloWithGreeting("Servus");      // prints "Servus Dmitry!"

Если бы мы не указали аннотацию @JsName, имя соответствующей функции содержало бы суффикс, вычисленный на основе сигнатуры функции, например hello_61zpoe$.

Обратите внимание, что в некоторых случаях компилятор Kotlin не изменяет имена:

• Имена объявлений external не изменяются.

• Имена всех переопределённых функций в классах, не являющихся external и наследующих классы external, не изменяются.

Параметр @JsName должен быть константной строкой, содержащей допустимый идентификатор. Компилятор сообщит об ошибке при любой попытке передать в @JsName строку, не являющуюся идентификатором. Следующий пример приведёт к ошибке компиляции:

@JsName("new C()")   // error here
external fun newC()

@JsExport аннотация

Применив аннотацию @JsExport к объявлению верхнего уровня (например, классу, интерфейсу или функции), можно сделать объявления Kotlin доступными из JavaScript или TypeScript. Аннотация экспортирует все вложенные объявления под именами, заданными в Kotlin.

Вот пример экспорта интерфейса Kotlin с вложенным классом и именованным сопутствующим объектом:

@JsExport
interface Identity {
     class Metadata(val tag: String)

    companion object Registry {
        val defaultTag = "GUEST"
    }
}

В настоящее время аннотация @JsExport — единственный способ сделать ваши функции видимыми из Kotlin.

Аннотация @JsExport также доступна:

• В общем коде многоплатформенных проектов. Она действует только при компиляции для целевой платформы JavaScript и позволяет также экспортировать объявления Kotlin, не относящиеся к конкретной платформе.

• Вместе с аннотацией @JsName для задания имён сгенерированных и экспортируемых функций. Это помогает устранить неоднозначность при экспорте (например, перегрузок функций с одинаковыми именами).

• На уровне файла с помощью @file:JsExport.

// Kotlin
@JsExport
@JvmInline
value class Email(val address: String) {
    init { require(address.contains("@")) { "Invalid email" } }
}

@JsExport
class AuthService {
    suspend fun login(email: Email): String = ...
}

// TypeScript
import { AuthService, Email } from "..."
const auth = new AuthService();

console.log(await auth.login(new Email("jane@example.com"))); 
// "Welcome, jane@example.com!"
console.log(await auth.login(new Email("not-an-email"))); 
// "Invalid email"

@JsNoRuntime аннотация

Интерфейсы Kotlin можно экспортировать в JavaScript/TypeScript с помощью аннотации @JsNoRuntime. Она позволяет напрямую преобразовывать их в обычные интерфейсы TypeScript.

Например, чтобы экспортировать интерфейс Kotlin из многоплатформенного проекта Kotlin:

1. Пометьте интерфейс Kotlin аннотацией @JsNoRuntime в общем коде:

   // commonMain
   import kotlin.js.JsNoRuntime
   
   @JsNoRuntime
   expect interface DataProcessor {
       fun process(data: String): Int 
   }
   

2. Предоставьте фактическую реализацию с помощью @JsNoRuntime в исходном коде для JS:

   // jsMain
   import kotlin.js.JsNoRuntime
   
   @JsNoRuntime
   actual interface DataProcessor {
       actual fun process(data: String): Int
   } 
   

3. В TypeScript интерфейс будет преобразован в обычный интерфейс TypeScript:

   // Generated .d.ts
   export interface DataProcessor {
       process(data: string): number;
   }
   

Для многоплатформенных проектов Kotlin действуют следующие общие правила:

• Объявления интерфейсов expect и actual должны быть помечены аннотацией @JsNoRuntime. Исключение составляют реализации external в платформенном коде на стороне actual, которые не требуют аннотации.

• Использовать объявления интерфейсов external в общем коде на стороне expect запрещено. Вместо этого используйте обычные интерфейсы, помеченные аннотацией @JsNoRuntime.

Экспорт интерфейсов Kotlin с помощью @JsNoRuntime имеет некоторые ограничения. Аннотацию нельзя использовать с:

• Интерфейсами external, поскольку по умолчанию они уже ведут себя так, как если бы у них была аннотация @JsNoRuntime. Её добавление приводит к предупреждению компилятора.

• Проверками типов is и as.

• Ссылками на классы с использованием синтаксиса ::class.

• Интерфейсами, передаваемыми как аргумент реифицированного типа.

@JsStatic

Аннотация @JsStatic указывает компилятору сгенерировать дополнительные статические методы для целевого объявления. Это позволяет напрямую использовать статические члены из кода Kotlin в JavaScript.

Аннотацию @JsStatic можно применять к функциям, определённым в именованных объектах, а также в сопутствующих объектах, объявленных внутри классов и интерфейсов. При использовании этой аннотации компилятор сгенерирует как статический метод объекта, так и метод экземпляра в самом объекте. Например:

// Kotlin
class C {
    companion object {
        @JsStatic
        fun callStatic() {}
        fun callNonStatic() {}
    }
}

Теперь функция callStatic() является статической в JavaScript, а функция callNonStatic() — нет:

// JavaScript
C.callStatic();              // Works, accessing the static function
C.callNonStatic();           // Error, not a static function in the generated JavaScript
C.Companion.callStatic();    // Instance method remains
C.Companion.callNonStatic(); // The only way it works

Аннотацию @JsStatic также можно применить к свойству объекта или сопутствующего объекта. В этом случае его методы получения и установки становятся статическими членами этого объекта или класса, содержащего сопутствующий объект.

Эта функция находится на стадии экспериментальной разработки. Оставляйте отзывы в нашем трекере задач YouTrack.

Использование типа BigInt для представления типа Long в Kotlin

При компиляции в современный JavaScript (ES2020) Kotlin/JS использует встроенный тип BigInt JavaScript для представления значений Long Kotlin.

Чтобы включить поддержку типа BigInt, добавьте следующий параметр компилятора в файл build.gradle(.kts):

// build.gradle.kts
kotlin {
    js {
        ...
        compilerOptions {
            freeCompilerArgs.add("-Xes-long-as-bigint")
        }
    }
}

Эта функция находится на стадии экспериментальной разработки. Оставляйте отзывы в нашем трекере задач YouTrack.

Использование типа BigInt64Array для представления типа LongArray в Kotlin

При компиляции в JavaScript Kotlin/JS может использовать встроенный тип BigInt64Array JavaScript для представления значений LongArray в Kotlin.

Чтобы включить поддержку типа BigInt64Array, добавьте следующий параметр компилятора в файл build.gradle(.kts):

// build.gradle.kts
kotlin {
    js {
        ...
        compilerOptions {
            freeCompilerArgs.add("-Xes-long-as-bigint")
        }
    }
}

Эта функция находится на стадии экспериментальной разработки. Оставляйте отзывы в нашем трекере задач YouTrack.