HTMX 集成
所需依赖项:io.ktor:ktor-htmx、io.ktor:ktor-htmx-html、 io.ktor:ktor-server-htmx
代码示例: htmx-integration
HTMX 是一个轻量级 JavaScript 库,可通过 HTML 属性实现动态客户端行为。它支持诸如 AJAX、CSS 过渡(transitions)、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 行为时避免使用魔术字符串(magic strings)。
请求标头
使用 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 标头作出不同的响应。
