JavaScript метод Node.appendChild()

Определение и применение

JavaScript метод .appendChild() объекта Node позволяет добавить узел в конец списка дочерних элементов указанного родительского узла.

Метод возвращает добавленный узел. Если передан DocumentFragment, перемещаются все его дочерние узлы, а результатом становится опустевший фрагмент.

Посмотрите пример с DocumentFragment и возвращаемым значением.

Поддержка браузерами

Спецификация: dom.spec.whatwg

Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры
Совместимостьapi.Node.appendChild
ВозможностьКомпьютерыМобильные
ChromeEdgeFirefoxOperaSafariChrome AndroidFirefox for AndroidOpera AndroidSafari on iOSSamsung BrowserWebView AndroidWebView on iOS
appendChild✓1✓12✓1✓7✓1.1✓18✓4✓10.1✓1✓1.0✓4.4✓1

поддерживаетсяс ограниченияминет поддержкинет данных≤31 — не позднее версии 31

JavaScript синтаксис

JavaScript
parentElement.appendChild(childElement);

Спецификация

DOM Standard.

Значения параметров

Параметры Node.appendChild()
Параметр Описание
childElement Объект узла, который необходимо добавить в конец списка дочерних элементов указанного родительского узла. Обязательный параметр.

Исключения

Исключения Node.appendChild()
Тип исключения Описание
HierarchyRequestError Возникает, если вставка нарушает структуру дерева: например, создаёт цикл, добавляет детей недопустимому типу узла или второй корневой элемент в Document.
TypeError Возникает, если аргумент не является объектом Node.

Пример использования

Добавление нового элемента в конец списка

Нажмите ▶, затем Append new element несколько раз: каждый щелчок добавляет новый пункт в конец списка.

index.html
HTML
<button data-migration-click-0="">Append new element</button>
<ul id="first"></ul>
main.js
JavaScript
function myFunc() {
    const firstUl = document.getElementById('first'),
        newElem = document.createElement('li'),
        text = document.createTextNode("I\'m just a text")
    newElem.appendChild(text)
    firstUl.appendChild(newElem)
}

// Обработчики кнопок перенесены из HTML для запуска с CSP без inline-скриптов.
document.querySelector('[data-migration-click-0]').addEventListener('click', function () {
    myFunc()
})
document.querySelector('[data-migration-click-0]').removeAttribute('data-migration-click-0')

В этом примере с использованием метода addEventListener() при нажатии на кнопку (HTML элемент <button>) вызываем функцию myFunc(), которая:

  • С использованием JavaScript метода getElementById() объекта Document выбирает элемент с определенным глобальным атрибутом id и инициализирует переменную этим значением.
  • С использованием JavaScript метода createElement() объекта Document создает новый пустой элемент <li>.
  • С использованием JavaScript метода createTextNode() объекта Document создает узел с текстовым содержимым.
  • С использованием метода .appendChild() объекта Node добавляем узел с текстовым содержимым созданному элементу <li>, а затем добавляем созданный элемент <li> элементу <ul>.

В следующем примере мы рассмотрим ситуацию, при которой мы с помощью метода .appendChild() будем вставлять уже существующий элемент:

Перемещение существующего элемента в другой список

Нажмите ▶, затем кнопки в результате: красный пункт перемещается между списками, а не копируется, потому что один узел не может иметь двух родителей.

index.html
HTML
<button data-migration-click-0="">Append to first Ul</button>
<button data-migration-click-2="">Append to second Ul</button>
<ul id="first">
  <li class="active" style="color: red">1</li>
  <li>2</li>
  <li>3</li>
</ul>
<ul id="second">
  <li>1</li>
  <li>2</li>
</ul>
main.js
JavaScript
const firstUl = document.getElementById('first'),
    secondUl = document.getElementById('second'),
    activeLi = document.getElementsByClassName('active')[0]

function myFunc() {
    firstUl.appendChild(activeLi)
}

function myFunc2() {
    secondUl.appendChild(activeLi)
}

// Обработчики кнопок перенесены из HTML для запуска с CSP без inline-скриптов.
document.querySelector('[data-migration-click-0]').addEventListener('click', function () {
    myFunc()
})
document.querySelector('[data-migration-click-0]').removeAttribute('data-migration-click-0')
document.querySelector('[data-migration-click-2]').addEventListener('click', function () {
    myFunc2()
})
document.querySelector('[data-migration-click-2]').removeAttribute('data-migration-click-2')

В этом примере с использованием метода addEventListener() при нажатии на определенную кнопку (HTML элемент <button>) вызываем функции myFunc(), или myFunc2(), которые с использованием метода .appendChild() объекта Node сначала удаляют, а затем добавляют элемент <li> в определенный элемент <ul>.

Элемент <li> удаляется, а затем вставляется по той причине, что метод .appendChild() ссылается на один и тот же элемент <li>, а он не может по объективным причинам находиться в нескольких родителях одновременно.

Что возвращает appendChild() для фрагмента

Нажмите ▶. Два элемента появятся в списке, а консоль покажет, что возвращён тот же фрагмент, уже без детей. Измените массив названий и повторите запуск.

index.html
HTML
<ul></ul>
main.js
JavaScript
const fragment = document.createDocumentFragment()
for (const label of ['Первый', 'Второй']) {
    const item = document.createElement('li')
    item.textContent = label
    fragment.appendChild(item)
}
const result = document.querySelector('ul').appendChild(fragment)
console.log('Возвращён исходный фрагмент:', result === fragment)
console.log('Детей осталось во фрагменте:', result.childNodes.length)