開始使用 Kotlin/JS

本教學將示範如何使用 Kotlin/JavaScript (Kotlin/JS) 為瀏覽器建立網頁應用程式。若要建立您的應用程式，請選擇最符合您工作流程的工具：

IntelliJ IDEA：從版本控制複製專案範本並在 IntelliJ IDEA 中進行開發。
Gradle 建置系統：手動為您的專案建立建置檔案，以更好地理解其底層的設定運作方式。

除了針對瀏覽器之外，您還可以使用 Kotlin/JS 編譯其他環境。更多資訊，請參閱執行環境。

在 IntelliJ IDEA 中建立您的應用程式

若要建立您的 Kotlin/JS 網頁應用程式，您可以使用 IntelliJ IDEA 的 Community 或 Ultimate 版本。

設定環境

下載並安裝最新版本的 IntelliJ IDEA。
設定您的 Kotlin 多平台開發環境。

建立您的專案

在 IntelliJ IDEA 中，選擇 File | New | Project from Version Control (檔案 | 新增 | 從版本控制建立專案)。
輸入 Kotlin/JS 範本專案的 URL：
text
```
https://github.com/Kotlin/kmp-js-wizard
```
點擊 Clone (複製)。

設定您的專案

開啟 kmp-js-wizard/gradle/libs.versions.toml 檔案。它包含專案依賴項的版本目錄。
確保 Kotlin 版本與 Kotlin Multiplatform Gradle plugin 的版本相符，這是建立針對 Kotlin/JS 的網頁應用程式所必需的：
text
```
[versions]
kotlin = "2.2.21"

[plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
```
同步 Gradle 檔案 (如果您更新了 libs.versions.toml 檔案)。點擊建置檔案中出現的 Load Gradle Changes (載入 Gradle 變更) 圖示。
或者，點擊 Gradle 工具視窗中的重新整理按鈕。

更多關於多平台專案的 Gradle 設定資訊，請參閱多平台 Gradle DSL 參考資料。

建置並執行應用程式

開啟 src/jsMain/kotlin/Main.kt 檔案。
- src/jsMain/kotlin/ 目錄包含您專案 JavaScript 目標的主要 Kotlin 原始程式檔。
- Main.kt 檔案包含使用 kotlinx.browser API 在瀏覽器頁面上渲染「Hello, Kotlin/JS!」的程式碼。
點擊 main() 函式中的 Run (執行) 圖示來執行程式碼。

網頁應用程式會自動在您的瀏覽器中開啟。或者，當執行完成後，您可以在瀏覽器中開啟以下 URL：

text

   http://localhost:8080/

您可以看到網頁應用程式：

應用程式輸出

首次執行應用程式後，IntelliJ IDEA 會在頂部工具列建立其對應的執行設定 (jsMain [js])：

Gradle 執行設定

在 IntelliJ IDEA Ultimate 中，您可以使用 JS 除錯器直接從 IDE 除錯程式碼。

啟用持續建置

當您進行變更時，Gradle 可以自動重建您的專案：

在執行設定清單中選擇 jsMain [js]，然後點擊 More Actions (更多動作) | Edit (編輯)。
在 Run/Debug Configurations (執行/除錯設定) 對話框中，在 Run (執行) 欄位內輸入 jsBrowserDevelopmentRun --continuous。
點擊 OK (確定)。

現在，當您執行應用程式並進行任何變更時，只要您儲存 (/) 或變更類別檔案， Gradle 就會自動執行專案的增量建置並熱重新載入瀏覽器。

修改應用程式

修改應用程式以新增一個計算單字中字母數量的功能。

新增輸入元素

在 src/jsMain/kotlin/Main.kt 檔案中，透過擴充函式新增一個 HTML input 元素以讀取使用者輸入：

kotlin

// 取代 Element.appendMessage() 函式
fun Element.appendInput() {
    val input = document.createElement("input")
    appendChild(input)
}

在 main() 中呼叫 appendInput() 函式。它會在頁面上顯示一個輸入元素：

kotlin

fun main() {
    // 取代 document.body!!.appendMessage(message)
    document.body?.appendInput()
}

再次執行應用程式。
您的應用程式會像這樣：

新增輸入事件處理

在 appendInput() 函式內部新增一個監聽器以讀取輸入值並對變更做出反應：

kotlin

// 取代目前的 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 回呼。它會讀取並處理輸入值：

kotlin

fun main() {
    // 取代 document.body?.appendInput()
    document.body?.appendInput(onChange = { println(it) })
}

新增輸出元素

透過定義一個擴充函式來新增一個文字元素以顯示輸出，該函式會建立一個段落：

kotlin

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

在 main() 中呼叫 appendTextContainer() 函式。它會建立輸出元素：

kotlin

fun main() {
    // 為我們的輸出建立一個文字容器
    // 取代 val message = Message(topic = "Kotlin/JS", content = "Hello!")
    val output = document.body?.appendTextContainer()

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

處理輸入以計算字母數量

透過移除空白字元並顯示帶有字母數量的輸出來處理輸入。

將以下程式碼新增到 main() 函式內的 appendInput() 函式中：

kotlin

fun main() {
    // 為我們的輸出建立一個文字容器
    val output = document.body?.appendTextContainer()

    // 讀取輸入值
    // 取代目前的 appendInput() 函式
    document.body?.appendInput(onChange = { name ->
        name.replace(" ", "").let {
            output?.textContent = "您的姓名包含 ${it.length} 個字母"
        }
    })
}

從上面的程式碼來看：

replace() 函式會移除名稱中的空白字元。
let{} 作用域函式在物件上下文 (object context) 中執行函式。
字串模板 (${it.length}) 透過在其前面加上一個錢號 ($) 並將其括在花括號 ({}) 中，將單字的長度插入到字串中。而 it 是 lambda 參數的預設名稱。

執行應用程式

執行應用程式。
輸入您的姓名。
按下 (輸入鍵)。

您可以看到結果：

應用程式輸出

處理輸入以計算唯一字母的數量

作為額外練習，我們來處理輸入以計算並顯示單字中唯一字母的數量：

在 src/jsMain/kotlin/Main.kt 檔案中，為 String 新增 .countDistinctCharacters() 擴充函式：
kotlin
```
fun String.countDistinctCharacters() = lowercase().toList().distinct().count()
```
從上面的程式碼來看：
- .lowercase() 函式會將名稱轉換為小寫。
- toList() 函式會將輸入字串轉換為字元列表。
- distinct() 函式會從單字中選擇唯一的字元。
- count() 函式會計算唯一的字元。

在 main() 中呼叫 .countDistinctCharacters() 函式。它會計算您姓名中唯一字母的數量：

kotlin

fun main() {
    // 為我們的輸出建立一個文字容器
    val output = document.body?.appendTextContainer()

    // 讀取輸入值
    document.body?.appendInput(onChange = { name ->
        name.replace(" ", "").let {
            // 印出唯一字母的數量
            // 取代 output?.textContent = "您的姓名包含 ${it.length} 個字母"
            output?.textContent = "您的姓名包含 ${it.countDistinctCharacters()} 個唯一字母"
        }
    })
}

按照步驟執行應用程式並輸入您的姓名。

您可以看到結果：

應用程式輸出

使用 Gradle 建立您的應用程式

在本節中，您將學習如何使用 Gradle 手動建立 Kotlin/JS 應用程式。

Gradle 是 Kotlin/JS 和 Kotlin Multiplatform 專案的預設建置系統。它也常被用於 Java、Android 和其他生態系統中。

建立專案檔案

確保您使用的 Gradle 版本與 Kotlin Gradle plugin (KGP) 相容。請參閱相容性表格以獲取更多詳細資訊。
使用您的檔案總管、命令列或任何您偏好的工具，為您的專案建立一個空目錄。

在專案目錄中，建立一個 build.gradle.kts 檔案，內容如下：

KotlinGroovy

kotlin

// build.gradle.kts
plugins {
    kotlin("multiplatform") version "2.2.21"
}

repositories {
    mavenCentral()
}

kotlin {
    js {
        // 使用 browser() 在瀏覽器中執行，或使用 nodejs() 在 Node.js 中執行
        browser()
        binaries.executable()
    }
}

groovy

// build.gradle
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.2.21'
}

repositories {
    mavenCentral()
}

kotlin {
    js {
        // 使用 browser() 在瀏覽器中執行，或使用 nodejs() 在 Node.js 中執行
        browser()
        binaries.executable()
    }
}

您可以使用不同的執行環境，例如 browser() 或 nodejs()。每個環境都會定義您的程式碼執行位置，並決定 Gradle 如何在專案中產生任務名稱。

在專案目錄中，建立一個空的 settings.gradle.kts 檔案。
在專案目錄中，建立一個 src/jsMain/kotlin 目錄。
在 src/jsMain/kotlin 目錄中，新增一個 hello.kt 檔案，內容如下：
kotlin
```
fun main() {
    println("Hello, Kotlin/JS!")
}
```
依照慣例，所有原始碼都位於 src/<target name>[Main|Test]/kotlin 目錄中：
- Main 是原始碼的位置。
- Test 是測試的位置。
- <target name> 對應於目標平台 (在本例中為 js)。

針對 browser 環境

如果您正在使用 browser 環境，請遵循以下步驟。如果您正在使用 nodejs 環境，請跳到建置並執行專案一節。

在專案目錄中，建立一個 src/jsMain/resources 目錄。

在 src/jsMain/resources 目錄中，建立一個 index.html 檔案，內容如下：

html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>應用程式標題</title>
</head>
<body>
    <script src="$NAME_OF_YOUR_PROJECT_DIRECTORY.js"></script>
</body>
</html>

將 <$NAME_OF_YOUR_PROJECT_DIRECTORY> 佔位符替換為您的專案目錄名稱。

建置並執行專案

若要建置專案，請從專案根目錄執行以下命令：

bash

# 針對瀏覽器
gradle jsBrowserDevelopmentRun

# 或者

# 針對 Node.js
gradle jsNodeDevelopmentRun

如果您正在使用 browser 環境，您會看到瀏覽器開啟 index.html 檔案並在瀏覽器主控台中印出「Hello, Kotlin/JS!」。您可以使用 / 命令開啟主控台。

應用程式輸出

如果您正在使用 nodejs 環境，您會看到終端機印出「Hello, Kotlin/JS!」。

應用程式輸出

在 IDE 中開啟專案

您可以在任何支援 Gradle 的 IDE 中開啟您的專案。

如果您使用 IntelliJ IDEA：

選擇 File | Open (檔案 | 開啟)。
尋找專案目錄。
點擊 Open (開啟)。

IntelliJ IDEA 會自動偵測它是否是一個 Kotlin/JS 專案。如果您遇到專案問題， IntelliJ IDEA 會在 Build (建置) 窗格中顯示錯誤訊息。

基本類型

建構器

Spring

使用 Spring Boot 建立一個包含資料庫的 RESTful Web 服務

Java 遷移至 Kotlin 指南

C 互通

Objective-C 互通

記憶體管理器

參考與提示

用於 JS 平台的 Kotlin

概覽

執行 Dokka

輸出格式

最小化心智複雜度

開始使用 Kotlin/JS

在 IntelliJ IDEA 中建立您的應用程式

設定環境

建立您的專案

設定您的專案

建置並執行應用程式

啟用持續建置

修改應用程式

新增輸入元素

新增輸入事件處理

新增輸出元素

處理輸入以計算字母數量

執行應用程式

處理輸入以計算唯一字母的數量

使用 Gradle 建立您的應用程式

建立專案檔案

建置並執行專案

在 IDE 中開啟專案

接下來是什麼？

使用 Spring Boot 建立一個包含資料庫的 RESTful Web 服務

開始使用 Kotlin/JS ​

在 IntelliJ IDEA 中建立您的應用程式 ​

設定環境 ​

建立您的專案 ​

設定您的專案 ​

建置並執行應用程式 ​

啟用持續建置 ​

修改應用程式 ​

新增輸入元素 ​

新增輸入事件處理 ​

新增輸出元素 ​

處理輸入以計算字母數量 ​

執行應用程式 ​

處理輸入以計算唯一字母的數量 ​

使用 Gradle 建立您的應用程式 ​

建立專案檔案 ​

建置並執行專案 ​

在 IDE 中開啟專案 ​

接下來是什麼？ ​

開始使用 Kotlin/JS

在 IntelliJ IDEA 中建立您的應用程式

設定環境

建立您的專案

設定您的專案

建置並執行應用程式

啟用持續建置

修改應用程式

新增輸入元素

新增輸入事件處理

新增輸出元素

處理輸入以計算字母數量

執行應用程式

處理輸入以計算唯一字母的數量

使用 Gradle 建立您的應用程式

建立專案檔案

建置並執行專案

在 IDE 中開啟專案

接下來是什麼？