部署（引入）教程：htmx

1. 引入方式：将 HTMX 添加到你的项目

HTMX 的引入非常简单，主要有以下两种方式。

方式一：通过 CDN 引入（最快，推荐用于快速体验）

这是最推荐的开始方式，无需下载或安装任何文件，直接在 HTML 页面的 <head> 或 <body> 末尾添加一个 <script> 标签即可。

  1. 复制以下代码：

    1
    2
    3
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"
            integrity="sha384-H5SrcfygHmAuTDZphMHqBJLc3FhssKjG7w/CeCpFReSfwBWDTKpkzPP8c+cLsK+V"
            crossorigin="anonymous"></script>

    你也可以从 https://htmx.org/download/ 获取最新版本号。

  2. 将其粘贴到你的 HTML 文件中。

方式二：通过 npm 安装（推荐用于项目开发）

如果你的项目使用了 Node.js 生态和构建工具（如 Webpack、Vite），可以通过 npm 安装并管理 HTMX。

  1. 在你的项目根目录下运行：

    1
    npm install htmx.org --save

    重要提示：请注意包名是 htmx.org，而不是 htmx（后者是一个已被废弃的旧包）。

  2. 在你的 JavaScript 入口文件中导入 HTMX：

    1
    2
    3
    4
    5
    // ES Module 方式
    import 'htmx.org';

    // 或者 CommonJS 方式
    require('htmx.org');

    或者，你也可以在 HTML 中通过 <script> 标签引用 node_modules 中的文件。

2. 基本使用示例：验证引入成功

引入 HTMX 后，你可以通过一个简单的示例来验证它是否工作。创建一个 HTML 文件，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!DOCTYPE html>
<html>
<head>
    <!-- 1. 通过 CDN 引入 HTMX -->
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"
            integrity="sha384-H5SrcfygHmAuTDZphMHqBJLc3FhssKjG7w/CeCpFReSfwBWDTKpkzPP8c+cLsK+V"
            crossorigin="anonymous"></script>
</head>
<body>
    <!-- 2. 使用 HTMX 属性 -->
    <button hx-post="/clicked" hx-swap="outerHTML">
        点击我
    </button>
</body>
</html>

原理说明：

  • hx-post="/clicked"：告诉 HTMX，当用户点击此按钮时，向 /clicked 路径发起一个 AJAX POST 请求。
  • hx-swap="outerHTML"：指定将服务器返回的响应内容，用来替换整个按钮本身。
  • 当服务器端（例如，一个 Python Flask、Node.js Express 或任何后端服务）在 /clicked 路径上返回新的 HTML 片段时，页面上的按钮就会被这个新内容替换，无需刷新整个页面。

3. 开发与测试环境设置（可选）

如果你想参与 HTMX 本身的开发或运行其测试套件，可以参考以下步骤：

  1. 克隆仓库并安装依赖：

    1
    2
    3
    git clone https://github.com/bigskysoftware/htmx.git
    cd htmx
    npm install

  2. 启动本地开发服务器：
    在项目根目录下运行一个 Web 服务器（例如使用 npx serve）：

    1
    npx serve

  3. 访问测试页面：
    在浏览器中打开 http://0.0.0.0:3000/test/，这里包含了 HTMX 的完整测试套件，可以用于验证修改或调试。

4. 核心概念与下一步

理解以下核心概念，能帮你更好地使用 HTMX：

  • 核心属性：除了 hx-post，还有 hx-get、hx-put、hx-delete 等，对应不同的 HTTP 方法。
  • 触发方式：默认是自然事件（如按钮的 click），但可以通过 hx-trigger 属性自定义，例如 hx-trigger="mouseenter" 或 hx-trigger="load"。
  • 目标元素：通过 hx-target 属性指定响应内容要替换到页面上的哪个元素（默认是发起请求的元素自身）。
  • 交换方式：通过 hx-swap 属性控制如何替换内容，如 innerHTML（替换内部 HTML）、beforeend（在末尾追加）等。

HTMX 的价值在于它极大地减少了前端 JavaScript 的编写量，让你能用更接近传统 Web 开发的方式（服务端渲染 HTML 片段）来构建交互丰富的应用。

总结

部署方式 适用场景 操作
CDN 引入 快速原型、演示、不依赖构建工具的项目 在 HTML 中添加 <script> 标签
npm 安装 使用构建工具的项目、需要版本管理和打包 运行 npm install htmx.org --save，并在 JS 中导入