정의 및 사용 방법

insertAdjacentHTML() 함수는
지정된 요소의 인접한(Adjacent) 특정 위치에 HTML 코드를 문자열로 삽입(insert)하여 새로운 DOM 요소를 생성합니다.

구문

insertAdjacentHTML() 함수는 지정된 요소(element)의 인접한 위치에(position) 전달받은 HTML 코드 문자열(string)을 HTML(혹은 XML)로 파싱하여 DOM 요소를 생성합니다.

JavaScript 
element.insertAdjacentHTML(position, string)

element는 insertAdjacentHTML() 함수를 적용할 지정된 요소입니다.

매개변수

insertAdjacentHTML() 함수의 매개변수
position 지정된 요소(element)의 인접한 위치를 나타내는 문자열입니다. 다음 문자열 중에서 하나이여야 합니다.
  • "beforebegin": element 바로 앞
  • "afterbegin": element 안쪽 시작 부분
  • "beforeend": element 안쪽 끝 부분
  • "afterend": element 바로 뒤
string 삽입할 HTML(혹은 XML) 코드 문자열입니다. 이 문자열이 DOM 트리에 파싱되어 요소의 인접한 위치에 추가됩니다.

즉, 지정된 요소(element)의 인접한 위치

  • "beforebegin" (바로 앞)
  • "afterbegin" (안쪽 시작 부분)
  • "beforeend" (안쪽 끝 부분)
  • "afterend" (바로 뒤)

중 하나의 위치를 선택하여 HTML 코드를 문자열로 삽입하여 새로운 DOM 요소를 생성합니다.

기본 예제

요소의 인접한 특정 위치를 시각화하면 다음과 같습니다.

HTML 요소의 인접한 특정 위치은 주석으로 나타냈습니다. 
<!-- beforebegin (바로 앞) -->
<div id="my-div" style="background: gold;"> <!-- 지정된 요소 -->
    <!-- afterbegin (안쪽 시작 부분) -->
    Content
    <!-- beforeend (안쪽 끝 부분)-->
</div>
<!-- afterend (바로 뒤) -->
JavaScript 
const ele = document.getElementById("my-div"); // 지정된 요소(element)

/*
 * element.insertAdjacentHTML(position, string)
 * 지정된 요소(element)의
 * 인접한 위치에(position) 전달받은
 * HTML 코드 문자열(string)을 HTML(혹은 XML)로 파싱하여
 * DOM 노드를 생성합니다.
*/

// 요소 바로 앞 새로운 HTML 코드 삽입
ele.insertAdjacentHTML("beforebegin", "<p>(Before begin)</p>");

// 요소 안쪽 시작 부분, 즉 첫 번째 자식으로 HTML 코드 삽입
ele.insertAdjacentHTML("afterbegin", "<p>(After begin)</p>");

// 요소 안쪽 끝 부분, 즉 마지막 자식으로 HTML 코드 삽입
ele.insertAdjacentHTML("beforeend", "<p>(Before end)</p>");

// 요소의 뒤에 새로운 HTML 코드 삽입
ele.insertAdjacentHTML("afterend", "<p>(After end)</p>");

코드 부연설명
getElementById() 함수는 주어진 문자열과 값이 일치하는 id 속성의 값을 가진 요소 객체를 반환합니다.

실제 적용된 모습

전달받은 HTML 코드 문자열(string)이 코드가 포함되어 있지 않은 단순한 텍스트일 경우에는 텍스트를 삽입합니다.

반환 값

없습니다. 즉, undefined를 반환합니다.

예외

insertAdjacentHTML() 함수는 다음의 경우에 예외를 발생시킵니다.

NoModificationAllowedError

position이 "beforebegin" 또는 "afterend"이고 요소에 부모를 가지고 있지 않거나 부모가 Document 객체인 경우 NoModificationAllowedError를 던집니다.

SyntaxError

position이 지정된 문자열("beforebegin", "afterbegin", "beforeend", "afterend")이 아닌 경우 SyntaxError를 던집니다.

insertAdjacentHTML()과 insertAdjacentText() 차이

insertAdjacentHTML()과 insertAdjacentText()는 언뜻 비슷해 보이지만 중요한 차이점이 있습니다.

insertAdjacentHTML()

  • HTML(혹은 XML) 코드를 문자열로 삽입하는 데 사용됩니다.
  • 삽입되는 내용이 HTML(혹은 XML) 태그일 경우, 해당 태그가 실제로 해석되어 DOM에 요소로 추가됩니다.
  • 따라서, HTML(혹은 XML) 구조를 변경하거나 새로운 요소를 생성할 수 있습니다.

insertAdjacentText()

  • 텍스트를 삽입하는 데 사용됩니다.
  • 삽입되는 텍스트에 HTML(혹은 XML) 태그가 포함되어 있을 경우, 자동으로 이스케이프 처리되어 실제 HTML 요소로 해석되지 않고, 사용자에게 보여지는 텍스트로 변환됩니다.

HTML 태그를 이스케이프 처리한다는 것은 예를 들어, < 기호는 HTML의 시작 태그로 인식되기 때문에, <라는 기호만을 그대로 기재하면 브라우저에서의 표시에 문제가 생기거나 표시되지 않거나 합니다. 이것을 이스케이프 처리하면 HTML의 특수 문자로 해당하는 기호로 변환해서 사람이 볼 수 있게 한다는 것을 의미합니다.
HTML 특수 문자 사용법과 의의 – 예약된 문자와의 충돌을 피하며 웹 콘텐츠 작성하기를 참고하세요!

이 두 함수는 사용 목적이 다르기 때문에, 상황에 맞게 적절한 함수를 선택하여 사용하는 것이 중요합니다. 예를 들어, 단순한 텍스트 삽입에는 insertAdjacentText()를 사용하고, HTML(혹은 XML) 구조를 변경해야 할 때는 insertAdjacentHTML()을 사용합니다.

예제

다음은 일반적으로 가장 많이 사용되는 insertAdjacentHTML() 함수에 관련된 예제입니다.

CSS 
#container {
    border: 1px solid red;
    margin-bottom: 1em;
}
#container span {
    color: red;
}
HTML 요소의 인접한 특정 위치은 주석으로 나타냈습니다. 
<!-- beforebegin (바로 앞) -->
<div id="container">
    <!-- afterbegin (안쪽 시작 부분) -->
    <span>Content</span>
    <!-- beforeend (안쪽 끝 부분)-->
</div>
<!-- afterend (바로 뒤) -->
<button type="button" id="btn">HTML 삽입하기</button>
JavaScript 
const ele = document.getElementById("container");
const btn = document.getElementById("btn");

btn.addEventListener("click", () => {
    ele.insertAdjacentHTML("beforebegin", "<p>beforebegin 삽입</p>");
    ele.insertAdjacentHTML("afterbegin", "<p>afterbegin 삽입</p>");
    ele.insertAdjacentHTML("beforeend", "<p>beforeend 삽입</p>");
    ele.insertAdjacentHTML("afterend", "<p>afterend 삽입</p>");
});
실제 적용된 모습 '버튼'을 실제로 클릭해 보세요!

위 예제처럼 insertAdjacentHTML() 함수는 기존의 요소에는 영향을 주지 않고 새로운 콘텐츠만을 HTML(혹은 XML)로 파싱하여 DOM 노드를 생성해서 삽입하기 때문에 HTML 마크업 콘텐츠를 새로 대체하면 기존 콘텐츠를 모두 제거하고 다시 처음부터 새롭게 새로운 콘텐츠를 DOM에 대체하는 innerHTML 속성에 비해서 효율적이고 빠릅니다.

주의할 점

HTML 문자열을 그대로 파싱하여 DOM에 삽입하므로, 사용자 입력을 직접 삽입하는 경우 등 제어할 수 없는 문자열을 설정할 때에는 보안적인 측면을 항상 고려해야 합니다.

JavaScript 
const userInput = "<img src='x' onerror='document.cookie)'>";
el.insertAdjacentHTML("beforeend", userInput);

위 예제처럼 사용자 입력을 직접 삽입하는 경우에는 insertAdjacentHTML() 함수를 사용하지 마세요. 사용자 입력을 삽입하려면 단순히 원시 텍스트(raw text)를 처리하는 textContent 속성이나 insertAdjacentText()를 사용하세요.

브라우저 호환성

insertAdjacentHTML() 함수의 브라우저 호환성
메서드
데스크탑 Chrome
Chrome
데스크탑데스크탑 Edge
Edge
데스크탑 Firefox
Firefox
Safari
Safari
insertAdjacentHTML() 1 17 8 4

명세서

insertAdjacentHTML() 함수의 명세서 사양
명세서 사양
insertAdjacentHTML() HTML Standard
#the-insertadjacenthtml()-method

참고문헌

같이 보기