Element: insertAdjacentHTML() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2018年4月.

insertAdjacentHTML() は Element インターフェイスのメソッドで、指定されたテキストを HTML または XML として解釈し、結果のノードを DOM ツリーの指定された位置に挿入します。

構文

insertAdjacentHTML(position, text)

引数

position

文字列で、要素の相対的な位置を表します。以下のいずれかでなければなりません。

"beforebegin"

要素の前。要素が DOM ツリー内にあり、親要素がある場合にのみ有効です。

"afterbegin"

要素のすぐ内側、最初の子の前。

"beforeend"

要素のすぐ内側、最後の子の後。

"afterend"

要素の後。要素が DOM ツリー内にあり、親要素がある場合にのみ有効です。

text

HTML または XML として解釈し、ツリーに挿入する文字列です。

返値

なし (undefined)。

例外

このメソッドは、以下の種類の DOMException を発生させることがあります。

NoModificationAllowedError DOMException

position が "beforebegin" または "afterend" で、要素が親を持っていないか、親が Document オブジェクトである場合に発生します。

SyntaxError DOMException

position が掲載されている 4 つの値のいずれでもない場合に発生します。

解説

insertAdjacentHTML() は挿入先の要素を再解釈するものではないため、既存の要素や要素内部の破壊を伴いません。余分なシリアル化のステップを回避できる分、innerHTML の操作よりもはるかに高速な動作となります。

挿入されるコンテンツの使用可能な位置は、以下のように可視化できます。

html
<!-- beforebegin -->
<p>
  <!-- afterbegin -->
  foo
  <!-- beforeend -->
</p>
<!-- afterend -->

HTML

html
<select id="position">
  <option>beforebegin</option>
  <option>afterbegin</option>
  <option>beforeend</option>
  <option>afterend</option>
</select>

<button id="insert">Insert HTML</button>
<button id="reset">Reset</button>

<p>
  Some text, with a <code id="subject">code-formatted element</code> inside it.
</p>

CSS

css
code {
  color: red;
}

JavaScript

js
const insert = document.querySelector("#insert");
insert.addEventListener("click", () => {
  const subject = document.querySelector("#subject");
  const positionSelect = document.querySelector("#position");
  subject.insertAdjacentHTML(
    positionSelect.value,
    "<strong>inserted text</strong>",
  );
});

const reset = document.querySelector("#reset");
reset.addEventListener("click", () => {
  document.location.reload();
});