Hotwire / Turbo ➡️ htmx 迁移指南

本指南旨在提供 Hotwire 等效功能在 htmx 中的常见实践方法。

htmx 专注于一组透明、高度灵活的 HTML 扩展，使其作为超文本达到逻辑终点。
Hotwire / Turbo 专注于开箱即用的流畅体验，但更具规范性且灵活性较低。

Turbo Drive

<body hx-boost="true"> 可启用类似 Turbo Drive 的体验。参见：hx-boost
与 Turbo Drive 一样，如果用户禁用了 JavaScript，hx-boost 仍将继续工作。参见：渐进增强
hx-boost="false" 等同于 data-turbo="false"，用于在特定链接或表单上禁用加速。参见：手册
表单提交后重定向 (302, 303, 307, 3xx) hx-target="body" hx-swap="outerHTML" hx-push-url="true" 参见：手册
表单提交时禁用按钮参见：手册
- 仅禁用按钮，因为 <form> 不会提交禁用的字段。参见：MDN：禁用属性

addEventListener("submit", (event) => {
    event.target.querySelectorAll("button").forEach(node => { node.disabled = true })
})
addEventListener("htmx:afterOnLoad", (event) => {
    event.target.querySelectorAll("button").forEach(node => { node.disabled = false })
})

或者，可以使用 hx-on：
- hx-on:submit= 'event.target.querySelectorAll("button").forEach(node => { node.disabled = true })'
- hx-on:htmx:afterOnLoad= 'event.target.querySelectorAll("button").forEach(node => { node.disabled = false })'
或者，可以使用 hyperscript：_="on submit toggle @disabled <button/> in me until htmx:afterOnLoad" 参见：手册

Turbo Frames

htmx 将所有 "Turbo Frames" 的概念整合到基础属性中。无需 <turbo-frame>。
延迟加载：hx-trigger="load, submit" 参见：手册

Turbo Streams

htmx 将所有 "Turbo Streams" 的概念整合到基础属性中。无需 <turbo-stream>，无需 <template>。
注意：Turbo Streams 可以在页面任意位置执行多个操作（类似于 hx-select-oob 和 hx-swap-oob），而 Turbo Frames 仅更新包裹在 <turbo-frame> .. </turbo-frame> 中的内容。

事件

拦截或暂停事件。htmx:config-request 等同于 turbo:before-fetch-request 参见：手册
- htmx:config-request 与 htmx:configRequest 相同参见：事件命名

document.body.addEventListener('htmx:configRequest', (event) => {
    event.detail.headers['Authorization'] = `Bearer ${token}`
})

或者，使用 hx-trigger 条件：hx-trigger="submit[action(target)]"
- 当前不支持异步调用解析。参见问题
或者，使用 hx-on：hx-on:click="event.preventDefault(); action(this); htmx.trigger(this, 'ready')" hx-trigger="ready"
或者，使用 hyperscript：_="on submit halt the event action(target) trigger ready" hx-trigger="ready"
- 支持解析异步调用（如 fetch）。参见：异步透明性

Stimulus

hx-on 为多种用例提供了内联的、原生的替代方案。
hyperscript 是一个类似的官方配套项目，但这两个项目完全分离，可以单独使用或与任何其他库配合使用。
其他选项请参见：htmx：脚本支持