Node.insertBefore()
Node.insertBefore()
メソッドは、ノードを参照ノードの前に、指定された親ノードの子として挿入します。
指定されたノードが既に文書中に存在した場合、 insertBefore()
はこれを現在の位置から新しい位置に移動します。 (つまり、既存の親ノードから自動的に削除され、指定された新しい親に追加されます。)
これは、1つのノードが文書中に同時に2か所に存在できないことを意味します。
メモ: Node.cloneNode()
を使用して、ノードを新しい親の下に追加する前に複製を作成することができます。なお、 cloneNode()
で作成された複製は自動的には同期されません。
指定された子が DocumentFragment
である場合、 DocumentFragment
の内容全体が指定された親ノードの子リストに移動されます。
構文
let insertedNode = parentNode.insertBefore(newNode, referenceNode)
insertedNode
- 挿入されたノード (
newNode
と同じ) です。 parentNode
- 新しく挿入されるノードの親です。
newNode
- 挿入されるノードです。
referenceNode
-
newNode
がこのノードの直前に挿入されます。このノードがnull
である場合は、newNode
はparentNode
の子ノードの末尾に挿入されます。
返値
追加された子ノードを返します (ただし newNode
が DocumentFragment
の場合は、空の DocumentFragment
が返ります)。
例
例 1
<div id="parentElement">
<span id="childElement">foo bar</span>
</div>
<script>
// 挿入する新しいノードを作成する
let newNode = document.createElement("span")
// 親ノードの参照を取得する
let parentDiv = document.getElementById("childElement").parentNode
// テストケース [ 1 ] 開始: 既存の childElement (すべて正しく動作)
let sp2 = document.getElementById("childElement")
parentDiv.insertBefore(newNode, sp2)
// テストケース [ 1 ] 終了
// テストケース [ 2 ] 開始: childElement が undefined 型の場合
let sp2 = undefined // "childElement" の ID を持つノードが存在しない
parentDiv.insertBefore(newNode, sp2) // Node 型に暗黙に動的型変換
// テストケース [ 2 ] 終了
// テストケース [ 3 ] 開始: childElement が "undefined" (文字列) の場合
let sp2 = "undefined" // "childElement" の ID を持つノードが存在しない
parentDiv.insertBefore(newNode, sp2) // Generates "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
になります。その場合も、要素は親の最後の子の後に追加されます。
親要素が最初の子を持っていない場合は、最後の子も持っていません。結果的に、新しく挿入された要素は唯一の要素になります。
仕様書
仕様書 | 状態 | 備考 |
---|---|---|
DOM Node.insertBefore の定義 |
現行の標準 | 挿入アルゴリズムのエラーを修正 |
DOM4 Node.insertBefore の定義 |
廃止 | より詳細にアルゴリズムを記述 |
Document Object Model (DOM) Level 3 Core Specification Node.insertBefore の定義 |
廃止 | 目立った変更はなし |
Document Object Model (DOM) Level 2 Core Specification Node.insertBefore の定義 |
廃止 | 目立った変更はなし |
Document Object Model (DOM) Level 1 Specification Node.insertBefore の定義 |
廃止 | 導入 |
ブラウザーの互換性
BCD tables only load in the browser