htmx 怪癖

这是一个基于 SQLite 的 “SQLite 中的怪癖、注意事项和陷阱” 页面 的 “quirks” 页面。

¥This is a “quirks” page, based on SQLite’s “Quirks, Caveats, and Gotchas In SQLite” page.

属性继承

¥Attribute Inheritance

htmx 中的许多属性都是 inherited：子元素可以从位于父元素上的属性接收行为。

¥Many attributes in htmx are inherited: child elements can receive behavior from attributes located on parent elements.

例如，这里有两个 htmx 驱动的按钮，它们从父 div 继承了 target：

¥As an example, here are two htmx-powered buttons that inherit their target from a parent div:

<div hx-target="#output">
    <button hx-post="/items/100/like">Like</button>
    <button hx-delete="/items/100">Delete</button>
</div>
<output id="output"></output>

这有助于避免重复属性，从而保留代码 DRY。

¥This helps avoid repeating attributes, thus keeping code DRY.

另一方面，随着属性远离元素，你将失去 位置行为，并且更难理解元素在做什么。

¥On the other hand, as the attributes get further away elements, you lose Locality of Behavior and it becomes more difficult to understand what an element is doing.

也可以通过向父元素添加属性来无意中改变元素的行为。

¥It is also possible to inadvertently change the behavior of elements by adding attributes to parents.

有些人更喜欢使用 htmx.config.disableInheritance 配置变量 完全禁用 htmx 中的继承。

¥Some people prefer to disable inheritance in htmx entirely, using the htmx.config.disableInheritance configuration variable.

以下是执行此操作的 meta 标记配置：

¥Here is a meta tag configuration that does so:

  <meta name="htmx-config" content='{"disableInheritance":true}'>

默认交换策略是 innerHTML

¥The Default Swap Strategy is innerHTML

hx-swap 属性允许你控制如何执行交换。默认策略是 innerHTML，即将响应 HTML 内容放置在目标元素内。

¥The hx-swap attribute allows you to control how a swap is performed. The default strategy is innerHTML, that is, to place the response HTML content within the target element.

许多人更喜欢使用 outerHTML 策略作为默认策略。

¥Many people prefer to use the outerHTML strategy as the default instead.

你可以使用 htmx.config.defaultSwapStyle 配置变量 更改此行为。

¥You can change this behavior using the htmx.config.defaultSwapStyle configuration variable.

以下是执行此操作的 meta 标记配置：

¥Here is a meta tag configuration that does so:

  <meta name="htmx-config" content='{"defaultSwapStyle":"outerHTML"}'>

定位 body 始终执行 innerHTML 交换

¥Targeting the body Always Performs an innerHTML Swap

由于历史原因，如果你定位 body 元素，htmx 将 始终执行 innerHTML 交换。

¥For historical reasons, if you target the body element, htmx will always perform an innerHTML swap.

这意味着你无法通过 htmx 请求更改 body 标签上的属性。

¥This means you cannot change attributes on the body tag via an htmx request.

默认情况下 4xx 和 5xx 响应不交换

¥By Default 4xx & 5xx Responses Do Not Swap

htmx 默认从未交换过 “error” 状态响应代码（400 和 500）。

¥htmx has never swapped “error” status response codes (400s & 500s) by default.

这种行为让一些人感到烦恼，特别是一些服务器框架会返回 422 - Unprocessable Entity 响应代码来指示表单未正确填写。

¥This behavior annoys some people, and some server frameworks, in particular, will return a 422 - Unprocessable Entity response code to indicate that a form was not filled out properly.

第一次遇到时，这可能会非常令人困惑。

¥This can be very confusing when it is first encountered.

你可以通过 htmx:beforeSwap 事件或 通过 htmx.config.responseHandling 配置数组 配置 htmx 的响应行为。

¥You can configure the response behavior of htmx via the htmx:beforeSwap event or via the htmx.config.responseHandling config array.

以下是默认配置：

¥Here is the default configuration:

{
  "responseHandling": [
    {"code":"204", "swap": false},
    {"code":"[23]..", "swap": true},
    {"code":"[45]..", "swap": false, "error":true},
    {"code":"...", "swap": false}]
}

请注意，204 No Content 也不会被交换。

¥Note that 204 No Content also is not swapped.

如果你想要交换所有内容而不管响应代码如何，可以使用以下配置：

¥If you want to swap everything regardless of response code, you can use this configuration:

{
  "responseHandling": [
    {"code":"...", "swap": true}]
}

如果你想要明确允许 422 响应进行交换，可以使用以下配置：

¥If you want to specifically allow 422 responses to swap, you can use this configuration:

{
  "responseHandling": [
    {"code":"422", "swap": true},
    {"code":"204", "swap": false},
    {"code":"[23]..", "swap": true},
    {"code":"[45]..", "swap": false, "error":true},
    {"code":"...", "swap": false}]
}

以下是允许所有响应交换的元标记：

¥Here is a meta tag allowing all responses to swap:

  <meta name="htmx-config" content='{"responseHandling": [{"code":"...", "swap": true}]}'>

GET 非表单元素上的请求默认不包含表单值

¥GET Requests on Non-Form Elements Do Not Include Form Values by Default

如果非表单元素通过 htmx 发出非 GET 请求（例如 PUT 请求），则该元素的封闭表单的值（如果有）将包含在请求中。

¥If a non-form element makes a non-GET request (e.g. a PUT request) via htmx, the values of the enclosing form of that element (if any) will be included in the request.

但是，如果元素发出 GET，则封闭表单的值将 不包括。

¥However, if the element issues a GET, the values of an enclosing form will not be included.

如果你希望在发出 GET 时包含封闭表单的值，则可以像这样使用 hx-include 属性：

¥If you wish to include the values of the enclosing form when issuing an GET you can use the hx-include attribute like so:

<button hx-get="/search"
        hx-include="closest form">
  Search
</button>

历史记录可能很棘手

¥History Can Be Tricky

htmx 提供与浏览器的 历史记录 交互的支持。这可能非常强大，但也可能很棘手，特别是如果你使用修改 DOM 的第三方 JavaScript 库。

¥htmx provides support for interacting with the browser’s history. This can be very powerful, but it can also be tricky, particularly if you are using 3rd party JavaScript libraries that modify the DOM.

使用 htmx 的历史记录支持时也可以有 安全问题。

¥There can also be security concerns when using htmx’s history support.

大多数这些问题都可以通过禁用任何本地历史记录缓存并在用户在历史记录中向后导航时简单地发出服务器请求来解决，但代价是历史记录导航会更慢。

¥Most of these issues can be solved by disabling any local history cache and simply issuing a server request when a user navigates backwards in history, with the tradeoff that history navigation will be slower.

以下是禁用历史缓存的元标记：

¥Here is a meta tag that disables history caching:

  <meta name="htmx-config" content='{"historyCacheSize": 0}'>

有些人不喜欢 hx-boost

¥Some People Don’t Like hx-boost

与 htmx 的大多数其他方面相比，hx-boost 是一个奇怪的功能：它将 “magically” 将所有锚标记和表单转换为 AJAX 请求。

¥hx-boost is an odd feature compared with most other aspects of htmx: it “magically” turns all anchor tags and forms into AJAX requests.

这可以加快这些交互的感觉，并且还允许表单和锚点在 JavaScript 已禁用 时继续工作，但它有一些权衡：

¥This can speed the feel of these interactions up, and also allows the forms and anchors to continue working when JavaScript is disabled, however it comes with some tradeoffs:

• 上面提到的历史问题可能会出现

  ¥The history issues mentioned above can show up

• 只有网页主体才会更新，因此新页面 head 标签中的任何样式和脚本都将被丢弃

  ¥Only the body of the web page will be updated, so any styles and scripts in the new page head tag will be discarded

• 全局 javascript 范围未刷新，因此页面之间可能会出现奇怪的交互。例如，全局 let 可能会开始失败，因为符号已经定义。

  ¥The global javascript scope is not refreshed, so it is possible to have strange interactions between pages. For example a global let may start failing because a symbol is already defined.

核心 htmx 团队的一些成员认为，由于这些问题以及浏览器在页面导航方面有了很大改进，最好避免使用 hx-boost 和 仅使用未增强的链接和表单。

¥Some members on the core htmx team feel that, due to these issues, as well as the fact that browsers have improved quite a bit in page navigation, it is best to avoid hx-boost and just use unboosted links and forms.

毫无疑​​问，与其他 htmx 属性相比，hx-boost 是一个异类，并且受到 “如果某样东西神奇地起作用，那么它也可能神奇地中断。” 的格言的影响

¥There is no doubt that hx-boost is an odd-man out when compared to other htmx attributes and suffers from the dictum that “If something magically works, then it can also magically break.”

尽管如此，我（Carson）仍然觉得它在许多情况下都很有用，并且它在 https://htmx.nodejs.cn 网站上使用。

¥Despite this fact, I (Carson) still feel it is useful in many situations, and it is used on the https://htmx.nodejs.cn website.

JavaScript API 不是焦点

¥The JavaScript API Is Not A Focus

htmx 是一个面向超媒体的前端库。这意味着 htmx 通过 HTML 中的 属性 增强 HTML，而不是提供复杂的 JavaScript API。

¥htmx is a hypermedia-oriented front end library. This means that htmx enhances HTML via attributes in the HTML , rather than providing an elaborate JavaScript API.

有一个 JavaScript API，但它不是库的重点，在大多数情况下，htmx 终端用户不应大量使用它。

¥There is a JavaScript API, but it is not a focus of the library and, in most cases, should not be used heavily by htmx end users.

如果你发现自己大量使用它，尤其是 htmx.ajax() 方法，那么可能值得问自己是否有更像 htmx 的方法来实现你正在做的事情。

¥If you find yourself using it heavily, especially the htmx.ajax() method, it may be worth asking yourself if there is a more htmx-ish approach to achieve what you are doing.