企业官网建设流程全解析

• 前端

htmx 在hx-preserve属性中集成了实验性的 [moveBefore()DOM API]，当浏览器支持时，它可以让你在通过 htmx 合并新内容、彻底改变页面布局的同时，将标记为hx-preserve的元素（如正在播放的视频、保持焦点的输入框）原封不动地“搬移”到新的父节点下，播放状态、焦点等全部保留。本文以仓库中的 move-before 示例 为主线，讲解如何在 Chrome Canary 中开启该 API、演示其效果、剖析 src/htmx.js 中的底层实现，并给出完整的hx-preserve使用要点、回退逻辑与测试依据。

背景：为什么需要 moveBefore()？

在传统的 Web 开发中，当一个 DOM 元素被“reparenting”（即改变其父节点）时，浏览器会重置该元素的状态：正在播放的<video>/<iframe>会停止播放，输入框的焦点与光标位置会丢失。这意味着，如果你希望在一次 AJAX 交换后彻底改变页面的布局结构（比如把视频从div里挪进figure里），几乎不可能不打断用户的观看体验。

现有的替代方案是 DOM morphing（变形），例如 morphdom 扩展 所采用的“新页面结构与旧页面足够接近”的策略——它通过逐节点对比来尽力保留元素。但这要求新页面的结构不能有大的变动，否则像视频这类元素仍然无法被保留。htmx 官方文档在 hx-preserve 属性说明 中也明确指出：某些元素（如<input type="text">的焦点和光标位置、iframe 或某些类型的视频）在常规保留策略下无法被完整保留，因此推荐 morphdom 做更细致的 DOM 对账。

moveBefore()为这一问题提供了根本解法：它允许开发者在一次原子操作中把元素从旧父节点移动到新父节点，而不触发布局重置，从而完全改变页面布局的同时保留元素的播放状态、焦点等。htmx 在hx-preserve功能中优先使用该 API（如果可用）。

在 Chrome Canary 中启用 moveBefore()

moveBefore()目前仍是实验性 API（WHATWG DOM 规范提案 issue #1255），该示例的演示需要安装Chrome Canary并手动开启对应 flag：

1. 安装 Chrome Canary 并打开浏览器；
2. 在地址栏导航到chrome://flags/#atomic-move；
3. 将"Atomic DOM move"标志设置为Enabled；
4. 重启浏览器使配置生效。

开启后，htmx 便会在hx-preserve功能中自动检测并使用moveBefore()API（详见下文源码分析）。如果你在 Chrome 稳定版或尚不支持该 API 的浏览器中运行，htmx 会自动回退到常规的replaceChild保留策略，功能依然可用，只是无法实现“跨父节点搬移且不重置状态”。

演示效果：从div到figure的布局切换

仓库中的 move-before 示例首页 展示了这一能力的核心场景：页面中嵌入了一个 YouTube iframe，它位于一个div内，并带有hx-preserve="true"和固定的id="rick-roll"：

<div class="center"> <iframe hx-preserve="true" id="rick-roll" width="617" height="351" src="https://www.youtube.com/embed/dQw4w9WgXcQ" title="Rick Astley - Never Gonna Give You Up (Official Music Video)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> <div> <a hx-boost="true" href="/examples/move-before/details">View Details &rarr;</a> </div> </div>

点击hx-boost="true"的"View Details"链接后，页面通过 hx-boost 发起整页级别的 AJAX 交换，过渡到 details 页面。在 details 页面中，响应里有一个相同id（rick-roll）的 iframe，但它被嵌入在figure元素中：

<figure> <iframe hx-preserve="true" id="rick-roll" width="617" height="351" src="https://www.youtube.com/embed/dQw4w9WgXcQ" title="Rick Astley - Never Gonna Give You Up (Official Music Video)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> <figcaption>A Classic Rick Roll</figcaption> </figure>

在没有moveBefore()的情况下，这种“从div的子节点变成figure的子节点”的 reparenting 必然导致视频重置。而开启该 API 后，视频会持续播放，并且点击浏览器返回键回到首页后依然可以继续观看。这正是hx-preserve与moveBefore()组合带来的核心价值：服务器端完全掌控布局结构，客户端无缝保留有状态元素。

源码剖析：htmx 如何在 hx-preserve 中集成 moveBefore()

htmx 对moveBefore()的集成位于 src/htmx.js 的handlePreservedElements函数中。当新响应中包含[hx-preserve]/[data-hx-preserve]元素时，htmx 会：

1. 读取该元素的id，并在当前文档中查找同 id 的现有元素；
2. 若找到，且该元素（或其父节点）支持moveBeforeAPI，则创建一个隐藏的“储藏间（pantry）”容器：

let pantry = find('#--htmx-preserve-pantry--') if (pantry == null) { getDocument().body.insertAdjacentHTML('afterend', "<div id='--htmx-preserve-pantry--'></div>") pantry = find('#--htmx-preserve-pantry--') }

3. 通过pantry.moveBefore(existingElement, null)把现有元素原子性地“暂存”到 pantry 中（而非销毁），随后继续执行交换逻辑；
4. 交换完成后，在 restorePreservedElements 中把元素从 pantry 搬回新文档中的目标位置：

existingElement.parentNode.moveBefore(preservedElt, existingElement) existingElement.remove()

也就是说，htmx 用moveBefore将元素从旧父节点移动到临时容器，再移动到新的父节点，全程都是“原子移动”而非“删除+重建”，因此视频播放、焦点等内部状态得以保留。

回退逻辑：如果当前环境不支持moveBefore（例如preservedElt.moveBefore为undefined），htmx 会退回到传统方案——用现有元素直接替换响应中的占位节点：

preservedElt.parentNode.replaceChild(existingElement, preservedElt)

此时元素仍能按id被保留，但无法跨父节点移动而不重置状态。这一分支同样体现在 测试用例 中：当把fragment.firstChild.moveBefore置为undefined后，handlePreservedElements会把旧内容直接复制进 fragment，模拟无 API 环境下的回退行为。

hx-preserve 使用要点

根据 hx-preserve 属性文档，使用时需要遵守以下规则：

• 必须设置不变的id：元素按id被保留，响应中必须包含相同id的元素；响应中该元素的类型和其他属性会被忽略；
• 写法上既可以使用hx-preserve="true"，也可以直接用布尔属性hx-preserve；
• hx-preserve不继承，只在显式标记的元素上生效；
• 与 History Support 配合时，浏览器后退/前进等操作也会保留hx-preserve元素的状态；
• 避免在可能包含hx-preserve元素的请求上使用hx-swap="none"，以免元素丢失；
• hx-preserve元素可以在 partial 或 OOB 响应中被重新定位——例如把视频从当前位置搬到新位置：

<div id="new_location"> Just relocated the video here <div id="video" hx-preserve></div> </div>

• 也可以用在 hx-swap-oob 元素的内部内容中：

<div id="notify" hx-swap-oob="true"> Notification updated but keep the same retain <div id="retain" hx-preserve></div> </div>

值得注意的是，常规保留策略下仍有一些元素无法被完整保留（如<input type="text">的焦点与光标位置、iframe 或某些视频），moveBefore()正是为攻克这类场景而生的增强路径。

测试与手动验证

仓库为hx-preserve提供了完善的自动化测试（test/attributes/hx-preserve.js），覆盖了以下关键行为：

• 基本响应处理：响应中带hx-preserve的元素内容保持为旧内容，其他元素被替换为新内容；
• 响应中不存在旧元素时，直接插入新内容；
• 当保留元素位于hx-select选区之外时不被交换；
• 当保留元素位于hx-swap-oob或hx-select-oob交换中时不被交换；
• OOB 交换将保留元素原封不动地搬移到新位置（旧位置清空、新位置收到完整旧内容）；
• moveBefore缺失时的回退复制行为。

此外，仓库还提供了可在真实浏览器中体验的 手动测试入口：页面提供两个按钮，分别通过hx-get加载 video1.html（iframe 直接位于顶层）和 video2.html（iframe 被嵌入在<section id="the-video">中），目标均为#video-container，并通过hx-push-url="true"保持 URL 与历史同步。两页中的 iframe 拥有相同的id="rick-roll"与hx-preserve="true"，配合moveBefore()即可实现在两种完全不同的布局间切换且视频不中断。在 Chrome Canary 中打开该入口文件，即可复现示例页面的完整效果。

局限与注意事项

• moveBefore()目前仍是实验性 API，仅在 Chrome Canary 中通过chrome://flags/#atomic-move开启 "Atomic DOM move" 后才可用；请勿在生产环境将其作为硬性依赖；
• 在支持该 API 的浏览器中，htmx 会自动优先使用moveBefore()；在不支持的浏览器中会自动回退到replaceChild保留策略，功能不失效，但跨父节点搬移时的状态保留能力受限；
• 若你的目标是“仅小范围微调 DOM 而不改变布局”，morphdom 扩展仍是更成熟的方案；moveBefore()的价值体现在需要彻底改变页面布局、同时又要保留视频/焦点等有状态元素的场景。

总之，hx-preserve+moveBefore()为 htmx 开发者打开了一类全新的可能性：让服务端自由地重新编排页面结构，而客户端依然能为用户保持流畅、不中断的体验。你可以直接在本仓库的 move-before 示例 与 手动测试 中验证这一能力。

• 前端