HTMX 整合
必要相依性:io.ktor:ktor-htmx、io.ktor:ktor-htmx-html、 io.ktor:ktor-server-htmx
程式碼範例: htmx-integration
HTMX 是一個輕量級的 JavaScript 程式庫,可透過 HTML 屬性實現動態的用戶端行為。它支援 AJAX、CSS 轉場、WebSocket 以及 Server-Sent Events 等特性——且無需撰寫 JavaScript。
Ktor 透過一組共用模組為 HTMX 提供實驗性的一級支援,簡化伺服器端與用戶端環境中的整合。這些模組提供了用於處理 HTMX 標頭、使用 Kotlin DSL 定義 HTML 屬性,以及在伺服器端處理特定於 HTMX 的路由邏輯等工具。
模組概觀
Ktor 對 HTMX 的支援分布在三個實驗性模組中:
| 模組 | 描述 |
|---|---|
ktor-htmx | 核心定義與標頭常數 |
ktor-htmx-html | 與 Kotlin HTML DSL 的整合 |
ktor-server-htmx | 針對特定 HTMX 請求的路由支援 |
所有 API 均標記為 @ExperimentalKtorApi,且需要透過 @OptIn(ExperimentalKtorApi::class) 宣告採用。
HTMX 標頭
您可以使用核心 ktor-htmx 模組中的預定義常數,以型別安全的方式存取或設定 HTMX 標頭。這些常數有助於在偵測 HTMX 行為(例如觸發器、歷程記錄還原或內容交換)時避免使用魔術字串。
請求標頭
在應用程式中使用 HxRequestHeaders 物件來讀取或比對 HTMX 請求標頭:
true回應標頭
您可以使用 HxResponseHeaders 物件來存取 HTMX 回應標頭的常數:
交換模式
您可以使用核心 ktor-htmx 模組中的 HxSwap 物件來存取不同 HTMX 交換模式的常數。
HTML DSL 擴充
ktor-htmx-html 模組為 Kotlin 的 HTML DSL 新增了擴充函式,允許您直接向 HTML 元素新增 HTMX 屬性:
@OptIn(ExperimentalKtorApi::class)
html {
body {
button {
attributes.hx {
get = "/data"
target = "#result"
swap = HxSwap.outerHtml
trigger = "click"
}
+"Load Data"
}
}
}上述範例會產生包含 HTMX 屬性的 HTML:
<button hx-get="/api/data" hx-target="#result-div" hx-swap="outerHTML" hx-trigger="click">Load Data</button>伺服器端路由
ktor-server-htmx 模組透過 hx DSL 區塊提供感知 HTMX 的路由功能:
@OptIn(ExperimentalKtorApi::class)
routing {
route("api") {
// 常規路由(同時處理 HTMX 與非 HTMX 請求)
get {
call.respondText("Regular response")
}
// 僅比對 HTMX 請求(存在 HX-Request 標頭)
hx.get {
call.respondText("HTMX response")
}
// 比對具有特定目標的 HTMX 請求
hx {
target("#result-div") {
get {
call.respondText("Response for #result-div")
}
}
// 比對具有特定觸發器的 HTMX 請求
trigger("#load-button") {
get {
call.respondText("Response for #load-button clicks")
}
}
}
}
}這些功能允許您的應用程式依據用戶端傳送的 HTMX 標頭做出不同的回應。
