HTMX 基础

触发 HTTP 请求

  • hx-get: 发出 HTTP GET 请求
  • hx-post: 发出 HTTP POST 请求
  • hx-put: 发出 HTTP PUT 请求
  • hx-patch: 发出 HTTP PATCH 请求
  • hx-delete: 发出 HTTP DELETE 请求

例如,希望一个按钮向 /contacts 发出 GET 请求:

<button hx-get="contacts">Get The Contacts</button>

当点击后,产生的局部 HTML 响应可能类似这样:

<ul>
  <li><a href="mailto:joe@example.com">Joe</a></li>
  <li><a href="mailto:sarah@example.com">Sarah</a></li>
  <li><a href="mailto:fred@example.com">Fred</a></li>
</ul>

定位元素

htmx 默认行为会把返回的内容直接放进出发请求的元素内部。 可以使用 hx-target 精确指定新内容放在 DOM 的什么位置。

<div id="main">
  <button hx-get="/contacts" hx-target="#main">Get The Contacts</button>
</div>

这里,#main 是一个 CSS 选择器,表示 ID 为 main 的那个元素。 这样响应接收处理后,客户端 HTML 大致这样:

<div id="main">
  <ul>
    <li><a href="mainto:joe@example.com">Joe</a></li>
    <li><a href="mainto:sarah@example.com">Sarah</a></li>
    <li><a href="mainto:fred@example.com">Fred</a></li>
  </ul>
</div>

响应 HTML 被放进 div 中,并替换了触发的按钮。

交换样式

htmx 提供了 hx-swap 属性,可以精确制定如何交换进 DOM,支持以下取值:

  • innerHTML: 默认值,替换 目标元素的内部 HTML
  • outerHTML: 用响应 替换 整个目标元素
  • beforebegin: 将响应 插入 到目标元素之前
  • afterbegin: 将响应 插入 到目标元素的第一个子元素之前
  • beforeend: 将响应 插入 到目标元素的最后一个子元素之后
  • afterend: 将响应 插入 到目标元素之后
  • delete: 无论响应是什么,都 删除 目标元素
  • none: 不执行任何交换

前两个值 innerHTML 和 outerHTML 取自标准的 DOM 属性,它们分别允许替换元素内部的内容,或整个元素本身。

后面的四个值取自 Element.insertAdjacentHTML() DOM API,它允许以多种方式把元素放置在给定元素的周围。

最后两个值 delete 和 none 是 htmx 特有的。 第一个选项将目标元素从 DOM 中移除,第二个选项则什么都不做。

对于上面例子,如果希望替换整个 div 元素,则只需要新增一个 hx-swap 属性:

<div id="main">
  <button hx-get="/contacts" hx-target="#main" hx-swap="outerHTML">
    Get The Contacts
  </button>
</div>

使用事件

默认情况下,hx-get 或 htmx 中其他驱动请求的注解被放在按钮上时,请求会在按钮点击时发出。 不过,htmx 将 “事件触发请求” 这一概念泛化了,即使用 hx-trigger。 该属性允许指定一个或多个事件,使用元素触发 HTTP 请求。

默认出发事件取决于元素类型:

  • input, textarea 和 select 上的请求由 change 事件触发
  • form 元素上的请求由 sumbit 事件触发
  • 所有其他元素上的请求由 click 事件触发

下面举一个用户体验并不是很好的例子: 鼠标进入按钮时触发按钮上面的请求

<div id="main">
  <button
    hx-get="/contacts"
    hx-target="#main"
    hx-swap="outerHTML"
    hx-trigger="mouseenter"
  >
    Get The Contacts
  </button>
</div>

再举一个更加现实的例子: 为加载联系人添加键盘快捷键 Ctrl-L。

trigger 属性支持的额外语法:事件过滤器和其他参数。 事件过滤器是一种机制,用于判断某个事件是否可以触发请求,在事件后方加上方括号即可应用过滤器:someEvent[someFilter]

过滤器本身是一个 JavaScript 表达式,会在给定时间发生时求值。 如果结果按 JavcScript 的意义为真值,就会触发请求,否则不会触发请求。

就键盘快捷键而言,除了 click 事件,还希望捕获 keyup 事件:

<div id="main">
  <button
    hx-get="/contacts"
    hx-target="#main"
    hx-swap="outerHTML"
    hx-trigger="click, keyup"
  >
    Ger The Contacts
  </button>
</div>

现在任何 keyup 事件都会触发请求,并且是只有在这个按钮内发生 keyup 才触发。 用户需要先用 Tab 键移动到按钮上使其激活,然后才能开始输入。

下面修复这两个问题:使用触发器过滤,检测 Control 和 L 是否同时按下

<div id="main">
  <button
    hx-get="/contacts"
    hx-target="#main"
    hx-swap="outerHTML"
    hx-trigger="click, keyup[ctrlKey && key == 'l']"
  >
    Get The Contacts
  </button>
</div>

但是,要让其全局都生效,而不是只在按钮上生效。

JavaScript 的事件冒泡模型: 事件通常向父元素“冒泡”。 因此,像 keyup 这样的事件会先在获得焦点的元素上触发,然后在其父元素上触发,依次类推,直到顶层 document 对象,也就是其他所有元素的根。

为了支持无论在哪个元素获得焦点都能工作的全局键盘快捷键,将使用 hx-trigger 属性的一个特性:监听其他元素上的事件。 语法是 from:修饰符,它加在事件名之后,允许用 CSS 选择器指定要在哪个特定元素上监听给定事件。

<div id="main">
  <button
    hx-get="/contacts"
    hx-target="#main"
    hx-swap="outerHTML"
    hx-trigger="click, keyup[ctrlKey && key == 'l'] from:body"
  >
    Get The Contacts
  </button>
</div>

传递请求参数

到目前为止,只包括了按钮简单 GET 请求的情况。 这些概念是否类似 a 标签可能做的事情。

但基于 HTML 还有另一种原生超媒体控件:表单。 表单用于在请求中把 URL 之外的附加信息传递给服务器。

这些信息通过表单的 input 元素捕获,所用的是 HTML 中可用的各种 input标签类型。 hmtx 允许模仿 HTML 自身的方式包含这些附加信息。

包围表单

在 htmx 随请求传递输入值的最简单方式,就是把发起请求的元素包括在 form 标签内。

<div id="main">
  <form>
    <label for="search">Search Contacts:</label>
    <input id="search" name="q" type="search" placeholder="Search Contacts" />
    <button hx-post="/contacts" hx-target="#main">Search The Contacts</button>
  </form>
</div>

这里在按钮外面包了一个 form 标签,并添加了一个搜索 input,可以用于搜索联系人的词。

现在,当用户点击按钮时,id 为 search 的 input 的值会包含在请求中。 这是因为有一个 form 同时包住了按钮和 input: 当 htmx 驱动的请求被触发时,htmx 会沿 DOM 层级向上查找外层的 form,如果找到,就会包含该表单内的所有值。

这里 GET 改成了 POST,默认情况下,htmx 对 GET 请求不会包含最近的外层表单,但是对所有其他类型的请求都会包含表单。

这似乎有点奇怪,但是可以避免在处理历史记录项时把表单中的 URL 弄乱。

包含输入

把包含在请求中的所有输入都包进来,是 htmx 请求中处理输入最常见的方法,但这并不总是可行: form 标签可能影响布局,而且无法放在 HTML 的某些位置。

后面一个例子是表格行元素 tr: form 标签及不是表格行是合法子元素,也不是合法父元素,因此无法将表单放在表格行的内部或周围。

为了解决这个问题,htmx 提供了一种在请求中包含输入的机制: hx-include 属性,允许通过 CSS 选择器选择系统包含在请求中的输入值。

例如下面这个例子,包含 input 但是去掉了表单:

<div id="main">
  <label for="search">Search Contacts:</label>
  <input id="search" name="q" type="search" placeholder="Search Contacts" />
  <button hx-post="/contacts" hx-target="#main" hx-include="#search">
    Search The Contacts
  </button>
</div>

hx-include 属性接受一个 css 选择器值,可以精确地指定请求发送哪些值。 当很难把发起请求的元素放在一起的时候,这会很有用。

同时,hx-include 也支持相对 CSS 选择器。 它们允许相对于声明该属性的元素来指定 CSS 选择器,下面是一些例子:

  • closest::: 查找与给定选择器批评的最近父元素
  • next::: 查找上一个(向后扫描)与给定选择器匹配的元素,例如 previous, input
  • find::: 在当前元素内部查找与给定的选择器匹配的下一个元素
  • this::: 当前元素

使用相对 css 选择器,通常可以避免为元素生成 id,因为可以转而利用其内部结构布局。

内联值

在 htmx 驱动的请求中包含值的最后一种方式,是使用 hx-vals 属性。 它允许在请求中包含“静态”的值。

如果有想要请求的附加信息,但又不想把这些信息嵌入例如隐藏 input 中,这会很有用。

<button hx-get="/contacts" hx-vals='{"state": "MT"}'>
  Get The Contacts In Montana
</button>

值为 MT 的参数 state 会被包含在 GET 请求中哦个,得到的路径和参数类似这样 /contacts?state=MT。 注意,这里将 hx-vals 属性改成了单引号包围,是因为 JSON 严格要求使用双引号。为了避免转义,故使用单引号形式。

还可以给 hx-vals 加上 js: 前缀,传入在请求时求职的值: 这对包含动态维护的变量,或来自第三方 JavaScript 库的值等情况非常有用。

例如:

<button hx-get="/contacts" hx-vals='js:{"state":getCurrentState()}'>
  Get The Contacts In The Selected State
</button>

这三种机制 —— form, hx-include 和 hx-vals 能以非常符合 HTML 精神的方式,在 htmx 的超媒体请求中包含值。

历史记录支持

当使用普通的 HTML 链接和表单时,浏览器会记录访问过的所有页面。 之后可以使用后退按钮,返回上一个页面。

htmx 和单页应用一样,需要显式使用历史记录 API.

考虑之前一直在使用的加载联系人的按钮:

<button hx-get="/contacts" hx-target="#main">Get The Contacts</button>

如果希望 在这个请求发生时创建历史记录项,就会给按钮添加一个新属性:hx-push-url:

<button hx-get="/contacts" hx-target="#main" hx-push-url="true">
  Get The Contacts
</button>

现在,点击按钮时,/contacts 路径会被放入浏览器的地址栏 ,并为其创建一条历史记录。 此外,如果用户点击后退,页面原来的内容会连同原始 URL 一起恢复。

属性名字 hx-push-url 来自 JavaScript API history.pushState()。 “推入”这一说法来自历史记录被压入栈的事实。

现在 /contacts 路径以及“推入”浏览器的地址栏,不过,要是在 /contacts 刷新浏览器。 这种情况下,就需要处理局部响应,也需要处理整页响应。 可以使用 HTTP 头来做到这一点,后面再介绍。

结论

与大多数基于 JavaScript 的方法相比,htmx 能以最小的额外概念负担,实现远比纯 HTML 复杂得多的 Web 应用。

通过更贴近 Web 的原生模型,htmx 力求在简单性与功能性之间取得平衡,并把现有 Web 平台之上更精细的前端扩展交给其他库处理。