</> htmx 备忘清单

NPM version Downloads Repo Dependents Github repo

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

入门

快速开始

htmxintercooler.js 的继承者

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

hx-posthx-swap 属性告诉 htmx

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

$ npm install htmx.org

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

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控制内容的交换方式(outerHTMLbeforeEndafterend,...)
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:afterOnLoadAJAX 请求完成处理成功响应后触发
htmx:afterProcessNode在 htmx 初始化节点后触发
htmx:afterRequestAJAX 请求完成后触发
htmx:afterSettleDOM 稳定后触发
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:onLoadErrorhtmx中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:abortajax 请求中止时触发
htmx:xhr:loadendajax 请求结束时触发
htmx:xhr:loadstartajax 请求开始时触发
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允许您触发客户端事件
参阅文档以获取更多信息