状態を失わずにDOMノードを移動する
Element.moveBefore()でDOMノードを移動し、iframe、フォーカス、アニメーション、ダイアログの状態を保つ方法を解説。構文や制約、代替策も紹介します。
Element.moveBefore() は、ドキュメント内にすでに存在するノードを移動します。その際、appendChild() や insertBefore() が行う「削除してから挿入する」という処理を経ません。そのため、<iframe> は読み込み済みのページを保持し、フォーカスされた入力欄はフォーカスを維持し、実行中のCSSアニメーションも途切れません。
ライブな要素の親を付け替えた経験がある開発者の多くは、次のような問題に直面したことがあるでしょう。カードを別の列にドラッグすると、その中に埋め込まれたプレーヤーが真っ白になって再読み込みされる。あるいは、入力中のフィールドが単語の途中でフォーカスを失う。
Chromeは Chrome 133 で moveBefore() をリリースしており、この機能は Chrome 133 のリリースノートに「DOM state-preserving move」として記載されています。本記事では、構文、デモ、保持される状態の正確な一覧、エラーケース、カスタム要素のフック、そして安全なフォールバックについて解説します。まず基本を復習したい場合は、JavaScriptでDOMを扱うおよび DOM要素のライフサイクルを参照してください。
重要なポイント
parent.moveBefore(node, ref)はinsertBefore()と同じ引数を取りますが、ノードを削除・再挿入せずに移動します。そのため、iframe、フォーカス、アニメーション、ポップオーバー、モーダルダイアログの状態が保持されます。- 移動するノードは Element または CharacterData ノードでなければなりません。ドキュメント間の移動、接続済みツリーと未接続ツリー間の移動、ノード自身の子孫への移動は
HierarchyRequestErrorをスローします。 MutationObserverは、moveBefore()による移動を引き続き1件の削除と1件の追加として検知します。connectedMoveCallback()を定義したカスタム要素では、disconnectedCallback()とconnectedCallback()の代わりにこのコールバックが呼ばれます。- Safari は
moveBefore()をサポートしていないため、'moveBefore' in Element.prototypeで確認し、insertBefore()にフォールバックしてください。
なぜ appendChild と insertBefore は状態をリセットするのか
appendChild() や insertBefore() による移動は、実際には2つの操作で構成されています。ブラウザはノードをドキュメントから削除し、その後再び挿入します。Chromeチームのリリース記事でも指摘されているとおり、DOMには初期の標準以来、ノードを移動する別の手段が存在しませんでした。ノードを削除すると、接続中にのみ存在する状態が破棄されます。iframe はドキュメントをアンロードして再読み込みし、フォーカスされた要素はフォーカスを失い、CSSアニメーションは最初からやり直しになり、開いているポップオーバーやモーダルダイアログは閉じられます。
並べ替え可能なダッシュボードのセッションリプレイでは、このバグは典型的に次のように現れます。ユーザーがカードをドラッグしてそのまま入力を続けても、フィールドがフォーカスを失っているためキー入力が反映されない。また、埋め込まれた iframe がセッションの途中で目に見えて再読み込みされる。
moveBefore() の構文
moveBefore() は insertBefore() と同じ2つの引数を取ります。移動するノードと参照ノードです。参照ノードに null を渡すと、ノードは親の子要素の末尾に移動します。
parent.moveBefore(movedNode, referenceNode);
parent.moveBefore(movedNode, null); // append
MDNの moveBefore() リファレンスによると、移動するノードは Element または CharacterData ノードでなければなりません。テキストノードは許可されますが、たとえばドキュメントタイプは許可されません。このメソッドは Document と DocumentFragment にも存在するため、フラグメントがドキュメントに接続されることはなくても、フラグメント内でノードを移動できます。このメソッドは DOM Living Standard で定義されています。
デモ: moveBefore を使う場合と使わない場合の iframe の移動
違いを最も手早く確認できるのは、独自の内部状態を持つ iframe です。このデモでは srcdoc を使用しているため、ネットワークリクエストは発生しません。
<div id="left" class="box">
<iframe id="frame" srcdoc="<button onclick='this.textContent=++n'>0</button><script>let n=0</script>"></iframe>
</div>
<div id="right" class="box"></div>
<button id="viaInsert">Move with insertBefore()</button>
<button id="viaMove">Move with moveBefore()</button>
<script>
const frame = document.getElementById('frame');
const left = document.getElementById('left');
const right = document.getElementById('right');
const target = () => (frame.parentElement === left ? right : left);
document.getElementById('viaInsert').onclick = () =>
target().insertBefore(frame, null); // iframe reloads, counter back to 0
document.getElementById('viaMove').onclick = () =>
target().moveBefore(frame, null); // counter value survives
</script>
フレーム内のカウンターを何回かクリックしてから、それぞれのボタンを試してみてください。insertBefore() ではフレームが再読み込みされ、カウンターはゼロに戻ります。moveBefore() ではカウントが保持されます。2つ目のボタンは、このメソッドをサポートしているブラウザでのみ動作します(後述の機能検出のセクションを参照してください)。
フォーカスも同様の挙動を示します。
const input = document.querySelector('#note');
input.focus();
sidebar.moveBefore(input, null);
console.log(document.activeElement === input); // true
// With sidebar.insertBefore(input, null), focus is lost
moveBefore() はどの状態を保持するのか
moveBefore() が保持するのは、MDNに記載されている特定の状態のセットです。あらゆる状態を保持するわけではありません。
- アニメーションとトランジションの状態
<iframe>の読み込み状態:focusと:active- フルスクリーン要素の状態
- ポップオーバーの開閉状態
- モーダル
<dialog>の状態
ネイティブの <video> 要素や <audio> 要素は、appendChild() や insertBefore() で移動しても再生状態を保持します。したがってメディアに関しては、moveBefore() が意味を持つのは、サードパーティの動画埋め込みのようにプレーヤーが <iframe> 内に埋め込まれている場合であり、ネイティブのメディア要素ではありません。
moveBefore() のエラーと制約
moveBefore() は insertBefore() よりも厳格です。insertBefore() であれば暗黙的に削除と挿入を行うケースでも、moveBefore() は例外をスローします。
| エラー | 発生条件 | 対処法 |
|---|---|---|
HierarchyRequestError | 接続済みツリーと未接続ツリーの間で移動した場合 | insertBefore() を使用する |
HierarchyRequestError | ドキュメント間で移動した場合 | insertBefore() を使用する(または先に adoptNode() を実行する) |
HierarchyRequestError | ノードを自身の子孫に移動した場合 | 移動先を修正する(ロジックのバグです) |
HierarchyRequestError | movedNode が Element でも CharacterData でもない場合 | insertBefore() を使用する |
NotFoundError | referenceNode が親の子ではない場合 | 実在する子要素か null を渡す |
TypeError | 第2引数が省略された場合 | 末尾に追加するには明示的に null を渡す |
TypeError の行は、insertBefore() を使うときの癖が持ち越されるため、つまずきやすいポイントです。引数を1つだけ渡して moveBefore(node) と呼び出しても、末尾への追加はできません。
MutationObserver と connectedMoveCallback
MutationObserver は、moveBefore() で移動されたノードを引き続き1件の削除ノードと1件の追加ノードとして記録します。そのため、既存のオブザーバーは移動についてもレコードを受け取り続けます。DOM Standardの移動手順(move steps)では、元の親に対する削除レコードと新しい親に対する追加レコードがキューに入れられます。削除を「破棄された」とみなすコードで、移動と削除を区別する必要がある場合は、別のシグナルが必要です。オブザーバーのセットアップについては、3つのDOMオブザーバーAPIを参照してください。
カスタム要素には、移動専用のフック connectedMoveCallback() が用意されています。MDNのカスタム要素ガイドで説明されているとおり、connectedMoveCallback() が定義されている場合、要素が Element.moveBefore() によってDOM内の別の場所に移動されるたびに、connectedCallback() と disconnectedCallback() の代わりにこのコールバックが呼び出されます。
class DashCard extends HTMLElement {
connectedCallback() { /* initial setup: subscriptions, timers */ }
disconnectedCallback() { /* teardown */ }
connectedMoveCallback() { /* runs instead of the two above on moveBefore() */ }
}
customElements.define('dash-card', DashCard);
クラスで connectedMoveCallback() が定義されていない場合、moveBefore() による移動でも disconnectedCallback() が実行され、続いて connectedCallback() が実行されます。このメソッドを定義すれば、たとえ空の関数であっても、この2つのコールバックの組み合わせが置き換えられます。この挙動は HTML仕様で規定されています。
moveBefore の機能検出とフォールバック
メソッドを呼び出す前に 'moveBefore' in Element.prototype を確認してください。メソッドが存在しない場合に加え、insertBefore() なら受け付けるはずの移動に対して HierarchyRequestError がスローされた場合にも、insertBefore() にフォールバックします。caniuse によると、Chrome および Edge 133以降、Firefox 144以降がサポートしており、Safari はサポートしていません。web-features では、Baseline ではなく Limited availability として記載されています。
function moveNode(parent, node, ref = null) {
if ('moveBefore' in Element.prototype) {
try {
parent.moveBefore(node, ref);
return;
} catch (err) {
if (err.name !== 'HierarchyRequestError') throw err; // NotFoundError etc. are real bugs
}
}
const active = document.activeElement;
parent.insertBefore(node, ref); // state-resetting path
if (active && node.contains(active)) active.focus();
}
insertBefore() へのフォールバックでは、従来どおり iframe が再読み込みされ、アニメーションが再開され、ダイアログが閉じられます。フォーカスの復元はフォーカスを戻すだけであり、キャレット位置は保証されません。また、このチェックが対象とするのは Element の親のみです。Document や DocumentFragment がこのメソッドをサポートしているかどうかは判定できません。
まとめ
moveBefore() によって、DOMは初めて真の「移動」操作を手にしました。MDNに記載された制約の範囲内であれば、1回の呼び出しで iframe の読み込み状態を保ち、フォーカスを維持し、アニメーションを継続させることができます。ドラッグ&ドロップやモーフィングのコードの中で、ライブなノードを移動している appendChild() や insertBefore() の呼び出しをすべて洗い出し、moveNode() のようなヘルパー経由に置き換えましょう。そして、位置が変わったときにセットアップ処理を再実行すべきでないカスタム要素には、connectedMoveCallback() を追加してください。
よくある質問
moveBefore() で要素をシャドウルートの内外に移動できますか?
はい。ShadowRoot は DocumentFragment を継承しているため、独自の moveBefore() メソッドを持っています。移動は同一の shadow-including root 内にとどまる必要がありますが、接続済みのシャドウルートであれば、同じドキュメントに接続されているあらゆるノードについてこの要件を満たします。ライトDOMのコンテンツを接続済みのシャドウツリーに移動した場合も、フォーカス、iframe の読み込み状態、その他MDNに記載された状態が保持されます。
新しく作成した要素を挿入すると、なぜ moveBefore() は例外をスローするのですか?
document.createElement() で作成した要素は、まだドキュメントに接続されていません。未接続のノードを接続済みの親に移動しようとすると、HierarchyRequestError がスローされます。最初の挿入には appendChild() または insertBefore() を使用してください。一度も接続されたことのないノードには、保持すべき iframe、フォーカス、アニメーションの状態が存在しないため、失われるものはありません。moveBefore() はそれ以降の移動にのみ使用してください。
Safari 向けに moveBefore() をポリフィルできますか?
いいえ。ポリフィルで insertBefore() を呼び出す moveBefore() メソッドを追加することはできますが、それはメソッド名を模倣しているにすぎません。移動中に iframe のドキュメント、フォーカス、アニメーション、開いているポップオーバーを維持しているのはブラウザエンジンであり、JavaScript ではそれを実現できません。ネイティブサポートのないブラウザでは、シムは insertBefore() とまったく同じように動作し、同じ状態をリセットします。
moveBefore() をすでに使用しているライブラリはありますか?
はい。htmx は2024年10月にリリースされたバージョン 2.0.3 で moveBefore() のサポートを追加しました。ブラウザが moveBefore() を提供している場合、htmx はコンテンツのスワップ時に hx-preserve が指定された要素の移動にこのメソッドを使用するため、それらの要素は状態を保持します。このメソッドがないブラウザでは、htmx は通常の動作に戻り、従来の削除と挿入による方法で要素を移動します。