JavaScript метод Node.insertBefore()

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

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

Если вставляемый узел является узлом фрагмента DocumentFragment, то в указанную позицию вставляется не сам узел, а все его дочерние узлы, в исходном порядке следования.

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

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

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

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

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

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

JavaScript синтаксис

JavaScript
parentNode.insertBefore(newNode, referenceNode);

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

DOM Standard.

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

Параметры Node.insertBefore()
Параметр Описание
newNode Узел, который требуется вставить. Обязательный аргумент.
referenceNode Дочерний узел, перед которым необходимо вставить новый узел. Если задано значение null, то новый узел будет добавлен в конец списка дочерних узлов родительского узла. Является ошибкой передавать в аргументе ссылочный узел, который не является дочерним по отношению к родительскому узлу. Обязательный аргумент

Исключения

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

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

Вставка перед узлом и в конец списка

Нажмите ▶, затем первую кнопку: новый пункт появится перед исходным. Вторая кнопка передаёт null вторым аргументом, и пункт добавляется в конец списка.

index.html
HTML
<button data-migration-click-0="">referenceNode = li</button>
<button data-migration-click-2="">referenceNode = null</button>
<ul id="first">
  <li class="list-item">Элемент списка</li>
</ul>
main.js
JavaScript
const firstUl = document.getElementById('first'),
    li = document.querySelector('.list-item')

function myFunc() {
    const newElem = document.createElement('li'),
        text = document.createTextNode("I\'m inserted before")
    newElem.appendChild(text)
    firstUl.insertBefore(newElem, li)
}

function myFunc2() {
    const newElem = document.createElement('li'),
        text = document.createTextNode("I\'m inserted at the end of the list of child nodes")
    newElem.appendChild(text)
    firstUl.insertBefore(newElem, null)
}

// Обработчики кнопок перенесены из 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().

В первом случае мы с помощью метода .insertBefore() вставляем созданный узел перед заданным узлом в качестве дочернего узла указанного родительского узла, а во втором вставляем созданный узел в конец списка дочерних узлов родительского узла, передав в качестве значения второго аргумента значение null.

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

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

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

index.html
HTML
<button data-migration-click-0="">Insert before first child first Ul</button>
<button data-migration-click-2="">Insert before first child second Ul</button>
<ul id="first">
  <li>1</li>
  <li>2</li>
  <li class="active" style="color: red">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.insertBefore(activeLi, firstUl.firstChild)
}

function myFunc2() {
    secondUl.insertBefore(activeLi, secondUl.firstChild)
}

// Обработчики кнопок перенесены из 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(), которые с использованием метода .insertBefore() объекта Node сначала удаляют, а затем добавляют элемент <li> перед заданным узлом, который является первым дочерним элементом родительского узла в качестве дочернего узла в определенном элементе <ul>.

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