Node: insertBefore() メソッド
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2015年7月.
insertBefore() は Node インターフェイスのメソッドで、参照先ノードの前にこの親ノードの子としてノードを挿入します。
指定されたノードが既に文書中に存在した場合、 insertBefore() はこれを現在の位置から新しい位置に移動します。（つまり、既存の親ノードから自動的に削除され、指定された新しい親に追加されます。）
これは、 1 つのノードが文書中に同時に 2 か所に存在できないことを意味します。
メモ: Node.cloneNode() を使用すると、ノードを新しい親の下に追加する前に複製を作成することができます。なお、 cloneNode() で作成された複製は自動的には同期されません。
指定された子が DocumentFragment である場合、 DocumentFragment の内容全体が指定された親ノードの子リストに移動されます。
構文
insertBefore(newNode, referenceNode) 引数
newNode-
挿入するノードです。
referenceNode-
newNodeが挿入される位置の前にあるノードです。このノードがnullである場合は、newNodeはこのノードの子ノードの末尾に挿入されます。
返値
追加された子ノードを返します（ただし newNode が DocumentFragment の場合は、空の DocumentFragment を返します）。
例外
挿入前の検証
例
例 1
<div id="parentElement"> <span id="childElement">foo bar</span> </div> <script> // 挿入する新しいノードを作成する const newNode = document.createElement("span"); // 親ノードの参照を取得する const parentDiv = document.getElementById("childElement").parentNode; // テストケース [ 1 ] 開始: 既存の childElement (すべて正しく動作) let sp2 = document.getElementById("childElement"); parentDiv.insertBefore(newNode, sp2); // テストケース [ 1 ] 終了 // テストケース [ 2 ] 開始: childElement が undefined 型の場合 sp2 = undefined; // "childElement" の ID を持つノードが存在しない parentDiv.insertBefore(newNode, sp2); // Node 型に暗黙に動的型変換 // テストケース [ 2 ] 終了 // テストケース [ 3 ] 開始: childElement が "undefined" (文字列) の場合 sp2 = "undefined"; // "childElement" の ID を持つノードが存在しない parentDiv.insertBefore(newNode, sp2); // "Type Error: Invalid Argument" が発生 // テストケース [ 3 ] 終了 </script> 例 2
<div id="parentElement"> <span id="childElement">foo bar</span> </div> <script> // 新しいただの <span> 要素を作成 let sp1 = document.createElement("span"); // 参照要素を取得 let sp2 = document.getElementById("childElement"); // 親要素を取得 let parentDiv = sp2.parentNode; // 新しい要素を sp2 の手前に挿入 parentDiv.insertBefore(sp1, sp2); </script> メモ: insertAfter() メソッドはありません。 これは insertBefore メソッドと Node.nextSibling の組み合わせでエミュレートできます。
前の例では、 sp1 は以下のようにして sp2 の後に挿入することができます。
parentDiv.insertBefore(sp1, sp2.nextSibling); sp2 に次の兄弟ノードがない場合、これが最後の子ノードです。 — sp2.nextSibling は null を返し、 sp1 は子ノードリストの末尾（sp2 の直後）に挿入されます。
例 3
要素を最初の子要素の前に挿入するために、 firstChild プロパティを使用します。
// 親ノードを取得 let parentElement = document.getElementById("parentElement"); // 親ノードの最初の子ノードを取得 let theFirstChild = parentElement.firstChild; // 新しい要素を取得 let newElement = document.createElement("div"); // 最初の子ノードの前に新しい要素を挿入 parentElement.insertBefore(newElement, theFirstChild); 要素に最初の子ノードがない場合、 firstChild は null になります。その場合も、要素は親ノードの最後の子ノードの後に追加されます。
親要素に最初の子ノードがない場合は、最後の子ノードもありません。結果的に、新しく挿入された要素は唯一の要素になります。
仕様書
| Specification |
|---|
| DOM # dom-node-insertbefore |