SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场drupal-htmx

drupal-htmx

前端与建站

查看项目

更新于 10-16 02:14

技能介绍

Drupal HTMX 是 Drupal 11.3+ 核心内置的 HTMX 集成能力。HTMX 2.0.4 随 Drupal 11.3+ 核心以 core/htmx 形式提供，无需贡献模块。

一、用途与选型 该技能用于在 Drupal 中实现无整页刷新的动态交互。文档给出 HTMX 与 AJAX Form API 的选型建议：表单字段联动更新其他字段用 HTMX（swapOob）；简单表单提交并局部更新页面用 HTMX 或 AJAX Form API；带 AjaxResponse 命令的复杂多步 AJAX 用 AJAX Form API；非表单 UI 交互（懒加载、无限滚动、boost）用 HTMX；修改既有表单时用 AJAX Form API 以减少干扰。

二、附加库 在 mymodule.libraries.yml 中声明依赖 core/drupal.htmx。core/drupal.htmx 包含 htmx 供应商 JS、Drupal behaviors 桥接、资源加载器与 drupalSettings 集成。

三、Htmx PHP 流式构建器 使用 Drupal\Core\Htmx\Htmx 与 Drupal\Core\Url。通过 new Htmx() 创建实例，调用 post($url)->target('#my-wrapper')->swap('outerHTML') 等方法，再用 applyTo($element) 将 data-hx-* 属性写入渲染数组元素；传入 '#wrapper_attributes' 作为第二参数可作用于外层 div。

请求属性方法包括：get/post/put/patch/delete（对应 data-hx-get 等）、target、swap（innerHTML|outerHTML|beforebegin|afterbegin|beforeend|afterend|delete|none）、swapOob、select、selectOob、trigger、vals、boost、confirm、on、pushUrl、onlyMainContent（添加 data-hx-drupal-only-main-content 以触发 HtmxRenderer）。

响应头方法包括：pushUrlHeader（HX-Push-Url）、redirectHeader（HX-Redirect）、triggerHeader（HX-Trigger，也可接受带数据的数组）、triggerAfterSettleHeader（HX-Trigger-After-Settle）、refreshHeader（HX-Refresh），以及 replaceUrlHeader、locationHeader、reswapHeader、retargetHeader、reselectHeader、triggerAfterSwapHeader。

四、主要模式

  1. 依赖下拉（动态表单）：一个 select 更新另一个 select，无需页面刷新。每个字段以 swapOob 提交到 <current>，两个字段均带外重渲染。示例中为 type 与 value 两个 select 分别应用 post($formUrl)->swap('none')->swapOob('true')，并可选在变更时 pushUrlHeader。
  2. 部分路由（_htmx_route）：返回仅含内容片段（无 <html> 外壳）的路由，用于响应 hx-get/hx-post 的控制器。在 routing.yml 的 options 中设置 _htmx_route: true，使用 HtmxRenderer 仅返回 HTML 片段；控制器正常返回渲染数组即可。
  3. onlyMainContent()：为任意 HTMX 元素添加 data-hx-drupal-only-main-content，Drupal JS 桥接会自动追加 ?_wrapper_format=drupal_htmx，触发 HtmxRenderer（无页面框架、无区块、无区域）。也可在 Twig 中直接写该属性。
  4. Boost（类 SPA 导航）：对容器应用 hx-boost 后，内部所有链接/表单变为 AJAX 驱动，替换 <body> 并更新 <title>；Drupal.behaviors 在每次交换后自动重新附加。
  5. 懒加载/无限滚动：使用 data-hx-trigger="revealed" 在元素进入视口时加载内容，data-hx-swap="outerHTML"。
  6. 操作前确认：使用 confirm() 方法。
  7. 从响应触发自定义 JS 事件：使用 triggerAfterSettleHeader，并在 Drupal.behaviors 中监听该事件。

五、Drupal.behaviors 集成 无需额外设置。core/drupal.htmx 库自动接线：htmx:drupal:load 在交换内容上调用 Drupal.attachBehaviors()；htmx:drupal:unload 在交换前调用 Drupal.detachBehaviors()。所有既有 JS behaviors 可透明作用于 HTMX 注入的内容。HTMX 响应中的 drupalSettings 由 htmx-utils.js 自动深合并到当前页面的 drupalSettings。

六、PHP 中检测 HTMX 请求 通过 Symfony Request 头判断：HX-Request 是否存在、HX-Trigger-Name（触发元素名）、HX-Current-URL。

七、缓存注意事项 HTMX 部分响应正常经过 Drupal 渲染缓存，需照常应用缓存元数据（tags、contexts、max-age）。HtmxRenderer 会自动添加已渲染缓存标签与所需缓存上下文。

八、Twig 中附加 HTMX 属性 使用 attach_library 附加库；可直接在 Twig 写属性。始终使用 data-hx-（而非裸 hx-），Drupal 实现采用 data- 前缀约定。

九、表单路由 URL 路由参数会作为额外参数传入 buildForm()。

十、常见错误 缺少库：未附加 core/drupal.htmx 时 HTMX 属性会渲染为静态 HTML，需在 libraries.yml 或 #attached 中附加。使用裸 hx-：Drupal 使用 data-hx-，构建器自动加 data- 前缀，Twig 中应写 data-hx-get。oob 触发时忘记 swap('none')：使用 swapOob 时触发元素自身也会被交换，除非设置 swap('none')。POST 的 CSRF：Drupal Form API 处理 CSRF 令牌；对控制器的非表单 HTMX POST，需添加路由要求 _csrf_token: 'TRUE' 并在 URL 追加 ?token={{ drupal_csrf_token(...) }}。目标占位符的原始标记：不要用 #markup 渲染独立的 HTMX 目标 div（会绕过 Drupal 渲染管线），应使用 #type => 'html_tag' 配合 #attributes；若目标可以是既有渲染元素的外层，则跳过单独 div，改用 applyTo() 配合 '#wrapper_attributes' 并在该元素上设置 #attributes['id']。