Модули JavaScript

Выберите целевую систему модулей

Чтобы выбрать тип модуля, установите параметр компилятора moduleKind в скрипте сборки Gradle.

tasks.named<KotlinJsCompile>("compileKotlinJs").configure {
    compilerOptions.moduleKind.set(org.jetbrains.kotlin.gradle.dsl.JsModuleKind.MODULE_COMMONJS)
}

compileKotlinJs.compilerOptions.moduleKind = org.jetbrains.kotlin.gradle.dsl.JsModuleKind.MODULE_COMMONJS

Доступные значения: umd (по умолчанию), commonjs, amd, plain.

В Kotlin Gradle DSL также есть сокращение для установки типа модуля CommonJS:

kotlin {
    js {
         useCommonJs()
         // . . .
    }
}

Применение @JsModule к пакетам

Некоторые библиотеки JavaScript экспортируют пакеты (пространства имен) вместо функций и классов. С точки зрения JavaScript, это объект, имеющий члены, являющиеся классами, функциями и свойствами. Импорт этих пакетов как объектов Kotlin часто выглядит неестественно. Компилятор может сопоставлять импортированные пакеты JavaScript с пакетами Kotlin, используя следующую нотацию:

@file:JsModule("extModule")
package ext.jspackage.name

external fun foo()

external class C

где соответствующий модуль JavaScript объявлен так:

module.exports = {
    foo:  { /* some code here */ },
    C:  { /* some code here */ }
}

Файлы, помеченные аннотацией @file:JsModule, не могут объявлять не внешние члены. Приведенный ниже пример приводит к ошибке времени компиляции:

@file:JsModule("extModule")
package ext.jspackage.name

external fun foo()

fun bar() = "!" + foo() + "!" // error here

Импорт более глубоких иерархий пакетов

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

Например, давайте усложним пример:

module.exports = {
    mylib: {
        pkg1: {
            foo: function() { /* some code here */ },
            bar: function() { /* some code here */ }
        },
        pkg2: {
            baz: function() { /* some code here */ }
        }
    }
}

Чтобы импортировать этот модуль в Kotlin, вам нужно написать два файла Kotlin:

@file:JsModule("extModule")
@file:JsQualifier("mylib.pkg1")
package extlib.pkg1

external fun foo()

external fun bar()

и

@file:JsModule("extModule")
@file:JsQualifier("mylib.pkg2")
package extlib.pkg2

external fun baz()

@JsNonModule аннотация

Когда объявление помечено как @JsModule, вы не можете использовать его из кода Kotlin, когда не компилируете его в модуль JavaScript. Обычно разработчики распространяют свои библиотеки как модули JavaScript и загружаемые .js файлы, которые можно скопировать в статические ресурсы вашего проекта и включить с помощью тега <script>. Чтобы сообщить Kotlin, что разрешается использовать объявление @JsModule из среды без модулей, добавьте аннотацию @JsNonModule. Например, рассмотрите следующий код JavaScript:

function topLevelSayHello(name) { alert("Hello, " + name); }
if (module && module.exports) {
    module.exports = topLevelSayHello;
}

Вы можете описать его в Kotlin следующим образом:

@JsModule("hello")
@JsNonModule
@JsName("topLevelSayHello")
external fun sayHello(name: String)

Система модулей, используемая стандартной библиотекой Kotlin

Kotlin распространяется со стандартной библиотекой Kotlin/JS в виде одного файла, который сам компилируется как UMD-модуль, поэтому вы можете использовать его с любой системой модулей, описанной выше. Хотя для большинства случаев использования Kotlin/JS рекомендуется использовать зависимость Gradle от kotlin-stdlib-js, он также доступен в NPM как пакет kotlin.