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: 默认值,替换 目标元素的内部 HTMLouterHTML: 用响应 替换 整个目标元素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,inputfind::: 在当前元素内部查找与给定的选择器匹配的下一个元素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 平台之上更精细的前端扩展交给其他库处理。