Núcleo jQuery - método jQuery()

Manual de Referência do Núcleo jQuery

Exemplo

Encontre todos os elementos p que são filhos diretos de elementos div, e defina suas propriedades de borda:

$("div > p").css("border", "1px solid gray");

Experimente você mesmo

Definição e uso

A função jQuery() aceita uma string que contém um seletor CSS para combinar conjuntos de elementos.

A função jQuery() tem três sintaxes:

Sintaxe 1

Aceita uma string que contém um seletor CSS para combinar conjuntos de elementos:

jQuery(selector, [context]

Uso detalhado

Sintaxe 2

Criar elementos DOM usando uma string de HTML original:

jQuery(html,ownerDocument]

Uso detalhado

Sintaxe 3

Ligar uma função a ser executada após o carregamento do documento DOM:

jQuery( callback )

Uso detalhado

jQuery( selector, [ context ] )

Essa sintaxe tem várias formas de uso:

Uso 1: Definir ambiente de seleção

Sintaxe

jQuery(selector, [context]

Por padrão, o seletor pesquisa o DOM a partir da raiz do documento. No entanto, podemos definir um parâmetro opcional de contexto para o $().

Por exemplo, se desejarmos procurar um elemento em um callback, podemos limitar a pesquisa conforme abaixo:

Exemplo

$("div.foo").click(function() {
  $("span", this).addClass("bar");
);

Como já limitamos o seletor span ao ambiente this, apenas o span no elemento clicado receberá a classe adicional.

Internamente, o ambiente de seletor é implementado pela método .find(), então $("span", this) é equivalente a $(this).find("span").

Todas as funcionalidades nucleares do jQuery são implementadas por meio dessa função. Tudo no jQuery é baseado nessa função, ou seja, está de alguma forma usando essa função. O uso mais básico dessa função é passar uma expressão (normalmente composta por seletor CSS) para ela, e então encontrar todos os elementos que correspondem a essa expressão.

Por padrão, se o parâmetro context não for especificado, $() buscará elementos DOM no documento HTML atual; se o parâmetro context for especificado, como um conjunto de elementos DOM ou um objeto jQuery, ele buscará dentro desse contexto. A partir do jQuery 1.3.2, a ordem dos elementos retornados é equivalente à ordem de aparição no contexto.

Uso 2: Usar elemento DOM

Sintaxe

jQuery(elemento)

Esta função nos permite criar um objeto jQuery usando elementos DOM encontrados de outras maneiras. A utilização usual dessa funcionalidade é, chamar métodos jQuery no elemento que já foi passado ao callback função via palavra-chave this:

Exemplo

$("div.foo".click(function() {
  $(this).slideUp();
);

Este exemplo usará animação de deslizamento para ocultar o elemento ao ser clicado. Como o manipulador de eventos aceita o item clicado no contexto do palavra-chave this como um elemento DOM puro, é necessário empacotar o elemento com um objeto jQuery antes de chamá-lo.

Esta função também pode aceitar documentos XML e objetos Window (apesar de não serem elementos DOM) como parâmetros válidos.

Quando dados XML são retornados de uma chamada Ajax, podemos usar a função $() para empacotar esses dados com o objeto jQuery. Uma vez concluído, podemos usar .find() e outros métodos de varredura DOM para recuperar elementos individuais da estrutura XML.

Uso 3: Clonar objeto jQuery

Sintaxe

jQuery(objeto jQuery)

Quando se passa um objeto jQuery no formato de parâmetro para a função $(), é criada uma cópia do objeto. Como o objeto inicial, o novo objeto jQuery referencia o mesmo elemento DOM.

Uso 4: Retornar uma coleção vazia

Sintaxe

jQuery()

Para o jQuery 1.4, a chamada do método jQuery() sem parâmetros retornará uma coleção jQuery vazia. Em versões anteriores do jQuery, isso retornaria uma coleção contendo o nó document.

jQuery( html, [ ownerDocument ] )

Essa sintaxe tem várias formas de uso:

Uso 1: Criar novos elementos

Sintaxe

jQuery(html,ownerDocument]

Você pode passar uma string HTML escrita manualmente, ou uma string criada por algum motor de template ou plugin, ou uma string carregada via AJAX. No entanto, há restrições ao criar elementos input, você pode referenciar o segundo exemplo.

Claro, essa string pode conter barras invertidas (por exemplo, um endereço de imagem) e barras normais. Quando você criar um único elemento, use tags de fechamento ou formato XHTML. Por exemplo, para criar um span, você pode usar $("<span/>") ou $("<span></span>"), mas não é recomendável usar $("<span>"). Em jQuery, essa sintaxe é equivalente a $(document.createElement("span")).

Se você passar uma string como parâmetro para $(), o jQuery verificará se a string é HTML (por exemplo, se existem tags em certas posições). Se não for, o jQuery interpretará a string como uma expressão de seletor, conforme explicado acima. No entanto, se a string for um fragmento HTML, o jQuery tentará criar o elemento DOM descrito pelo fragmento HTML. Em seguida, criará e retornará um objeto jQuery que faz referência aos elementos DOM:

Exemplo

$("<p id="test">Meu <em>novo</em> texto</p>").appendTo("body");

Se o fragmento HTML for mais complexo do que um simples tag sem atributos, como no exemplo acima, o processo real de criação do elemento é realizado pelo mecanismo innerHTML do navegador. Em termos específicos, o jQuery cria um novo elemento <div>, e então define a propriedade innerHTML do elemento para o fragmento HTML fornecido. Quando o parâmetro é um simples tag, como $("<img />") ou $("<a></a>"), o jQuery cria o elemento através da função createElement() interna do JavaScript.

Para garantir a compatibilidade cross-plataforma, a estrutura do fragmento deve ser bem formada. As tags que podem conter outros elementos devem aparecer em pares (com tag de fechamento):

$("<a href="http://jquery.com"></a>");

No entanto, o jQuery também permite uma sintaxe de tags semelhante ao XML:

$("<a/>");

Etiquetas que não podem conter outros elementos podem ser fechadas ou não fechadas:

$("<img />");
$("<input>");

Uso 2: Definir atributos e eventos

Sintaxe

jQuery(html,props)

Para o jQuery 1.4, podemos passar um mapeamento de atributos como segundo parâmetro. Esse parâmetro aceita um superconjunto de atributos que podem ser passados para o método .attr(). Além disso, pode-se passar tipos de evento arbitrários e chamar os seguintes métodos jQuery: val, css, html, text, data, width, height ou offset.

Atenção, o Internet Explorer não permite criar elementos input e alterar seu tipo; você deve usar, por exemplo, "<input type="checkbox" />" para definir o tipo.

Exemplo

Cria um elemento <input>, configurando ao mesmo tempo o atributo type, os valores dos atributos e alguns eventos.

$("<input>", {
  type: "text",
  val: "Test",
  focusin: function() {
    $(this).addClass("active");
  },
  focusout: function() {
    $(this).removeClass("active");
  }
}).appendTo("form");

jQuery( callback )

Permite que você vincule uma função a ser executada após o carregamento do documento DOM.

A função desempenha o mesmo papel que $(document).ready(), mas ao usar essa função, é necessário empacotar todas as outras operações $() que precisam ser executadas após o carregamento do DOM dentro dela. Embora tecnicamente seja possível criar links dessa maneira, não há muitos casos práticos de uso dessa funcionalidade.

Exemplo

Quando o DOM estiver carregado, execute a função dentro dele:

$(function(){
  // Documento pronto
);

Manual de Referência do Núcleo jQuery