htmx 1.x → htmx 2.x 迁移指南

本指南的目的是提供从 htmx 1.x 到 htmx 2.x 的迁移说明。我们非常重视向后兼容性，因此在大多数情况下，这种迁移几乎不需要任何工作。

¥The purpose of this guide is to provide instructions for migrations from htmx 1.x to htmx 2.x. We place a very high value on backwards compatibility, so in most cases this migrations should require very little, if any, work.

• 如果你在模块设置中使用 htmx，我们现在为所有三种主要的 JavaScript 模块类型提供模块类型特定文件

  ¥If you are using htmx in a module setting, we now provide module-type specific files for all three of the major JavaScript module types

  • ESM 模块：/dist/htmx.esm.js

    ¥ESM Modules: /dist/htmx.esm.js

  • AMD 模块：/dist/htmx.amd.js

    ¥AMD Modules: /dist/htmx.amd.js

  • CJS 模块：/dist/htmx.cjs.js

    ¥CJS Modules: /dist/htmx.cjs.js

  • /dist/htmx.js 文件继续可由浏览器加载

    ¥The /dist/htmx.js file continues to be browser-loadable

• 所有扩展都已从核心 htmx 分发中删除并单独分发。虽然许多 1.x 扩展将继续与 htmx 2 配合使用，但你必须将 SSE 扩展升级到 2.x 版本，并且建议你将它们全部升级到 2.x 版本。

  ¥All extensions have been removed from the core htmx distribution and are distributed separately. While many 1.x extensions will continue to work with htmx 2, you must upgrade the SSE extension to the 2.x version, and it is recommended that you upgrade all of them to the 2.x versions.

• 如果你仍在使用旧版 hx-ws 和 hx-sse 属性，请升级到扩展版本

  ¥If you are still using the legacy hx-ws and hx-sse attributes, please upgrade to the extension versions

• 默认更改

  ¥Default Changes

  • 如果你想默认保留 “平滑滚动” 的 1.0 行为，请将 htmx.config.scrollBehavior 恢复为 'smooth'

    ¥If you want to retain the 1.0 behavior of “smooth scrolling” by default, revert htmx.config.scrollBehavior to 'smooth'

  • 如果你希望 DELETE 请求使用表单编码主体而不是参数，请将 htmx.config.methodsThatUseUrlParams 恢复为 ["get"]（这有点疯狂，但根据规范，DELETE 应该使用像 GET 这样的请求参数。）

    ¥If you want DELETE requests to use a form-encoded body rather than parameters, revert htmx.config.methodsThatUseUrlParams to ["get"] (it’s a little crazy, but DELETE, according to the spec, should use request parameters like GET.)

  • 如果你想使用 htmx 进行跨域请求，请将 htmx.config.selfRequestsOnly 恢复为 false

    ¥If you want to make cross-domain requests with htmx, revert htmx.config.selfRequestsOnly to false

• 将任何 hx-on 属性转换为其 hx-on: 等效项：

  ¥Convert any hx-on attributes to their hx-on: equivalent:

     <button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
                                   htmx:afterRequest: alert('Done making a request!')">
      Get Info!
     </button>
  

  变为：

  ¥becomes:

     <button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')"
                            hx-on:htmx:after-request="alert('Done making a request!')">
      Get Info!
     </button>
  Note that you must use the kebab-case of the event name due to the fact that attributes are case-insensitive in HTML.
  

• htmx.makeFragment() 方法现在始终返回 DocumentFragment，而不是 Element 或 DocumentFragment

  ¥The htmx.makeFragment() method now always returns a DocumentFragment rather than either an Element or DocumentFragment

• 如果你是扩展作者，并且你的扩展使用来自内部 API 的 selectAndSwap 方法，则该方法已被删除并替换为 swap 方法，该方法可从内部和公共 htmx API 中获得

  ¥If you are an extension author and your extension was using selectAndSwap method from internal API, it was removed and replaced with swap method, which is available from both internal and public htmx APIs

要使用新方法进行交换，你只需使用

¥To do a swap using new method, you need to simply use

let content = "<div>Hello world</div>"; // this is HTML that will be swapped into target
let target = api.getTarget(child);
let swapSpec = api.getSwapSpecification(child);
api.swap(target, content, swapSpec);

swap 方法文档可在 JS API 参考 上获得

¥swap method documentation is available on JS API Reference

htmx 2.0 不再支持 IE，但 htmx 1.x 继续支持 IE，并将在可预见的未来得到支持。

¥IE is no longer supported in htmx 2.0, but htmx 1.x continues to support IE and will be supported for the foreseeable future.

升级音乐

¥Upgrade Music

这是官方的 htmx 1.x -> 2.x 升级音乐：

¥This is the official htmx 1.x -> 2.x upgrade music: