JavaScript moveBefore() 怎麼用？搬動 DOM 時保留 focus、iframe 與動畫狀態

直接答案：呼叫目的容器的 moveBefore()#

moveBefore() 不是被搬動元素的方法，而是目的 Element 的方法。第二個參數是目的容器裡的 reference node；傳入 null 就代表放到子節點最後面：

1
<section id="inbox">
2
  <article id="card">
3
    <input id="card-input" value="保留目前輸入與 focus">
4
  </article>
5
</section>
6
<section id="archive"></section>

1
const card = document.querySelector('#card')
2
const archive = document.querySelector('#archive')
3
const input = document.querySelector('#card-input')
4

5
function moveCard() {
6
  if (!card || !archive) return
7

8
  if (typeof archive.moveBefore === 'function') {
9
    archive.moveBefore(card, null)
10
  } else {
11
    // 結構會正確，但 fallback 不保證保留 moveBefore 的狀態語意。
12
    archive.insertBefore(card, null)
13
  }
14

15
  console.log({
16
    parent: card.parentElement?.id,
17
    focusPreserved: document.activeElement === input,
18
  })
19
}

呼叫前先讓 input 取得 focus，再執行 moveCard()，就能在支援的瀏覽器中觀察 focus 是否仍在原本的輸入框。這個範例只負責示範原生 DOM API；實際專案仍要把按鈕事件、空值檢查和 UI 狀態管理接到自己的元件邊界。

它保留什麼，不能保證什麼？#

依 MDN 的說明，moveBefore() 和一般 remove／reinsert 不同之處，在於它不會先把節點移除再插回去，因此可保留這些狀態：

<video> 與 <audio> 的播放狀態本來就能在一般移除再插入時保留，因此不能把它們當成 moveBefore() 獨有的效果。另一方面，MutationObserver 仍會把這次移動記錄成 removed node 和 added node；如果你的同步邏輯依賴 observer，不能把 moveBefore() 當成「完全沒有 DOM 變更」。

與 insertBefore() 的差別#

兩個 API 都能把節點放到指定位置，但使用情境不同：

不要只因為兩個方法的參數看起來相同，就把 insertBefore() 無條件換成 moveBefore()。先確認這個節點確實是「搬動」而非第一次插入，也確認目的容器與節點在相同 document。

Fallback 與 Safari 支援邊界#

目前 MDN 將 moveBefore() 標為 Limited availability，不能假設所有使用者的瀏覽器都有這個方法。因此應該在真正需要時做 feature detection：

1
function moveNode(target, node, reference = null) {
2
  if (typeof target.moveBefore === 'function') {
3
    target.moveBefore(node, reference)
4
    return 'moveBefore'
5
  }
6

7
  target.insertBefore(node, reference)
8
  return 'insertBefore-fallback'
9
}

Fallback 的目標是讓結構和功能仍能運作，不是偽造同等的狀態保留。如果 focus、iframe 或 popover 的狀態是產品必要條件，應在不支援的瀏覽器測試實際體驗；必要時改用保持節點掛載、CSS 改變位置，或由元件框架提供的 portal／teleport 機制，而不是只接受狀態重置。

先處理 moveBefore() 的使用限制#

這個 API 不是任意 DOM reparenting 的通用替代品。呼叫前要確認：

• 搬動的節點和目的容器位於同一個 document。
• 不要把祖先節點搬到自己的子孫裡，也不要把 reference node 傳成目的容器的非直接子節點。
• 搬動節點和目的容器的連接狀態要相容；把 detached node 直接搬到已連接 parent，或反過來，會拋出 HierarchyRequestError。
• movedNode 要是 Element 或 CharacterData，第二個參數即使要追加到末端也要明確傳 null。
• 如果節點是 custom element，要考慮它的 lifecycle callback；有狀態的 custom element 可以設計 connectedMoveCallback() 來區分搬動和真正的斷線／重連。

遇到動態 UI，先把「同文件、已連接、reference 是直接子節點」列為 assertion 或測試條件，再決定是否使用這個 API。對不符合條件的資料流程，保留 insertBefore() 通常比包一層無限重試安全。

用可觀察的條件驗證狀態是否真的保留#

不要只看卡片最後出現在哪裡。可以在 demo 或端對端測試中記錄搬動前後的條件：

1
const before = {
2
  activeElement: document.activeElement,
3
  iframe: document.querySelector('#player'),
4
  cardParent: card.parentElement,
5
}
6

7
moveNode(archive, card, null)
8

9
console.table({
10
  moved: card.parentElement === archive,
11
  focusKept: document.activeElement === before.activeElement,
12
  iframeSameNode: document.querySelector('#player') === before.iframe,
13
})

這裡的 iframeSameNode 只能證明 DOM 節點沒有換成另一個節點；loading state 是否如預期，仍要在實際瀏覽器與網路條件下測試。若使用 MutationObserver、自訂元素或 framework reconciliation，也要把那些 callback 和 rerender 行為納入測試，不要只測單一 API 呼叫。

Framework 元件要先確認誰擁有 DOM#

在 React、Vue、Svelte 或其他會自行 reconcile 的元件中，直接把 framework 管理的節點搬到另一個容器，下一次 render 可能又把它移回去或重建。這時應先使用框架提供的 key、portal、teleport 或 slot 機制；moveBefore() 比較適合由原生 DOM 程式明確管理生命週期的區域。

如果是 custom element，moveBefore() 仍可能觸發與搬動相關的 lifecycle 流程；把初始化和清理邏輯全放在 connectedCallback()／disconnectedCallback()，可能讓搬動看起來像元件被銷毀。設計 connectedMoveCallback() 時，仍要測真正的 remove、重新插入和 move 三種情境。

結論：先用 feature detection，再決定能否保留狀態#

moveBefore() 的價值不只是少打一個方法名稱，而是把「搬動節點」和「移除後重新插入」的狀態語意分開。對同一份、已連接的 DOM，先用 typeof target.moveBefore === 'function' 偵測，再以明確的 fallback 和端對端檢查保護 focus、iframe、動畫與互動狀態；對不支援或不符合限制的流程，就誠實接受 fallback 的差異或改用保持掛載的 layout 設計。

常見問題#