Kotlin 允许你将 Kotlin 项目编译为热门模块系统的 JavaScript 模块。以下是可用选项的列表:
require
函数和 module.exports
对象)
选择目标模块系统的方式取决于你的构建环境:
设置每个模块:
打开“File → Project Structure…”,在“Modules”中找到你的模块并选择其下的“Kotlin”facet。在“Module kind”字段中选择合适的模块系统。
为整个项目设置:
打开“File → Settings”,选择“Build, Execution, Deployment”→“Compiler”→“Kotlin compiler”。 在“Module kind”字段中选择合适的模块系统。
要选择通过 Maven 编译时的模块系统,你应该设置 moduleKind
配置属性,即你的pom.xml
应该看起来像这样:
<plugin> <artifactId>kotlin-maven-plugin</artifactId> <groupId>org.jetbrains.kotlin</groupId> <version>${kotlin.version}</version> <executions> <execution> <id>compile</id> <goals> <goal>js</goal> </goals> </execution> </executions> <!-- 插入这些行 --> <configuration> <moduleKind>commonjs</moduleKind> </configuration> <!-- 插入文本结束 --> </plugin>
可用值包括:plain
、 amd
、 commonjs
、 umd
。
要选择通过 Gradle 编译时的模块系统,你应该设置 moduleKind
属性,即
compileKotlin2Js.kotlinOptions.moduleKind = "commonjs"
可用的值类似于 Maven。
@JsModule
注解
external
类、 包、 函数或者属性是一个 JavaScript 模块,你可以使用 @JsModule
注解。考虑你有以下 CommonJS 模块叫“hello”:
module.exports.sayHello = function(name) { alert("Hello, " + name); }你应该在 Kotlin 中这样声明:
@JsModule("hello") external fun sayHello(name: String)
@JsModule
应用到包
一些 JavaScript 库导出包(命名空间)而不是函数和类。从 JavaScript 角度讲 它是一个具有一些成员的对象,这些成员是类、函数和属性。将这些包作为 Kotlin 对象导入通常看起来不自然。编译器允许使用以下助记符将导入的 JavaScript 包映射到 Kotlin 包:
@file:JsModule("extModule") package ext.jspackage.name external fun foo() external class C其中相应的 JavaScript 模块的声明如下:
module.exports = { foo: { /* 此处一些代码 */ }, C: { /* 此处一些代码 */ } }重要提示:标有
@file:JsModule
注解的文件无法声明非外部成员。下面的示例会产生编译期错误:
@file:JsModule("extModule") package ext.jspackage.name external fun foo() fun bar() = "!" + foo() + "!" // 此处报错
在前文示例中,JavaScript 模块导出单个包。但是,一些 JavaScript 库会从模块中导出多个包。Kotlin 也支持这种场景,尽管你必须为每个导入的包声明一个新的 .kt
文件。例如,让我们的示例更复杂一些:
module.exports = { mylib: { pkg1: { foo: function() { /* 此处一些代码 */ }, bar: function() { /* 此处一些代码 */ } }, pkg2: { baz: function() { /* 此处一些代码 */ } } } }要在 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
、当你并不把它编译到一个 JavaScript 模块时,你不能在 Kotlin 代码中使用它。通常,开发人员将他们的库既作为 JavaScript 模块也作为可下载的.js
文件分发,你可以将这些文件复制到项目的静态资源,并通过 <script>
元素包含。 要告诉 Kotlin,可以在非模块环境中使用一个 <@JsModule
声明,你应该放置 @JsNonModule
声明。例如,给定 JavaScript 代码:
function topLevelSayHello(name) { alert("Hello, " + name); } if (module && module.exports) { module.exports = topLevelSayHello; }可以这样描述:
@JsModule("hello") @JsNonModule @JsName("topLevelSayHello") external fun sayHello(name: String)
Kotlin 以 kotlin.js
标准库作为单个文件分发,该文件本身被编译为 UMD 模块,因此你可以使用上述任何模块系统。也可以在 NPM 上使用 kotlin
包。