JavaScript 模块
可以将 Kotlin 项目编译为适用于各种流行模块系统的 JavaScript 模块。我们目前支持以下 JavaScript 模块配置:
- 统一模块定义(UMD,Unified Module Definitions),它与 AMD 和 CommonJS 兼容。 UMD 模块也可以在不导入或没有模块系统的情况下执行。这是
browser
与nodejs
目标的默认选项。 - 异步模块定义(AMD,Asynchronous Module Definition),它尤其为 RequireJS 库所使用。
- CommonJS,广泛用于 Node.js/npm (
require
函数和module.exports
对象) - 无模块(Plain)。不为任何模块系统编译。可以在全局作用域中以其名称访问模块。
浏览器目标
如果以浏览器为目标并且要使用与 UMD 不同的模块系统,则可以在 webpackTask
配置块中指定所需的模块类型。例如,要切换到 CommonJS,请使用:
kotlin {
js {
browser {
webpackTask {
output.libraryTarget = "commonjs2"
}
}
binaries.executable()
}
}
Webpack 提供了 commonjs
与 commonjs2
这两种不同的 CommonJS“风味”,它们影响声明的可用方式。虽然在大多数情况下,可能希望使用 commonjs2
,该模块将 module.exports
语法添加到所生成的库中,但也可以选择“纯”commonjs
选项,该选项完全实现 CommonJS 规范。 如需了解有关 commonjs
与 commonjs2
之间的区别的更多信息,请在此处查看。
JavaScript 库与 Node.js 文件
如果正在创建一个将从 JavaScript 或 Node.js 文件中使用的库,并且希望使用不同的模块系统,那么说明会略有不同。
选择目标模块系统
要选择模块种类,请在 Gradle 构建脚本中设置 moduleKind
编译器选项。
【Kotlin】
tasks.named<KotlinJsCompile>("compileKotlinJs").configure {
compilerOptions.moduleKind.set(org.jetbrains.kotlin.gradle.dsl.JsModuleKind.MODULE_COMMONJS)
}
【Groovy】
compileKotlinJs.compilerOptions.moduleKind = org.jetbrains.kotlin.gradle.dsl.JsModuleKind.MODULE_COMMONJS
可用值为:umd
(默认)、commonjs
、amd
、plain
。
这与调整
webpackTask.output.libraryTarget
不同。库目标更改了 webpack 生成的 输出(在代码已编译之后)。compilerOptions.moduleKind
更改 由 Kotlin 编译器 生成的输出。
在 Kotlin Gradle DSL 中,还有一个用于设置 CommonJS 模块种类的快捷方式:
kotlin {
js {
useCommonJs()
// ...
}
}
@JsModule 注解
要告诉 Kotlin 一个 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;
}
在 Kotlin 中可以这样描述:
@JsModule("hello")
@JsNonModule
@JsName("topLevelSayHello")
external fun sayHello(name: String)
Kotlin 标准库使用的模块系统
Kotlin 以 Kotlin/JS 标准库作为单个文件分发,该文件本身被编译为 UMD 模块, 因此可以使用上述任何模块系统。虽然在大多数 Kotlin/JS 用例中,建议对 kotlin-stdlib-js
使用 Gradle 依赖项, 也在 NPM 上作为 kotlin 包提供。