请求与响应

htmx 期望对它发出的 AJAX 请求的响应是 HTML，通常是 HTML 片段（尽管与 hx-select 标签匹配的完整 HTML 文档也很有用）。然后，htmx 会将返回的 HTML 交换到指定目标处的文档中，并指定交换策略。

有时你可能不想在交换中执行任何操作，但仍可能触发客户端事件（见下文）。

对于这种情况，默认情况下，你可以返回一个204 - No Content响应代码，此时 htmx 会忽略响应的内容。

如果服务器出现错误响应（例如 404 或 501），htmx 将触发 htmx:responseError 事件，你可以处理该事件。

一旦发生连接错误，就会触发 htmx:sendError 事件。

配置响应处理

你可以通过更改或替换 htmx.config.responseHandling 数组来配置 htmx 的上述行为。此对象是Json格式，定义示例如下：

    responseHandling: [
        {code:"204", swap: false},   // 204 - No Content by default does nothing, but is not an error
        {code:"[23]..", swap: true}, // 200 & 300 responses are non-errors and are swapped
        {code:"[45]..", swap: false, error:true}, // 400 & 500 responses are not swapped and are errors
        {code:"...", swap: false}    // catch all for any other response code
    ]

当 htmx 收到响应时，它将按顺序迭代 htmx.config.responseHandling 数组，并测试给定对象的 code 属性（被视为正则表达式时）是否与当前响应匹配。如果条目与当前响应代码匹配，则将用于确定是否以及如何处理响应。

此数组中的响应处理配置可用的字段包括：

• code - 一个代表将根据响应代码进行测试的正则表达式的字符串。
• swap - 如果为 true 响应应该被交换到 DOM 中，否则设为 false
• error - 如果为 true htmx 则将此响应视为错误
• ignoreTitle - 如果 htmx 应忽略响应中的标题标签则设为 true
• select - 用于从响应中选择内容的 CSS 选择器
• target - 指定响应的替代目标的 CSS 选择器
• swapOverride - 响应的替代交换机制

配置响应处理示例

作为如何使用此配置的示例，请考虑服务器端框架在发生验证错误时以 422 - Unprocessable Entity 响应进行响应的情况。默认情况下，htmx 将忽略响应，因为它与正则表达式 [45]...

使用 meta 机制配置 responseHandling，我们可以添加以下配置：

<!--
  * 204 No Content by default does nothing, but is not an error
  * 2xx, 3xx and 422 responses are non-errors and are swapped
  * 4xx & 5xx responses are not swapped and are errors
  * all other responses are swapped using "..." as a catch-all
-->
<meta
    name="htmx-config"
    content='{
        "responseHandling":[
            {"code":"204", "swap": false},
            {"code":"[23]..", "swap": true},
            {"code":"422", "swap": true},
            {"code":"[45]..", "swap": false, "error":true},
            {"code":"...", "swap": true}
        ]
    }'
/>

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

<meta name="htmx-config" content='{"responseHandling": [{"code":".*", "swap": true}]}' /> <!--all responses are swapped-->

最后，值得考虑使用 response extension ，它允许你通过属性以声明方式配置响应代码的行为。

CORS

在跨源上下文中使用 htmx 时，请记住配置你的 Web 服务器以设置访问控制头，以便 htmx 头在客户端可见。

• Access-Control-Allow-Headers（用于请求头）
• Access-Control-Expose-Headers（用于响应头）

请求头

htmx 在请求中包含许多有用的标头：

响应头

htmx 支持一些 htmx 特定的响应头：

• HX-Location - 允许你进行客户端重定向，而无需重新加载整个页面
• HX-Push-Url - 将新的 URL 推送到历史堆栈中
• HX-Redirect - 可用于将客户端重定向到新位置
• HX-Refresh - 如果设置为“true”，客户端将完全刷新页面
• HX-Replace-Url - 替换位置栏中的当前 URL
• HX-Reswap - 允许你指定如何交换响应。请参阅 hx-swap 了解可能的值
• HX-Retarget - CSS 选择器，将内容更新的目标更新为页面上的不同元素
• HX-Reselect - CSS 选择器，允许你选择要交换响应的哪一部分。覆盖触发元素上现有的 hx-select
• HX-Trigger - 允许你触发客户端事件
• HX-Trigger-After-Settle - 允许你在 Settle 步骤后触发客户端事件
• HX-Trigger-After-Swap - 允许你在交换步骤后触发客户端事件

有关 HX-Trigger 标头的更多信息，请参阅 HX-Trigger 响应头。

通过 htmx 提交表单的好处是不再需要 Post/Redirect/Get 模式。在服务器上成功处理 POST 请求后，你不需要返回HTTP 302 (Redirect)。你可以直接返回新的 HTML 片段。

此外，上述响应头不会提供给 htmx 进行处理，例如HTTP 302（重定向）等 3xx 重定向响应代码。相反，浏览器将在内部拦截重定向并从重定向的 URL 返回标头和响应。尽可能使用替代响应代码（例如 200）来允许返回这些响应头。

请求操作顺序

htmx 请求中的操作顺序如下：

• 元素被触发并开始请求
  • 为请求收集值
  • 该 htmx-request 类应用于适当的元素
  • 然后通过 AJAX 异步发出请求
  • 收到响应后，目标元素将被标记为 htmx-swapping 类
  • 应用可选的交换延迟（参见 hx-swap 属性）
  • 实际内容交换已完成
    • 该 htmx-swapping 类已从目标中移除
    • htmx-added 每条新内容都会添加相应的类别
    • 该 htmx-settling 类应用于目标
    • 完成延迟（默认值：20ms）
    • DOM 已稳定
    • 该 htmx-settling 类已从目标中移除
    • htmx-added 每次新增内容时都会删除该类 你可以使用 htmx-swapping 和 htmx-settling 类在页面之间创建 CSS 转换。