jQuery.append(): Como inserir elementos na árvore DOM

Com o método jQuery.append(), você sim­pli­fica tarefas complexas, como a criação de listas dinâmicas, a adição de elementos de for­mu­lá­rio e o car­re­ga­mento de conteúdos adi­ci­o­nais por AJAX. Conheça a sintaxe básica e aprenda a usar o jQuery.append().

O que é jQuery.append()?

jQuery.append() é a função da bi­bli­o­teca jQuery capaz de inserir conteúdos di­na­mi­ca­mente na árvore DOM (Document Object Model). Ao aplicar o método, você consegue anexar novos elementos ou es­tru­tu­ras ao fim de um objeto. Versátil, o jQuery.append() pode ser usado em com­bi­na­ção com outras funções, como com jQuery.re­mo­ve­Class() e jQuery.on(). Assim, você tem uma série de opções para expandir, de forma dinâmica, a árvore DOM. Entre as suas vantagens também está a in­te­gra­ção do jQuery com o WordPress, que pos­si­bi­lita a criação de fun­ci­o­na­li­da­des especiais e de elementos in­te­ra­ti­vos no CMS.

Sintaxe e pa­râ­me­tros de jQuery.append()

O método jQuery.append() aceita dois pa­râ­me­tros:

$(selector).append(content, function(index, html));

• content: Es­pe­ci­fica o conteúdo que será adi­ci­o­nado.
• function(index, html): Função executada após a anexação do conteúdo.
  • index: Índice do elemento atual no conjunto de objetos se­le­ci­o­na­dos.
  • html: Conteúdo HTML atual do elemento.

Por sua vez, selector pode ser qualquer seleção CSS válida para iden­ti­fi­car o elemento final desejado. Seletores em jQuery são, por exemplo, IDs (#id), classes (.class) ou nomes de elementos (como div).

O parâmetro content pode ser uma cadeia de ca­rac­te­res (texto), um código HTML ou um elemento DOM já existente. Se você utilizar uma cadeia de ca­rac­te­res, ela será adi­ci­o­nada como conteúdo de texto do elemento. Se você es­pe­ci­fi­car um código HTML, ele será in­ter­pre­tado e inserido como uma nova estrutura de elemento. No caso de um elemento DOM já existente, o método jQuery.append() anexará esse elemento ao objeto final.

Exemplos de uso de jQuery.append()

Acompanhe alguns exemplos de aplicação do método jQuery.append().

jQuery.append() com HTML

O exemplo a seguir mostra como adicionar es­tru­tu­ras HTML com .append() jQuery:

$("header").append("<div><p>Novo conteúdo</p></div>");

Acima, o trecho jQuery.append() div insere um contêiner com um parágrafo no fim do elemento header (cabeçalho).

jQuery.append() com elementos DOM

A adição de elementos DOM segue um esquema se­me­lhante, como exem­pli­fica o código abaixo:

var newElement = $("<div><p>Novo conteúdo</p></div>");
$("header").append(newElement);

jQuery.append() com função callback

Ao aplicar uma função callback após a inserção de um conteúdo, você se torna capaz de executar certas ações ou acessar o elemento recém-criado e as res­pec­ti­vas pro­pri­e­da­des:

$("div#container").append("<p>Primeiro elemento</p><p>Segundo elemento</p><p>Terceiro elemento</p>", function(index, html) {
    console.log("Elemento adicionado: " + html);
    console.log("Índice do elemento: " + index);
});

Assim ficaria o resultado:

Elemento adicionado: <p>Primeiro elemento</p>
Índice do elemento: 0
Elemento adicionado: <p>Segundo elemento</p>
Índice do elemento: 1
Elemento adicionado: <p>Terceiro elemento</p>
Índice do elemento: 2

No exemplo acima, a função jQuery.append() element anexa três tags <p> (Primeiro elemento, Segundo elemento e Terceiro elemento) si­mul­ta­ne­a­mente ao fim do div com o ID container. A função callback é chamada para cada objeto adi­ci­o­nado e exibe, no console, o conteúdo HTML do res­pec­tivo elemento, assim como o índice cor­res­pon­dente.