Node.insertBefore

O método Node.insertBefore() insere um nó antes do nó de referência como um filho de um nó pai especificado. Se o filho especificado for uma referência a um nó existente no documento, insertBefore() o moverá de sua posição atual para a nova posição (não há necessidade de remover o nó de seu nó pai antes de anexá-lo a outro nó).

Isso significa que um nó não pode estar em dois pontos do documento simultaneamente. Portanto, se o nó já tiver um pai, o nó será removido pela primeira vez e inserido na nova posição. O Node.cloneNode() pode ser usado para fazer uma cópia do nó antes de anexá-lo ao novo pai. Note que as cópias feitas com cloneNode() não serão automaticamente mantidas em sincronia.

 

Se o nó de referência for null, o nó especificado será incluído no final da lista de filhos do nó pai especificado.

Se o filho especificado for um DocumentFragment, todo o conteúdo do DocumentFragment será movido para a lista de filhos do nó pai especificado.

 

Sintaxe

var elementoInserido = elementoPai.insertBefore(novoElemento, elementoDeReferencia);

 

  • elementoInserido O nó sendo inserido, que é novoElemento
  • elementoPai Pai do nó recentemente inserido.
  • novoElemento O nó a ser inserido.
  • elementoDeReferencia O nó antes do qual o novoElemento será inserido.

 

Se elementoDeReferencia for null, novoElemento será inserido no fim da lista de nós filhos.

elementoDeReferencia não é um parâmetro opcional - você deve passar explicitamente um Node ou null. Deixar de fornecer ou passar valores inválidos pode ter comportamento diferente em diferentes versões de navegadores.

 

Return value

O valor retornado é o filho incluído, exceto quando newNode é um DocumentFragment, caso em que o DocumentFragment vazio é retornado.

 

Exemplo

<div id="elementoPai">
  <span id="elementoFilho">foo bar</span>
</div>

<script>
// Cria um novo elemento <span> vazio
var sp1 = document.createElement("span");

// Guarda a referência do elemento atraś do qual nos queremos inserir o novo elemento
var sp2 = document.getElementById("elementoFilho");
// Guarda a referência do elemento pai
var divPai = sp2.parentNode;

// Insere o novo elemento no DOM antes de sp2
divPai.insertBefore(sp1, sp2);
</script>

Não existe um método insertAfter. Mas ele pode ser emulado combinando o método insertBefore com nextSibling.

No exemplo anterior, sp1 poderia ser inserido após sp2 desta forma:

divPai.insertBefore(sp1, sp2.nextSibling);

Se sp2 não possuir um próximo nó, significa que ele deve ser o último filho — sp2.nextSibling retorna null, e sp1 é inserido ao fim da  da lista de nós filhos (logo após sp2).

Exemplo 2

Inserir um elemento antes do primeiro nó filho, usando a propriedade firstChild.

// Guarda a referêncis do elemento no quela nóe queremos inserir o novo nó
var elementoPai = document.getElementById('elementoPai');
// Guarda a referência do primeiro filho
var primeiroFilho = elementoPai.firstChild;

// Cria um novo elemento
var novoElemento = document.createElement("div");

// Insere o novo elemento antes do primeiro filho
elementoPai.insertBefore(novoElemento, primeiroFilho);

Quando o elemento não possui o primeiro filho, então firstChild é null. O elemento ainda será inserido no pai, mas após o último filho. Pois se o elemento pai não possui primeiro filho, ele também não possui o último filho. Conseqüentemente, o novo elemento será o único elemento após a inserção.

Compatibilidade de navegadores

Estamos convertendo nossos dados de compatibilidade para o formato JSON. Esta tabela de compatibilidade ainda usa o formato antigo, pois ainda não convertemos os dados que ela contém. Descubra como você pode ajudar! (en-US)

Funcionalidade Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Suporte básico 1.0 (Yes) (Yes) (Yes) (Yes)
Funcionalidade Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Suporte básico ? ? ? ? ?

Especificação