開始使用 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:
texthttps://github.com/Kotlin/kmp-js-wizard點擊 Clone。
設定您的專案
開啟
kmp-js-wizard/gradle/libs.versions.toml檔案。它包含專案相依性的版本目錄。確保 Kotlin 版本與 Kotlin Multiplatform Gradle 外掛程式的版本相符,這是建立以 Kotlin/JS 為目標的 Web 應用程式所必需的:
toml[versions] kotlin = "2.4.21" [plugins] kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }同步 Gradle 檔案(如果您更新了
libs.versions.toml檔案)。點擊建置檔案中出現的 Load Gradle Changes 圖示。
或者,點擊 Gradle 工具視窗中的重新整理按鈕。
如需有關多平台專案 Gradle 設定的更多資訊, 請參閱 Multiplatform Gradle DSL 參考。
建置並執行應用程式
開啟
src/jsMain/kotlin/Main.kt檔案。src/jsMain/kotlin/目錄包含專案中 JavaScript 目標的主要 Kotlin 原始碼檔案。Main.kt檔案包含使用kotlinx.browserAPI 在瀏覽器頁面上轉譯 "Hello, Kotlin/JS!" 的程式碼。
點擊
main()函式中的 Run 圖示以執行程式碼。
Web 應用程式將在您的瀏覽器中自動開啟。 或者,在執行完成後,您也可以在瀏覽器中開啟以下 URL:
http://localhost:8080/您可以看到該 Web 應用程式:

首次執行應用程式後,IntelliJ IDEA 會在頂端列建立其對應的執行配置 (jsMain [js]):

在擁有 Ultimate 訂閱的 IntelliJ IDEA 中, 您可以使用 JS 偵錯工具 直接從 IDE 偵錯程式碼。
啟用持續建置
每當您進行變更時,Gradle 可以自動重新建置您的專案:
在執行配置清單中選取 jsMain [js],然後點擊 More Actions | Edit。

在 Run/Debug Configurations 對話方塊中,於 Run 欄位內輸入
jsBrowserDevelopmentRun --continuous。
點擊 OK。
現在,當您執行應用程式並進行任何變更時, 每當您儲存(Ctrl + S/Cmd + S)或變更類別檔案時, Gradle 都會自動對專案執行累加建置並對瀏覽器進行熱重新載入(hot-reload)。
修改應用程式
修改應用程式以新增計算單字中字母數量功能。
新增 input 元素
在
src/jsMain/kotlin/Main.kt檔案中, 透過擴充函式新增一個 HTML input 元素以讀取使用者輸入:kotlin// 取代 Element.appendMessage() 函式 fun Element.appendInput() { val input = document.createElement("input") appendChild(input) }在
main()中呼叫appendInput()函式。它會在頁面上顯示一個 input 元素:kotlinfun main() { // 取代 document.body!!.appendMessage(message) document.body?.appendInput() }您的應用程式外觀如下:

新增 input 事件處理
在
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回呼。它會讀取並處理輸入值:kotlinfun main() { // 取代 document.body?.appendInput() document.body?.appendInput(onChange = { println(it) }) }
新增 output 元素
透過定義建立段落的擴充函式來新增用於顯示輸出的文字元素:
kotlinfun Element.appendTextContainer(): Element { return document.createElement("p").also(::appendChild) }在
main()中呼叫appendTextContainer()函式。它會建立輸出元素:kotlinfun main() { // 為我們的輸出建立文字容器 // 取代 val message = Message(topic = "Kotlin/JS", content = "Hello!") val output = document.body?.appendTextContainer() // 讀取輸入值 document.body?.appendInput(onChange = { println(it) }) }
處理輸入以計算字母數量
透過移除空白字元並顯示包含字母數量的輸出來處理輸入。
在 main() 函式內的 appendInput() 函式中新增以下程式碼:
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()擴充函式:kotlinfun String.countDistinctCharacters() = lowercase().toList().distinct().count()在上述程式碼中:
.lowercase()函式將名字轉換為小寫。toList()函式將輸入字串轉換為字元清單。distinct()函式僅選取單字中不重複的字元。count()函式計算不重複字元的數量。
在
main()中呼叫.countDistinctCharacters()函式。它會計算您名字中不重複字母的數量:kotlinfun main() { // 為我們的輸出建立文字容器 val output = document.body?.appendTextContainer() // 讀取輸入值 document.body?.appendInput(onChange = { name -> name.replace(" ", "").let { // 印出不重複字母的數量 // 取代 output?.textContent = "Your name contains ${it.length} letters" output?.textContent = "Your name contains ${it.countDistinctCharacters()} unique letters" } }) }依照步驟執行應用程式並輸入您的名字。
您可以看到結果:

使用 Gradle 建立您的應用程式
在本節中,您可以了解如何使用 Gradle 手動建立 Kotlin/JS 應用程式。
Gradle 是 Kotlin/JS 和 Kotlin Multiplatform 專案的預設建構系統。 它也常廣泛用於 Java、Android 和其他生態系統中。
建立專案檔案
請確保使用與 Kotlin Gradle 外掛程式 (KGP) 相容的 Gradle 版本。 詳情請參閱相容性表格。
使用檔案管理員、命令列或任何偏好的工具為您的專案建立一個空目錄。
在專案目錄中,建立具有以下內容的
build.gradle.kts檔案:kotlin// build.gradle.kts plugins { kotlin("multiplatform") version "2.4.21" } repositories { mavenCentral() } kotlin { js { // 使用 browser() 在瀏覽器中執行,或使用 nodejs() 在 Node.js 中執行 browser() binaries.executable() } }groovy// build.gradle plugins { id 'org.jetbrains.kotlin.multiplatform' version '2.4.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檔案:kotlinfun 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>Application title</title> </head> <body> <script src="$NAME_OF_YOUR_PROJECT_DIRECTORY.js"></script> </body> </html>將
<$NAME_OF_YOUR_PROJECT_DIRECTORY>占位符號替換為您的專案目錄名稱。
建置並執行專案
若要建置專案,請從專案根目錄執行以下指令:
# 對於瀏覽器
gradle jsBrowserDevelopmentRun
# 或
# 對於 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 窗格中顯示錯誤訊息。
後續步驟
- 設定您的 Kotlin/JS 專案。
- 了解如何偵錯 Kotlin/JS 應用程式。
- 了解如何使用 Kotlin/JS 編寫與執行測試。
- 了解如何為真實世界的 Kotlin/JS 專案編寫 Gradle 建置指令碼。
- 進一步閱讀關於 Gradle 建置系統。
