Skip to content
Experimental

HTMXの統合

必要な依存関係: io.ktor:ktor-htmx, io.ktor:ktor-htmx-html, io.ktor:ktor-server-htmx

コード例: htmx-integration

HTMX は、HTML属性を使用して動的なクライアント側の動作を可能にする軽量なJavaScriptライブラリです。JavaScriptを記述することなく、AJAX、CSSトランジション、WebSocket、Server-Sent Eventsなどの機能をサポートします。

Ktorは、サーバーとクライアントの両方のコンテキストで統合を簡素化する一連の共有モジュールを通じて、HTMXに対する実験的なファーストクラスのサポートを提供します。これらのモジュールは、HTMXヘッダーの操作、Kotlin DSLを使用したHTML属性の定義、サーバー上でのHTMX固有のルーティングロジックの処理を行うためのツールを提供します。

モジュールの概要 ​

KtorのHTMXサポートは、3つの実験的モジュールで利用できます。

モジュール説明
ktor-htmxコア定義とヘッダー定数
ktor-htmx-htmlKotlin HTML DSLとの統合
ktor-server-htmxHTMX固有のリクエストに対するルーティングサポート

すべてのAPIには @ExperimentalKtorApi のマークが付けられており、@OptIn(ExperimentalKtorApi::class) によるオプトインが必要です。

HTMXヘッダー ​

コアの ktor-htmx モジュールの定義済み定数を使用して、型安全な方法でHTMXヘッダーにアクセスまたは設定できます。これらの定数を使用することで、トリガー、履歴の復元、コンテンツの置換(スワップ)などのHTMXの動作を検出する際にマジックストリングを回避できます。

リクエストヘッダー ​

アプリケーションでHTMXリクエストヘッダーを読み取ったりマッチングしたりするには、HxRequestHeaders オブジェクトを使用します。

HxRequestHeaders.Request
HTMXリクエストの場合は常に true
HxRequestHeaders.Target
ターゲット要素のID
HxRequestHeaders.Trigger
トリガーされた要素のID
HxRequestHeaders.TriggerName
トリガーされた要素の名前
HxRequestHeaders.Boosted
hx-boost経由のリクエストであることを示す
HxRequestHeaders.CurrentUrl
現在のブラウザURL
HxRequestHeaders.HistoryRestoreRequest
履歴の復元用
HxRequestHeaders.Prompt
hx-promptに対するユーザーの応答

レスポンスヘッダー ​

HTMXレスポンスヘッダーの定数にアクセスするには、HxResponseHeaders オブジェクトを使用できます。

HxResponseHeaders.Location
ページをリロードしないクライアント側のリダイレクト
HxResponseHeaders.PushUrl
履歴スタックにURLをプッシュ
HxResponseHeaders.Redirect
クライアント側のリダイレクト
HxResponseHeaders.Refresh
ページ全体の完全なリフレッシュを強制
HxResponseHeaders.ReplaceUrl
現在のURLを置換
HxResponseHeaders.Reswap
レスポンスのスワップ方法を制御
HxResponseHeaders.Retarget
コンテンツ更新のターゲットを更新
HxResponseHeaders.Reselect
スワップするレスポンスの一部を選択
HxResponseHeaders.Trigger
クライアント側のイベントをトリガー
HxResponseHeaders.TriggerAfterSettle
セトル(整定)後にイベントをトリガー
HxResponseHeaders.TriggerAfterSwap
スワップ後にイベントをトリガー

スワップモード ​

コアの ktor-htmx モジュールの HxSwap オブジェクトを使用して、さまざまなHTMXスワップモードの定数にアクセスできます。

HxSwap.innerHtml
内部HTMLを置換(デフォルト)
HxSwap.outerHtml
要素全体を置換
HxSwap.textContent
テキストコンテンツのみを置換
HxSwap.beforeBegin
ターゲット要素の直前に挿入
HxSwap.afterBegin
最初の子要素として挿入
HxSwap.beforeEnd
最後の子要素として挿入
HxSwap.afterEnd
ターゲット要素の直後に挿入
HxSwap.delete
ターゲット要素を削除
HxSwap.none
コンテンツを追加しない

HTML DSL拡張 ​

ktor-htmx-html モジュールは、KotlinのHTML DSLに拡張関数を追加し、HTML要素に直接HTMX属性を追加できるようにします。

kotlin
@OptIn(ExperimentalKtorApi::class)
html {
    body {
        button {
            attributes.hx {
                get = "/data"
                target = "#result"
                swap = HxSwap.outerHtml
                trigger = "click"
            }
            +"Load Data"
        }
    }
}

上記の例は、HTMX属性を持つHTMLを生成します。

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を認識するルーティングを提供します。

kotlin
@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ヘッダーに応じて、アプリケーションが異なる応答を返すことができるようになります。