Node: replaceChild() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

replaceChild()Node インターフェイスのメソッドで、この(親)ノードの中の子ノードを置き換えます。

構文

js
replaceChild(newChild, oldChild)

引数

newChild

oldChild を置き換える新しいノードです。

警告: 新しいノードが既に DOM のどこか別なところにある場合は、まずその位置から取り除かれます。

oldChild

置き換えられる子ノードです。

メモ: 引数の順序で、新しいものの前に古いものが来るのは異例です。 Element.replaceWith() は、要素であるノードのみに適用されるものですが、読んだり使用したりしやすいかもしれません。

返値

置き換えられた Node です。これは oldChild と同じノードです。

例外

HierarchyRequestError DOMException

DOM ツリーの制約に違反した場合に発生します。すなわち、以下のいずれかが発生する場合です。

  • oldChild の親が Document, DocumentFragment, Element のいずれにもならない場合。
  • oldChildnewChild で置き換えると循環参照になる場合。すなわち newChild がこのノードの祖先である場合。
  • newChildDocumentFragment, DocumentType, Element, CharacterData のいずれでもない場合。
  • 現在のノードが Text であり、親ノードが Document になる場合。
  • 現在のノードが DocumentType であり、その親が Document にならない場合。 doctype は常に document の直下になければならないからです。
  • このノードの親が DocumentnewChildDocumentFragment であり、複数の Element の子、または Text の子がある場合。
  • oldChildnewChild で置き換えると、 Document の子の Element が複数になる場合。
  • oldChildnewChild で置き換えると、 Element ノードが DocumentType の前になる場合。
NotFoundError DOMException

oldChild の親ノードが現在のノードではない場合に発生します。

js
// 前提:
// <div>
//  <span id="childSpan">foo bar</span>
// </div>

// ID も属性も内容も持たない空要素を生成
const sp1 = document.createElement("span");

// 生成したノードに id 属性 'newSpan' を付与
sp1.id = "newSpan";

// 新しい要素にいくらかの内容を作成
const sp1_content = document.createTextNode("新しい置換 span 要素");

// その内容を新しい要素に適用
sp1.appendChild(sp1_content);

// 置き換えられる既存のノードの参照を作る
const sp2 = document.getElementById("childSpan");
const parentDiv = sp2.parentNode;

// 既存のノード sp2 を新しい span 要素 sp1 で置換
parentDiv.replaceChild(sp1, sp2);

// 結果:
// <div>
//   <span id="newSpan">新しい置換 span 要素</span>
// </div>

仕様書

Specification
DOM Standard
# dom-node-replacechild

ブラウザーの互換性

BCD tables only load in the browser

関連情報