`hx-trigger`

hx-trigger 属性を使用すると、AJAX リクエストのトリガーを指定できます。トリガー値は以下のいずれかになります。

イベント名（例: "click" または "my-custom-event"）、イベントフィルター、およびイベント修飾子のセット
every <タイミング宣言> 形式のポーリング定義
上記のようなイベントのカンマ区切りリスト

標準イベント

click のような標準イベントは、以下のようにトリガーとして指定できます。

<div hx-get="/clicked" hx-trigger="click">Click Me</div>

標準イベントフィルター

イベントは、イベント名の後に角括弧で囲んだブール値の JavaScript 式でフィルタリングできます。この式が true と評価された場合、イベントはトリガーされます。そうでない場合は無視されます。標準イベントフィルターは eval を必要とします。

<div hx-get="/clicked" hx-trigger="click[ctrlKey]">Control Click Me</div>

このイベントは、event.ctrlKey プロパティが true に設定されている状態で click イベントがトリガーされた場合にトリガーされます。

条件は、グローバル関数または状態を参照することもできます。

<div hx-get="/clicked" hx-trigger="click[checkGlobalState()]">Control Click Me</div>

また、標準の JavaScript 構文を使用して組み合わせることもできます。

<div hx-get="/clicked" hx-trigger="click[ctrlKey&&shiftKey]">Control-Shift Click Me</div>

式で使用されるすべてのシンボルは、最初にトリガーイベントに対して解決され、次にグローバル名前空間に対して解決されることに注意してください。そのため、myEvent[foo] は、最初にイベントで foo という名前のプロパティを探し、次に foo という名前のグローバルシンボルを探します。

標準イベント修飾子

標準イベントには、動作を変更する修飾子を付けることもできます。修飾子は次のとおりです。

once - イベントは一度だけトリガーされます（例：最初のクリック）
changed - 要素の値が変更された場合にのみ、イベントが変更されます。 change はイベントの名前であり、changed は修飾子の名前であることに注意してください。
delay:<タイミング宣言> - イベントがリクエストをトリガーする前に遅延が発生します。イベントが再び発生した場合、遅延はリセットされます。
throttle:<タイミング宣言> - イベントがリクエストをトリガーした後、スロットルが発生します。遅延が完了する前にイベントが再び発生した場合は無視され、要素は遅延の最後にトリガーされます。
from:<拡張 CSS セレクター> - リクエストをトリガーするイベントをドキュメント内の別の要素から発生させることができます（例：ホットキーをサポートするために、body でキーイベントをリッスンする）
- 標準の CSS セレクターは、そのセレクターに一致するすべての要素に解決されます。したがって、from:input はページ上のすべての input をリッスンします。
- CSS セレクターは一度だけ評価され、ページが変更されても再評価されません。動的に追加された要素を検出する必要がある場合は、標準イベントフィルターを使用します。たとえば、hx-trigger="click[event.target.matches('button')] from:body" は、ページ上のすべてのボタンからのクリックイベントをキャッチします。
- ここで拡張 CSS セレクターは、以下の非標準 CSS 値を許可します。
  - document - ドキュメントのイベントをリッスンします
  - window - ウィンドウのイベントをリッスンします
  - closest <CSS セレクター> - 指定された CSS セレクターに一致する、最も近い祖先要素または自身を見つけます
  - find <CSS セレクター> - 指定された CSS セレクターに一致する最も近い子を見つけます
  - next は element.nextElementSibling に解決されます
  - next <CSS セレクター> は、指定された CSS セレクターに一致する最初の要素を DOM を前方スキャンして見つけます。（例：next .error は、error クラスを持つ最も近い次の兄弟要素をターゲットにします）
  - previous は element.previousElementSibling に解決されます
  - previous <CSS セレクター> は、指定された CSS セレクターに一致する最初の要素を DOM を後方スキャンして見つけます。（例：previous .error は、error クラスを持つ最も近い前の兄弟をターゲットにします）
target:<CSS セレクター> - イベントのターゲットで CSS セレクターを使用してフィルタリングできます。たとえば、body でリッスンしますが、子要素のターゲットフィルターを使用することにより、初期化時点で DOM にない可能性のある要素からのトリガーをリッスンする場合に役立ちます。
consume - このオプションが含まれている場合、イベントは親（または親をリッスンしている要素）で他の htmx リクエストをトリガーしません
queue:<キューオプション> - 別のイベントのリクエストが処理中のときにイベントが発生した場合のイベントのキュー方法を決定します。オプションは次のとおりです。
- first - 最初のイベントをキューに入れます
- last - 最後のイベントをキューに入れます（デフォルト）
- all - すべてのイベントをキューに入れます（各イベントのリクエストを発行します）
- none - 新しいイベントをキューに入れません

keyup で検索を実行する検索ボックスの例を次に示します。ただし、検索値が変更され、ユーザーが 1 秒間何も入力していない場合に限ります。

<input name="q"
       hx-get="/search" hx-trigger="keyup changed delay:1s"
       hx-target="#search-results"/>

/search URL からのレスポンスは、ID が search-results の div に追加されます。

非標準イベント

htmx がサポートする追加の非標準イベントがいくつかあります。

load - ロード時にトリガーされます（遅延ロードに役立ちます）
revealed - 要素がビューポートにスクロールされたときにトリガーされます（遅延ロードにも役立ちます）。CSS で overflow-y: scroll のような overflow を使用している場合は、revealed の代わりに intersect once を使用する必要があります。
intersect - 要素が最初にビューポートと交差したときに一度だけ発生します。これは、2 つの追加オプションをサポートしています。
- root:<セレクター> - 交差のルート要素の CSS セレクター
- threshold:<浮動小数点数> - 0.0 から 1.0 までの浮動小数点数。イベントを発生させる交差量を示します。

`HX-Trigger` ヘッダーによるトリガー

HX-Trigger レスポンスヘッダーからイベントを発生させようとしている場合は、from:body 修飾子を使用する必要があります。たとえば、HX-Trigger: my-custom-event のようなヘッダーをレスポンスで送信する場合、要素は発生させるために次のようにする必要があります。

  <div hx-get="/example" hx-trigger="my-custom-event from:body">
    Triggered by HX-Trigger header...
  </div>

これは、ヘッダーが、トリガーする要素とは異なる DOM 階層でイベントをトリガーする可能性があるためです。同様の理由で、多くの場合、body からホットキーをリッスンします。

ポーリング

every <タイミング宣言> 構文を使用すると、要素を定期的にポーリングできます。

<div hx-get="/latest_updates" hx-trigger="every 1s">
  Nothing Yet!
</div>

この例では、1 秒ごとに /latest_updates URL に GET を発行し、結果をこの div の innerHTML にスワップします。

ポーリングにフィルターを追加する場合は、ポーリング宣言の *後* に追加する必要があります。

<div hx-get="/latest_updates" hx-trigger="every 1s [someConditional]">
  Nothing Yet!
</div>

複数のトリガー

カンマで区切って複数のトリガーを指定できます。各トリガーには独自のオプションがあります。

  <div hx-get="/news" hx-trigger="load, click delay:1s"></div>

この例では、ページの読み込み時にすぐに /news が読み込まれ、クリックするたびに 1 秒の遅延で再び読み込まれます。

JavaScript 経由

AJAX リクエストは、JavaScript の htmx.trigger() を介してトリガーすることもできます。

注意事項

hx-trigger は継承されません
hx-trigger は AJAX リクエストなしで使用できます。その場合、htmx:trigger イベントのみが発生します
空白を含む CSS セレクター（例：form input）を from 修飾子または target 修飾子に渡すには、セレクターをかっこまたは中かっこで囲みます（例：from:(form input) または from:closest (form input)）

hx-trigger