Hotwire / Turbo ➡️ htmx 迁移指南

本指南的目的是提供 htmx 中 “Hotwire 等效” 功能的通用做法。

¥The purpose of this guide is to provide common practices for “Hotwire Equivalent” features in htmx.

htmx 专注于一组透明、高度灵活的 html 扩展，以将其逻辑结论作为超文本。

¥htmx is focused on a set of transparent, highly flexible extensions of html to its logical conclusion as a hypertext.
Hotwire / Turbo 专注于流畅的开箱即用体验，但更有态度且灵活性较差。

¥Hotwire / Turbo is focused on a smooth out of the box experience, but is more opinionated and less flexible.

Turbo Drive

<body hx-boost="true"> 启用类似 Turbo Drive 的体验。参见：hx-boost

¥<body hx-boost="true"> to enable a Turbo Drive-like experience. See: hx-boost
与 Turbo Drive 一样，如果用户禁用了 javascript，hx-boost 将继续工作。参见：渐进式增强

¥As with Turbo Drive, if the user has javascript disabled, hx-boost will continue to work. See: Progressive Enhancement
hx-boost="false" 等同于 data-turbo="false"，用于禁用特定链接或表单上的增强。参见：手册

¥hx-boost="false" is equivalent to data-turbo="false" and used to disable boost on specific links or forms. See: Handbook
表单提交后重定向（302、303、307、3xx）hx-target="body" hx-swap="outerHTML" hx-push-url="true" 参见：手册

¥Redirect after form submission (302, 303, 307, 3xx) hx-target="body" hx-swap="outerHTML" hx-push-url="true" See: Handbook
在表单提交时禁用按钮请参阅：手册

¥Disable buttons on form submission See: Handbook
- 仅禁用按钮，因为 <form> 不提交禁用的字段。参见：MDN:disabled
  
  ¥Only disable buttons because <form> does not submit disabled fields. See: MDN: disabled

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：

¥Or, hx-on may be used:
- 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" 参见：Cookbook

¥Or, hyperscript may be used: _="on submit toggle @disabled <button/> in me until htmx:afterOnLoad" See: Cookbook

Turbo Frames

htmx 将 “Turbo Frames” 的所有想法结合到基本属性中。不需要 <turbo-frame>。

¥htmx combines all ideas of “Turbo Frames” into the base attributes. No <turbo-frame> required.
延迟加载：hx-trigger="load, submit" 参见：手册

¥Lazy loading: hx-trigger="load, submit" See: Handbook

Turbo Streams

htmx 将 “Turbo Streams” 的所有想法结合到基本属性中。不需要 <turbo-stream>，不需要 <template>。

¥htmx combines all ideas of “Turbo Streams” into the base attributes. No <turbo-stream>, no <template> required.
注意：Turbo Streams 可以在页面上的任何位置执行许多操作（类似于 hx-select-oob 和 hx-swap-oob），而 Turbo Frames 仅更新封装在 <turbo-frame> .. </turbo-frame> 中的内容

¥Note: Turbo Streams can perform many actions anywhere on a page (similar to hx-select-oob and hx-swap-oob) while Turbo Frames only update what is wrapped within <turbo-frame> .. </turbo-frame>

事件

¥Events

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

¥Intercepting or Pausing Events. htmx:config-request is equivalent to turbo:before-fetch-request See: Handbook
- htmx:config-request 与 htmx:configRequest 相同参见：事件命名
  
  ¥htmx:config-request is the same as htmx:configRequest See: Event Naming

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

或者，使用 hx-trigger 条件：hx-trigger="submit[action(target)]"

¥Or, use an hx-trigger condition: hx-trigger="submit[action(target)]"
- 目前无法解析异步调用。参见 issue
  
  ¥Does not currently resolve async calls. See issue
或者，使用 hx-on：hx-on:click="event.preventDefault(); action(this); htmx.trigger(this, 'ready')" hx-trigger="ready"

¥Or, use 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"

¥Or, use hyperscript: _="on submit halt the event action(target) trigger ready" hx-trigger="ready"
- 将解决异步调用，例如 fetch。参见：异步透明度
  
  ¥Will resolve async calls such as fetch. See: async transparency

刺激

¥Stimulus

hx-on 为各种用例提供了内联的原始替代品。

¥hx-on provides an inline, vanilla substitute for a wide variety of use cases.
hyperscript 是 htmx 的近似模拟和官方配套项目，但这两个项目完全分开，可以彼此或任何其他库单独使用。

¥hyperscript is a close analogue and an official companion project to htmx, but the two projects are entirely separated and can be used exclusively from each other or any other library.
有关其他选项，请参阅：htmx:脚本

¥For other options, see: htmx: Scripting