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 である場合は、 newNodeparentNode の子ノードの末尾に挿入されます。

メモ: referenceNode は省略可能な引数ではありません。明示的に Node または null を渡す必要があります。渡し忘れた場合や無効な値を渡した場合は、ブラウザーのバージョンによって異なる動作をすることがあります。

返値

追加された子ノードを返します (ただし newNodeDocumentFragment の場合は、空の 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.nextSiblingnull を返し、 sp1 は子ノードリストの末尾 (sp2 の直後) に挿入されます。

例 3

要素を最初の子要素の前に挿入するために、 firstChild プロパティを使用します。

// 親ノードを取得
let parentElement = document.getElementById('parentElement')
// 親の最初の子を取得
let theFirstChild = parentElement.firstChild

// 新しい要素を取得
let newElement = document.createElement("div")

// 最初の子の前に新しい要素を挿入
parentElement.insertBefore(newElement, theFirstChild)

要素に最初の子がない場合、 firstChildnull になります。その場合も、要素は親の最後の子の後に追加されます。

親要素が最初の子を持っていない場合は、最後の子も持っていません。結果的に、新しく挿入された要素は唯一の要素になります。

仕様書

仕様書 状態 備考
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 の定義
廃止された 導入

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
insertBeforeChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 3IE 完全対応 9Opera 完全対応 7Safari 完全対応 1.1WebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 10.1Safari iOS 完全対応 1Samsung Internet Android 完全対応 1.0

凡例

完全対応  
完全対応

関連情報