入门

从一行 <script> 标签开始。没有构建步骤，没有配置仪式——引入即生效。

引入 htmx

把脚本放在文档头部或 </body> 之前皆可，htmx 加载后会自动扫描整页的 hx-* 属性：

CDN 引入 · 任意 HTML 文件

<script src="https://cdn.jsdelivr.net/npm/htmx.org@4.0.0/dist/htmx.min.js"
        integrity="sha384-BvJpBiO8Kh31EqtJe5DRIeWrHWnCGkwytKs9NKFi86Hhw96dEqdEMzZDeK9iEGTc"
        crossorigin="anonymous"></script>

htmx 会监听 DOMContentLoaded；若之后动态插入内容，调用 htmx.process() 或对目标区域执行 htmx.refresh() 即可。

第一次请求

最经典的例子：让一个 <button> 通过 AJAX 发送一次点击的 POST 请求——这正是 README 快速开始的写法：

快速开始 · 两行成事

<!-- 让按钮通过 AJAX 发送一次点击的 POST 请求 -->
<button hx-post="/clicked" hx-swap="outerHTML">
  Click Me
</button>

hx-post 与 hx-swap 属性告诉 htmx：「当用户点击这个按钮时，向 /clicked 发起一次 AJAX 请求，并用响应内容替换掉整个按钮。」

本站的示范

就地验证 · hx-get

这个按钮此刻就是活的——点击后 htmx 会向本站请求一段 HTML 并换进下面的框。这正是 htmx 的全部心智模型。

作为 node 包安装

npm

npm install htmx.org --save

npm 上存在一个旧的、已损坏的包名叫 htmx——请认准 htmx.org。用 Bun、pnpm、yarn 同理，包名都是 htmx.org。

打包器项目中直接引入即可：

打包器 · import

import "htmx.org";            // 副作用引入，全局自动接管
// 或命名导入，适用于需要手动控制的场景
import htmx from "htmx.org";

本地开发与测试

想在本地贡献 htmx 源码？流程如下（本项目——一个纯 htmx 站点——与之共享同一种朴素：起个静态服务器就能开发）：

先安装开发依赖：npm install；
然后在仓库根目录启动一个 Web 服务器，最简单的方式是 npx serve；
访问 <http://0.0.0.0:3000/test/> 即可运行测试套件；
修改 /src/htmx.js 添加功能，并在 /test 相应位置补充测试。

测试目录结构

路径	内容
`/test/index.html`	测试的根页面，所有其他测试都由此引入
`/test/attributes`	属性相关的测试
`/test/core`	核心功能测试
`/test/core/regressions.js`	回归测试
`/test/ext`	扩展测试
`/test/manual`	无法自动化的手动测试

htmx 使用 mocha 测试框架、chai 断言框架以及 sinon 模拟 AJAX 请求——README 的原话是：「它们都很不错」。

下一章属性巡礼，把全部 hx-* 逐一过目。