6.2.2.2 Kotlin/JS 入门

6 分钟阅读

原文链接: https://kotlinlang.org/docs/js-get-started.html

6.2.2.2 Kotlin/JS 入门

本教程演示如何使用 Kotlin/JavaScript (Kotlin/JS) 为浏览器创建 Web 应用。要创建应用，请选择最适合你工作方式的工具：

IntelliJ IDEA：从版本控制克隆项目模板，并在 IntelliJ IDEA 中进行开发。
Gradle 构建系统：手动创建项目的构建文件，以更好地理解底层配置的工作方式。

提示： 除了面向浏览器之外，用 Kotlin/JS 你还可以为其他环境编译。更多信息请参阅执行环境。

在 IntelliJ IDEA 中创建应用

要创建 Kotlin/JS Web 应用，你可以使用 IntelliJ IDEA。

搭建环境

下载并安装最新版本的 IntelliJ IDEA。
安装 Kotlin Multiplatform IDE 插件（不要与 Kotlin Multiplatform Gradle 插件混淆）。

创建项目

在 IntelliJ IDEA 中，选择 File | New | Project from Version Control。
输入 Kotlin/JS 模板项目的 URL：

1
   https://github.com/Kotlin/kmp-js-wizard

点击 Clone。

配置项目

打开 kmp-js-wizard/gradle/libs.versions.toml 文件。它包含项目依赖的版本目录。
确认 Kotlin 版本与 Kotlin Multiplatform Gradle 插件的版本一致，这是创建面向 Kotlin/JS 的 Web 应用所必需的：

1
2
3
4
5
   [versions]
   kotlin = "2.4.20"

   [plugins]
   kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }

同步 Gradle 文件（如果你更新了 libs.versions.toml 文件）。点击构建文件中出现的 Load Gradle Changes 图标。

Load Gradle changes 按钮

或者，点击 Gradle 工具窗口中的刷新按钮。

关于多平台项目 Gradle 配置的更多信息，请参阅 Multiplatform Gradle DSL 参考。

构建并运行应用

打开 src/jsMain/kotlin/Main.kt 文件。

src/jsMain/kotlin/ 目录包含项目 JavaScript 目标的主要 Kotlin 源文件。
Main.kt 文件中的代码使用 kotlinx.browser API 在浏览器页面上渲染 “Hello, Kotlin/JS!"。

点击 main() 函数中的 Run 图标来运行代码。

运行应用

Web 应用会自动在浏览器中打开。或者，运行完成后，你可以在浏览器中打开以下 URL：

1
   http: // http://localhost:8080/

你可以看到这个 Web 应用：

应用输出

首次运行应用后，IntelliJ IDEA 会在顶部栏创建对应的运行配置（jsMain [js]）：

Gradle 运行配置

在使用 Ultimate 订阅的 IntelliJ IDEA 中，你可以使用 JS 调试器直接在 IDE 中调试代码。 {style=“tip”}

启用持续构建

Gradle 可以在你每次做出更改时自动重新构建项目：

在运行配置列表中选择 jsMain [js]，然后点击 More Actions | Edit。

Gradle 编辑运行配置

在 Run/Debug Configurations 对话框的 Run 字段中输入 jsBrowserDevelopmentRun --continuous。

持续运行配置

点击 OK。

现在，当你运行应用并做出任何更改时，Gradle 会自动执行增量构建，并在你保存（Ctrl + S/Cmd + S）或更改类文件时热重载浏览器。

修改应用

修改应用，添加一个统计单词中字母数量的功能。

添加输入元素

在 src/jsMain/kotlin/Main.kt 文件中，通过一个扩展函数添加 HTML 输入元素以读取用户输入：

1
2
3
4
5
   // 替换 Element.appendMessage() 函数
   fun Element.appendInput() {
       val input = document.createElement("input")
       appendChild(input)
   }

在 main() 中调用 appendInput() 函数。它会在页面上显示一个输入元素：

1
2
3
4
   fun main() {
       // 替换 document.body!!.appendMessage(message)
       document.body?.appendInput()
   }

再次运行应用。

你的应用看起来是这样的：

带输入元素的应用

添加输入事件处理

在 appendInput() 函数中添加一个监听器，以读取输入值并对变化作出反应：

1
2
3
4
5
6
7
8
9
   // 替换当前的 appendInput() 函数
    fun Element.appendInput(onChange: (String) -> Unit = {}) {
        val input = document.createElement("input").apply {
            addEventListener("change") { event ->
                onChange(event.target.unsafeCast<HTMLInputElement>().value)
            }
        }
        appendChild(input)
    }

按照 IDE 的建议导入 HTMLInputElement 依赖。

导入依赖

在 main() 中调用 onChange 回调。它读取并处理输入值：

1
2
3
4
    fun main() {
        // 替换 document.body?.appendInput()
        document.body?.appendInput(onChange = { println(it) })
    }

添加输出元素

通过定义一个创建段落的扩展函数，添加一个用于显示输出的文本元素：

1
2
3
    fun Element.appendTextContainer(): Element {
        return document.createElement("p").also(::appendChild)
    }

在 main() 中调用 appendTextContainer() 函数。它会创建输出元素：

1
2
3
4
5
6
7
8
    fun main() {
        // 为我们的输出创建一个文本容器
        // 替换 val message = Message(topic = "Kotlin/JS", content
        val output = document.body?.appendTextContainer()

        // 读取输入值
        document.body?.appendInput(onChange = { println(it) })
    }

处理输入以统计字母数

处理输入：去除空白字符，并显示带有字母数量的输出。

在 main() 函数内的 appendInput() 函数中添加以下代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
fun main() {
    // 为我们的输出创建一个文本容器
    val output = document.body?.appendTextContainer()

    // 读取输入值
    // 替换当前的 appendInput() 函数
    document.body?.appendInput(onChange = { name ->
        name.replace(" ", "").let {
            output?.textContent = "Your name contains ${it.length} letters"
        }
    })
}

从上面的代码可以看到：

replace() 函数会移除姓名中的空格。
let{} 作用域函数会在对象上下文中运行函数。
字符串模板（${it.length}）通过在变量前加美元符号（$）并用花括号（{}）括起来，把单词长度插入字符串中。而 it 是 lambda 参数的默认名称。

运行应用

运行应用。
输入你的名字。
按 Enter。

你可以看到结果：

应用输出

处理输入以统计不同字母数

作为额外练习，让我们处理输入，计算并显示单词中不同字母的数量：

在 src/jsMain/kotlin/Main.kt 文件中，为 String 添加 .countDistinctCharacters() 扩展函数：

1
   fun String.countDistinctCharacters() = lowercase().toList().distinct().count()

从上面的代码可以看到：

.lowercase() 函数把名字转换为小写。
toList() 函数把输入字符串转换为字符列表。
distinct() 函数只选取单词中不重复的字符。
count() 函数统计这些不同字符的数量。

在 main() 中调用 .countDistinctCharacters() 函数。它会统计你名字中不同字母的数量：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    fun main() {
        // 为我们的输出创建一个文本容器
        val output = document.body?.appendTextContainer()

        // 读取输入值
        document.body?.appendInput(onChange = { name ->
            name.replace(" ", "").let {
                // 打印不同字母的数量
                // 替换 output?.textContent = "Your name contains $
                output?.textContent = "Your name contains ${it.countDistinctCharacters()} unique letters"
            }
        })
   }

按照步骤运行应用并输入你的名字。

你可以看到结果：

应用输出

使用 Gradle 创建应用

在本节中，你可以学习如何使用 Gradle 手动创建 Kotlin/JS 应用。

Gradle 是 Kotlin/JS 和 Kotlin Multiplatform 项目的默认构建系统。它也常用于 Java、Android 以及其他生态。

创建项目文件

确保你使用的 Gradle 版本与 Kotlin Gradle 插件 (KGP) 兼容。更多细节请参阅兼容性表。
使用文件管理器、命令行或你喜欢的任何工具为项目创建一个空目录。
在项目目录中创建内容如下的 build.gradle.kts 文件：

Kotlin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
   // build.gradle.kts
   plugins {
       kotlin("multiplatform") version "2.4.20"
   }

   repositories {
       mavenCentral()
   }

   kotlin {
       js {
           // 在浏览器中运行用 browser()，在 Node.js 中运行用 nodejs()
           browser()
           binaries.executable()
       }
   }

Groovy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
   // build.gradle
   plugins {
       id 'org.jetbrains.kotlin.multiplatform' version '2.4.20'
   }

   repositories {
       mavenCentral()
   }

   kotlin {
       js {
           // 在浏览器中运行用 browser()，在 Node.js 中运行用 nodejs()
           browser()
           binaries.executable()
       }
   }

你可以使用不同的执行环境，例如 browser() 或 nodejs()。每个环境都定义了代码的运行位置，并决定 Gradle 在项目中生成任务名称的方式。 {style=“note”}

在项目目录中创建一个空的 settings.gradle.kts 文件。
在项目目录中创建 src/jsMain/kotlin 目录。
在 src/jsMain/kotlin 目录中，添加内容如下的 hello.kt 文件：

1
2
3
   fun main() {
       println("Hello, Kotlin/JS!")
   }

按照约定，所有源代码都位于 src/<target name>[Main|Test]/kotlin 目录中：

Main 是源代码的位置。
Test 是测试的位置。
<target name> 对应目标平台（在本例中是 js）。

对于 browser 环境

如果你使用的是 browser 环境，请继续以下步骤。如果你使用的是 nodejs 环境，请前往构建并运行项目一节。 {style=“note”}

在项目目录中创建 src/jsMain/resources 目录。
在 src/jsMain/resources 目录中，创建内容如下的 index.html 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <title>Application title</title>
   </head>
   <body>
       <script src="$NAME_OF_YOUR_PROJECT_DIRECTORY.js"></script>
   </body>
   </html>

把 <$NAME_OF_YOUR_PROJECT_DIRECTORY> 占位符替换为你的项目目录名。

构建并运行项目

要构建项目，请在项目根目录下运行以下命令：

1
2
3
4
5
6
7
# For browser
gradle jsBrowserDevelopmentRun

# OR

# For Node.js
gradle jsNodeDevelopmentRun

如果你使用的是 browser 环境，可以看到浏览器会打开 index.html 文件，并向浏览器控制台打印 "Hello, Kotlin/JS!"。你可以使用 Ctrl + Shift + J/Cmd + Option + J 命令打开控制台。

应用输出

如果你使用的是 nodejs 环境，可以看到终端会打印 "Hello, Kotlin/JS!"。

应用输出

在 IDE 中打开项目

你可以在任何支持 Gradle 的 IDE 中打开项目。

如果你使用 IntelliJ IDEA：

选择 File | Open。
找到项目目录。
点击 Open。

IntelliJ IDEA 会自动检测它是否是 Kotlin/JS 项目。如果项目遇到问题，IntelliJ IDEA 会在 Build 面板中显示错误信息。

接下来学什么？

最后修改 September 13, 2026: 更新C和Cpp以及新增Kotlin和SwiftUI (d20dcaaa6)