7.2.4 使用来自 npm 的依赖

原文链接: https://kotlinlang.org/docs/using-packages-from-npm.html

7.2.4 使用来自 npm 的依赖

在 Kotlin/JS 项目中，所有依赖都可以通过 Gradle 插件来管理。这包括 kotlinx.coroutines、kotlinx.serialization 或 ktor-client 这样的 Kotlin/Multiplatform 库。

如果要依赖来自 npm 的 JavaScript 包，Gradle DSL 暴露了一个 npm 函数，让你可以指定想从 npm 导入的包。我们来看一个名为 is-sorted 的 NPM 包的导入。

Gradle 构建文件中相应的部分如下所示：

1
2
3
4

dependencies {
    // ...
    implementation(npm("is-sorted", "1.0.5"))
}

由于 JavaScript 模块通常是动态类型的，而 Kotlin 是静态类型语言，你需要提供某种适配器。在 Kotlin 中，这类适配器称为外部声明。对于只提供一个函数的 is-sorted 包，这个声明写起来很短。在源代码文件夹中创建一个名为 is-sorted.kt 的新文件，并填入以下内容：

1
2
3

@JsModule("is-sorted")
@JsNonModule
external fun <T> sorted(a: Array<T>): Boolean

请注意，如果你以 CommonJS 作为目标，需要相应地调整 @JsModule 和 @JsNonModule 注解。

现在这个 JavaScript 函数就可以像普通的 Kotlin 函数一样使用了。由于我们在头文件中提供了类型信息（而不是简单地把参数和返回类型定义为 dynamic），因此也能获得完整的编译器支持和类型检查。

1
2
3

console.log("Hello, Kotlin/JS!")
console.log(sorted(arrayOf(1,2,3)))
console.log(sorted(arrayOf(3,1,2)))

无论是在浏览器还是 Node.js 中运行这三行代码，输出都表明对 sorted 的调用被正确地映射到了 is-sorted 包所导出的函数：

1
2
3

Hello, Kotlin/JS!
true
false

由于 JavaScript 生态在一个包中有多种暴露函数的方式（例如通过具名导出或默认导出），其他 npm 包的外部声明可能需要稍作调整的结构。

要了解如何编写声明，请参阅从 Kotlin 调用 JavaScript。