\</> htmx 备忘清单 | 竹山一叶

适合初学者的综合 htmx 备忘清单

入门

快速开始

<script
  src="https://unpkg.com/htmx.org@1.8.4"
>
</script>
<!-- 有一个按钮POST，通过AJAX点击 -->
<button
  hx-post="/clicked"
  hx-swap="outerHTML"
>
  点击我
</button>

hx-post 和 hx-swap 属性告诉 htmx：

当用户单击此按钮时，向 /clicked 发出 AJAX 请求，并用响应替换整个按钮

1	$ npm install htmx.org

安装 htmx 将导入添加到您的 index.js

1	import 'htmx.org';

点击编辑提交

有一个按钮，可以从 /contacts/1/edit 获取联系人的编辑 UI

<div hx-target="this" hx-swap="outerHTML">
  <div><label>名字</label>: Joe</div>
  <div><label>姓</label>: Blow</div>
  <div><label>邮箱</label>: joe@blow.com</div>
  <button hx-get="/contact/1/edit" class="btn btn-primary">
    点击编辑
  </button>
</div>

这将返回一个可用于编辑联系人的表单

<form hx-put="/contact/1" hx-target="this" hx-swap="outerHTML">
  <div>
    <label>名字</label>
    <input type="text" name="firstName" value="Joe">
  </div>
  <div class="form-group">
    <label>姓</label>
    <input type="text" name="lastName" value="Blow">
  </div>
  <div class="form-group">
    <label>邮箱</label>
    <input type="email" name="email" value="joe@blow.com">
  </div>
  <button class="btn">提交</button>
  <button class="btn" hx-get="/contact/1">取消</button>
</form>

表单按照通常的 REST-ful 模式将 PUT 发回 /contacts/1

删除行

<table class="table delete-row-example">
  <thead>
    <tr>
      <th>Name</th> <th>Email</th> <th>Status</th> <th></th>
    </tr>
  </thead>
  <tbody hx-confirm="Are you sure?" hx-target="closest tr" hx-swap="outerHTML swap:1s">
    ...
  </tbody>
</table>

表体有一个 hx-confirm 属性来确认删除动作。它还将所有按钮的目标设置为最近的 tr，即最近的表格行（hx-target 继承自 DOM 中的父级）hx-swap 中的交换规范表示将整个目标换出并收到响应后等待 1 秒。最后一点是为了让我们可以使用以下 CSS：

tr.htmx-swapping td {
  opacity: 0;
  transition: opacity 1s ease-out;
}

在交换/删除之前淡出该行。每行都有一个带有 hx-delete 属性的按钮，该属性包含发出 DELETE 请求以从服务器中删除该行的 url。此请求以空内容响应，表明该行应替换为空内容

<tr>
  <td>Angie MacDowell</td>
  <td>angie@macdowell.org</td>
  <td>Active</td>
  <td>
    <button class="btn btn-danger" hx-delete="/contact/1">
      Delete
    </button>
  </td>
</tr>

延迟加载

<div hx-get="/graph" hx-trigger="load">
  <img
    alt="正在加载中..."
    class="htmx-indicator"
    width="150"
    src="/img/bars.svg"/>
</div>

当我们加载图表时显示进度指示器。然后通过稳定的 CSS(htmx-settling) 过渡加载图形并逐渐淡入视图

.htmx-settling img {
  opacity: 0;
}
img {
  transition: opacity 300ms ease-in;
}

hx-swap

:–	–
`innerHTML`	默认，替换目标元素的内部 `html`
`outerHTML`	用响应替换整个目标元素
`beforebegin`	在目标元素之前插入响应
`afterbegin`	目标元素的第一个子元素之前插入响应
`beforeend`	目标元素的最后一个子元素之后插入响应
`afterend`	在目标元素之后插入响应
`delete`	无论响应如何，都删除目标元素
`none`	不附加来自响应的内容 (带外项目仍将被处理)

API 参考

核心属性参考

属性	说明
`hx-boost`	添加或删除链接和表单的渐进增强
`hx-get`	向指定的 URL 发出 `GET`
`hx-post`	向指定的 URL 发出 `POST`
`hx-push-url`	将 URL 推入浏览器地址栏，创建一个新的历史条目
`hx-select`	从响应中选择要换入的内容
`hx-select-oob`	从带外(目标以外的某个地方)的响应中选择要换入的内容
`hx-swap`	控制内容的交换方式(`outerHTML`、`beforeEnd`、`afterend`，…)
`hx-swap-oob`	将响应中的内容标记为带外(应该在目标以外的地方交换)
`hx-target`	指定要交换的目标元素
`hx-trigger`	指定触发请求的事件
`hx-vals`	向参数添加值以随请求一起提交(JSON 格式)

使用 htmx 时最常用的属性

附加属性参考

属性	说明
`hx-confirm`	在发出请求之前显示一个 `confim()` 对话框
`hx-delete`	向指定的 URL 发出 `DELETE`
`hx-disable`	禁用给定节点和任何子节点的 htmx 处理
`hx-disinherit`	控制和禁用子节点的自动属性继承
`hx-encoding`	更改请求编码类型
`hx-ext`	用于此元素的扩展
`hx-headers`	添加到将与请求一起提交的标头
`hx-history-elt`	在历史导航期间要快照和恢复的元素
`hx-include`	在请求中包含额外数据
`hx-indicator`	在请求期间放置 `htmx-request` 类的元素
`hx-params`	过滤将与请求一起提交的参数
`hx-patch`	向指定的 URL 发出 PATCH
`hx-preserve`	指定在请求之间保持不变的元素
`hx-prompt`	在提交请求之前显示一个 `prompt()`
`hx-put`	向指定的 URL 发出 PUT
`hx-replace-url`	替换浏览器地址栏中的 URL
`hx-request`	配置请求的各个方面
`hx-sse`	已移至分机。旧版本的文档
`hx-sync`	控制不同元素发出的请求如何同步
`hx-validate`	强制元素在请求之前验证自己
~~`hx-vars`~~	将值动态添加到参数以随请求提交(已弃用，请使用 `hx-vals`)
`hx-ws`	已移至分机。旧版本的文档

列出了 htmx 中可用的所有其他属性

CSS 类参考

Class	说明
`htmx-added`	在交换之前应用于新的内容，在它被解决之后移除
`htmx-indicator`	一个动态生成的类，当存在 `htmx-request` 类时将切换可见 (不透明度：`1`)
`htmx-request`	在请求进行时应用于元素或使用 `hx-indicator` 指定的元素
`htmx-settling`	内容交换后应用于目标，内容确定后删除。可以通过 `hx-swap` 修改持续时间
`htmx-swapping`	在交换任何内容之前应用于目标，在交换之后移除。可以通过 `hx-swap` 修改持续时间

事件参考

事件	说明
`htmx:abort`	将此事件发送到元素以中止请求
`htmx:afterOnLoad`	AJAX 请求完成处理成功响应后触发
`htmx:afterProcessNode`	在 htmx 初始化节点后触发
`htmx:afterRequest`	AJAX 请求完成后触发
`htmx:afterSettle`	DOM 稳定后触发
`htmx:afterSwap`	换入新内容后触发
`htmx:beforeOnLoad`	在任何响应处理发生之前触发
`htmx:beforeProcessNode`	在 htmx 初始化节点之前触发
`htmx:beforeRequest`	在发出 AJAX 请求之前触发
`htmx:beforeSwap`	在交换完成之前触发，允许您配置交换
`htmx:beforeSend`	在发送 ajax 请求之前触发
`htmx:configRequest`	在请求之前触发，允许您自定义参数、标头
`htmx:confirm`	在元素上发生触发器后触发允许您取消(或延迟)发出 AJAX 请求
`htmx:historyCacheError`	在缓存写入期间因错误而触发
`htmx:historyCacheMiss`	在历史子系统中的缓存未命中时触发
`htmx:historyCacheMissError`	远程检索不成功时触发
`htmx:historyCacheMissLoad`	在成功的远程检索时触发
`htmx:historyRestore`	当 htmx 处理历史恢复操作时触发
`htmx:beforeHistorySave`	在内容保存到历史缓存之前触发
`htmx:load`	当新内容添加到 DOM 时触发
`htmx:noSSESourceError`	当元素在其触发器中引用 SSE 事件但未定义父 SSE 源时触发
`htmx:onLoadError`	htmx中onLoad处理异常时触发
`htmx:oobAfterSwap`	在交换了一个带元素之后触发
`htmx:oobBeforeSwap`	在带外元素交换完成之前触发，允许您配置交换
`htmx:oobErrorNoTarget`	当带外元素在当前 DOM 中没有匹配的 ID 时触发
`htmx:prompt`	显示提示后触发
`htmx:pushedIntoHistory`	在 url 被推送到历史记录后触发
`htmx:responseError`	当发生 HTTP 响应错误 (非 200 或 300 响应代码)时触发
`htmx:sendError`	当网络错误阻止 HTTP 请求发生时触发
`htmx:sseError`	当 SSE 源发生错误时触发
`htmx:swapError`	在交换阶段发生错误时触发
`htmx:targetError`	指定无效目标时触发
`htmx:timeout`	发生请求超时时触发
`htmx:validation:validate`	在验证元素之前触发
`htmx:validation:failed`	当元素验证失败时触发
`htmx:validation:halted`	当请求由于验证错误而停止时触发
`htmx:xhr:abort`	当 `ajax` 请求中止时触发
`htmx:xhr:loadend`	`ajax` 请求结束时触发
`htmx:xhr:loadstart`	`ajax` 请求开始时触发
`htmx:xhr:progress`	在支持进度事件的 `ajax` 请求期间定期触发

JavaScript API 参考

方法	说明
`htmx.addClass()`	向给定元素添加一个类
`htmx.ajax()`	发出一个 htmx 风格的 ajax 请求
`htmx.closest()`	找到与选择器匹配的给定元素的最近父级
`htmx.config`	保存当前 htmx 配置对象的属性
`htmx.createEventSource`	包含为 htmx 创建 SSE EventSource 对象的函数的属性
`htmx.createWebSocket`	包含为 htmx 创建 WebSocket 对象的函数的属性
`htmx.defineExtension()`	定义一个 htmx 扩展
`htmx.find()`	查找与选择器匹配的单个元素
`htmx.findAll()` \| `htmx.findAll(elt, selector)`	查找与给定选择器匹配的所有元素
`htmx.logAll()`	安装将记录所有 htmx 事件的记录器
`htmx.logger`	设置为当前记录器的属性（默认为空）
`htmx.off()`	从给定元素中删除事件侦听器
`htmx.on()`	在给定元素上创建事件侦听器，并返回它
`htmx.onLoad()`	为 htmx:load 事件添加回调处理程序
`htmx.parseInterval()`	将间隔声明解析为毫秒值
`htmx.process()`	处理给定元素及其子元素，连接任何 htmx 行为
`htmx.remove()`	删除给定的元素
`htmx.removeClass()`	从给定元素中删除一个类
`htmx.removeExtension()`	删除一个 htmx 扩展
`htmx.takeClass()`	从给定元素的其他元素中获取一个类
`htmx.toggleClass()`	从给定元素切换一个类
`htmx.trigger()`	在元素上触发事件
`htmx.values()`	返回与给定元素关联的输入值

请求标头参考

标头	说明
`HX-Boosted`	表示请求是通过使用 `hx-boost` 的元素发出的
`HX-Current-URL`	浏览器的当前 `URL`
`HX-History-Restore-Request`	如果请求是在本地历史缓存未命中后进行历史恢复，则为 `true`
`HX-Prompt`	用户对 `hx` 提示的响应
`HX-Request`	总是 `true`
`HX-Target`	目标元素的 id(如果存在)
`HX-Trigger-Name`	触发元素的名称(如果存在)
`HX-Trigger`	触发元素的 id(如果存在)

响应标头参考

标头	说明
`HX-Location`	允许您执行不执行整页重新加载的客户端重定向
`HX-Push-Url`	将一个新的 `url` 推入历史堆栈
`HX-Redirect`	可用于将客户端重定向到新位置
`HX-Refresh`	如果设置为 `true`，客户端将完全刷新页面
`HX-Replace-Url`	替换地址栏中的当前 `URL`
`HX-Reswap`	允许您指定如何交换响应有关可能的值，请参阅 `hx-swap`
`HX-Retarget`	将内容更新的目标更新为页面上不同元素的 CSS 选择器
`HX-Trigger`	允许您触发客户端事件请参阅文档以获取更多信息
`HX-Trigger-After-Settle`	允许您触发客户端事件请参阅文档以获取更多信息
`HX-Trigger-After-Swap`	允许您触发客户端事件请参阅文档以获取更多信息