Artigo original: The Best jQuery Examples

Tradução realizada em português europeu

O jQuery é a biblioteca de JavaScript mais popular, sendo utilizada em mais de metade de todos os maiores sites. O seu lema é "escreve menos, faz mais...!"

O jQuery torna o desenvolvimento para a web mais fácil de utilizar ao fornecer uma série de funções de "ajuda". Essas funções ajudam os programadores a escrever interações rápidas com o DOM (Document Object Model – ou Modelo Documento-Objeto, em português) sem a necessidade de escreverem manualmente tanto JavaScript.

O jQuery adiciona uma variável global com todos os métodos da biblioteca anexados. A convenção para a nomenclatura é ter esta variável global como $. Ao escreveres $., ficas com todos os métodos jQuery ao teu dispor.

Primeiros passos

Existem duas formas principais para começar a utilizar o jQuery:

  • Incluir o jQuery localmente: descarrega a biblioteca jQuery a partir de jquery.com e inclui a biblioteca no teu código HTML.
  • Utilizar uma CDN: faz a ligação para a biblioteca jQuery utilizando uma CDN (Content Delivery Network – ou Rede de Entrega de Conteúdo, em português).
<head>
  <script src="/jquery/jquery-3.4.1.min.js"></script>
  <script src="js/scripts.js"></script>
</head>
<head>
  <script src = "https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
  <script src="js/scripts.js"></script>
</head>

Seletores

O jQuery utiliza seletores de estilo CSS para selecionar partes ou elementos de uma página HTML. Depois, permite-te fazer alguma coisa com os elementos através da utilização de métodos jQuery ou funções.

Para utilizar um destes seletores, escreve um caractere de dólar e parênteses depois dele: $(). Esta é a forma abreviada para a função jQuery(). Dentro dos parênteses, adiciona o elemento que queres selecionar. Podes utilizar tanto aspas simples como aspas duplas. De seguida, adiciona um ponto após os parênteses e o método que desejas utilizar.

Em jQuery, a classe e os seletores de ID são representados da mesma maneira que em CSS.

Aqui está um exemplo de um método jQuery que seleciona todos os elementos de parágrafo, adicionando uma classe "selected" aos elementos:

<p>Este é um parágrafo selecionado por um método do jQuery.</p>
<p>Este parágrafo também é selecionado por um método do jQuery.</p>

$("p").addClass("selected");

Em jQuery, a classe e seletores de ID são escritos da mesma forma que em CSS. Se quiseres selecionar todos os elementos com uma determinada classe, utiliza um ponto (.) e o nome da classe. Se quiseres selecionar elementos com um determinado ID, utiliza o símbolo do cardinal (#) e o nome do ID. Observa que o HTML não é sensível a maiúsculas ou minúsculas. Por isso, é boa prática manter o código HTML e seletores de CSS em minúsculas.

Selecionar por classe

Se quiseres selecionar elementos com uma determinada classe, utiliza um ponto (.) e o nome da classe.

<p class="pWithClass">Parágrafo com uma classe.</p>
$(".pWithClass").css("color", "blue"); // torna o texto azul

Também podes utilizar o seletor de classe em conjunto com a etiqueta de nome de maneira a ser mais específico.

<ul class="wishList">Minha lista de desejos</ul>`<br>
$("ul.wishList").append("<li>Um liquidificador novo</li>");

Selecionar por ID

Se quiseres selecionar elementos com um determinado valor de ID, utiliza o símbolo do cardinal (#) e o nome do ID.

<li id="liWithID">Item de lista com ID.</li>
$("#liWithID").replaceWith("<p>Meias</p>");

Da mesma maneira que com o seletor de classe, isto também pode ser utilizado em conjunto com a etiqueta de nome.

<h1 id="headline">Título da notícia</h1>
$("h1#headline").css("font-size", "2em");

Selecionar por valor de atributo

Se quiseres selecionar elementos com um determinado atributo, utiliza ([nomeDoAtributo="valor"]).

<input name="meuInput" />
$("[name='meuInput']").value("Teste"); // define um valor de input para "Teste"

Também podes utilizar o seletor de atributo em conjunto com a etiqueta de nome para ser mais específico.

<input name="meuElemento" />`<br>
<button name="meuElemento">Botão</button>
$("input[name='myElement']").remove(); // remove o campo de input e não o botão

Seletores que funcionam como filtros

Também existem seletores que funcionam como filtros. Geralmente, vão começar por dois pontos. Por exemplo, o seletor :first seleciona o elemento que é o primeiro filho do seu elemento pai. Aqui está um exemplo de uma lista não ordenada com alguns itens. O seletor do jQuery por baixo da lista seleciona o primeiro elemento <li> na lista – o item "Um" da lista – e depois utiliza o método .css para tornar o texto verde.

   <ul>
      <li>Um</li>
      <li>Dois</li>
      <li>Três</li>
   </ul>
$("li:first").css("color", "green");

Seletor de atributo

Estes são seletores que devolvem elementos que correspondem a certas combinações de atributos, tais como o atributo contém, o atributo termina com, o atributo começa com, e assim por diante. Aqui está um exemplo de uma lista não ordenada com alguns itens de lista. O seletor de jQuery por baixo da lista seleciona o elemento <li> na lista – o primeiro item da lista, visto que tem um atributo data* com "India" como o seu respetivo valor – e depois utiliza o método .css para tornar o texto verde.

   <ul>
      <li data-country="India">Mumbai</li>
      <li data-country="China">Beijing</li>
      <li data-country="United States">New York</li>
   </ul>
$("li[data-country='India']").css("color", "green");

Outro seletor de filtragem, :contains(text), seleciona os elementos que têm um determinado texto. Coloca o texto que queres entre parênteses. Aqui está um exemplo de dois parágrafos. O seletor do jQuery pega na palavra "Mundo" e altera a sua cor para amarelo.

    <p>Olá</p>
    <p>Mundo</p>
$("p:contains('Mundo')").css("color", "yellow");

De modo semelhante, o seletor :last seleciona o elemento que está no último descendente do seu elemento pai. O seletor de jQuery abaixo seleciona o último elemento <li> na lista – o terceiro item da lista – e depois utiliza o método .css para tornar o texto amarelo.

$("li:last").css("color", "yellow");

Observação: No seletor de jQuery, Mundo está entre aspas simples, pois já está dentro de um par de aspas duplas. Utiliza sempre aspas simples dentro das aspas duplas para evitar que uma string termine sem querermos.

Múltiplos seletores

Em jQuery, podes utilizar vários seletores para aplicar as mesmas alterações a mais do que um elemento, utilizando apenas uma linha de código. Podes fazer isto ao separar os diferentes ids com uma vírgula. Por exemplo, se quiseres definir a cor de fundo de três elementos com os ids cat, dog e rat para vermelho, faz simplesmente:

$("#cat,#dog,#rat").css("background-color","red");

Método HTML

O método do jQuery .html() obtém o conteúdo de um elemento HTML ou define o conteúdo de um elemento HTML.

Obter

Para devolver o conteúdo de um elemento HTML, utiliza esta sintaxe:

$('seletor').html();

Por exemplo:

$('#exemplo').html();

Definir

Para definir o conteúdo de um elemento HTML, utiliza esta sintaxe:

$('seletor').html(conteúdo);

Por exemplo:

$('p').html('Olá mundo!');

Isto vai definir o conteúdo de todos os elementos <p> para Olá mundo!

Aviso

O método .html() é utilizado para definir o conteúdo do elemento em formato HTML. Isto pode ser um risco caso o conteúdo seja fornecido pelo utilizador. Em vez disto, considera utilizar o método .text() se precisares de definir strings que não sejam do HTML como conteúdo.

Método CSS

O método de jQuery .css() obtém o valor de uma propriedade de estilo computada para o primeiro elemento num conjunto de elementos correspondentes, ou define uma ou mais propriedades do CSS por cada elemento correspondente.

Obter

Para devolver o valor de uma propriedade CSS especificada, utiliza a seguinte sintaxe:

    $(seletor).css(nomeDaPropriedade);

Exemplo:

    $('#elemento').css('background');

Observação: Aqui, podemos utilizar qualquer seletor CSS. Por exemplo: elemento(seletor da tag HTML), .elemento(seletor de classe) e #elemento(seletor de ID).

Definir

Para definir uma propriedade CSS especificada, utiliza a seguinte sintaxe:

    $(seletor).css(nomeDaPropriedade,valor);

Exemplo:

    $('#elemento').css('background','red');

Para definir várias propriedades do CSS, terás de utilizar a sintaxe de objeto literal, deste modo:

    $('#element').css({
        'background': 'gray',
        'color': 'white'
    });

Se quiseres alterar uma propriedade que tenha como etiqueta mais do que uma palavra, consulta este exemplo:

Para alterar o background-color de um elemento

    $('#elemento').css('background-color', 'gray');

Método click

O método click do jQuery aciona uma função quando um elemento é clicado. A função é conhecida como um "manipulador", pois lida com o evento de clique. As funções podem causar um impacto no elemento HTML que está vinculado ao evento de clique utilizando o método click do jQuery, ou podem alterar algo completamente diferente. O formato mais utilizado é:

$("#cliqueAqui").click(handler)

O método click recebe a função de manipulação como argumento e executa-a sempre que o elemento #cliqueAqui for clicado. A função de manipulação recebe um parâmetro conhecido como eventObject que pode ser útil para controlar a ação.

Exemplos

Este código mostra um alerta assim que um utilizador clicar num botão:

<button id="alert">Clique aqui</button>
$("#alerta").click(function () {
  alert("Oi! Eu sou um alerta");
});

O eventObject tem alguns métodos incorporados, incluindo o preventDefault(), que faz exatamente o que o nome indica - pára o evento predefinido de um elemento. Aqui, evitamos que a tag de link se comporte como um link:

<a id="myLink" href="www.google.com">Link para o Google</a>
$("#meuLink").click(function (event) {
  event.preventDefault();
});

Mais formas de brincar com o método click

A função de manipulação também pode aceitar informação adicional sob a forma de um objeto:

jqueryElement.click(usefulInfo, handler)

A informação pode ser de qualquer tipo.

$("elemento").click({primeiraPalavra: "Olá", segundaPalavra: "Mundo"}, function(event){
    alert(event.data.primeiraPalavra);
    alert(event.data.segundaPalavra);
});

Invocar o método click sem uma função de manipulação gera um evento de click:

$("#alert").click(function () {
  alert("Oi! Eu sou um alerta");
});

$("#alert").click();

Agora, sempre que a página carregar, o evento de click será acionado quando entramos ou recarregamos a página, e exibirá o alerta atribuído.

Além disto, deves utilizar preferencialmente .on("click",...) em vez de .click(...), pois o primeiro pode utilizar menos memória e funcionar com elementos adicionados dinamicamente.

Erros comuns

O evento click está vinculado apenas a elementos atualmente presentes no DOM na altura da vinculação. Por isso, qualquer elemento adicionado posteriormente não ficará vinculado. Para vincular todos os elementos no DOM, mesmo que sejam criados mais tarde, utiliza o método .on().

Por exemplo, este método click:

$("elemento").click(function() {
  alert("Fui clicado!");
});

Pode ser alterado para este exemplo do método on:

$(document).on("click", "elemento", function() {
  alert("Fui clicado!");
});

Obter o elemento a partir de um evento de Click

Isto aplica-se tanto em jQuery como em JavaScript simples, mas se configurares a ativação do teu evento para afetar uma classe, podes pegar no elemento específico que acionou o elemento ao utilizar a palavra-chave this.

O jQuery torna muito fácil (e compatível com vários navegadores) percorrer o DOM para encontrar os pais, irmãos e filhos do elemento.

Digamos que tenho uma tabela cheia de botões e quero afetar a linha em que está o botão. Posso simplesmente envolver this num seletor do jQuery e depois obter o seu parent e o parent desse elemento, desta forma:

$( document ).on("click", ".myCustomBtnClassInATable", function () {
    var myTableCell = $(this).parent();
    var myTableRow = myTableCell.parent();
    var myTableBody = myTableRow.parent();
    var myTable = myTableBody.parent();
    
    //também podes encadear todos estes para obter o que desejas numa só linha
    var myTableBody = $(this).parent().parent().parent();
});

Também é interessante verificar a informação de evento para o evento de click, que podes pegar ao passar qualquer nome de variável para a função no evento de click. Na maioria dos casos, provavelmente, verás um e ou event:

$( document ).on("click", ".myCustomBtnClassInATable", function (e) { 
    //encontra mais informação sobre a variável de evento na consola
    console.log(e);
});

Método mousedown

O evento mousedown ocorre quando o botão esquerdo do rato é pressionado. Para acionar o evento mousedown no elemento selecionado, utiliza esta sintaxe: $(seletor).mousedown();

No entanto, na maior parte das vezes, o método mousedown é utilizado com uma função anexada ao evento mousedown. Aqui está a sintaxe: $(seletor).mousedown(function);

Por exemplo:

$(#exemplo).mousedown(function(){
   alert("Exemplo foi clicado");
});

Este código vai gerar um alerta na página "Exemplo foi clicado" quando #exemplo for clicado.

Método hover

O método hover do jQuery é uma combinação dos eventos mouseenter e mouseleave. Esta é a sintaxe:

$(seletor).hover(inFunction, outFunction);

A primeira função, inFunction, irá executar quando o evento mouseenter ocorrer. A segunda função é opcional, mas irá executar quando o evento mouseleave ocorrer. Se for especificada apenas uma função, a outra função será executada tanto para o evento mouseenter como para o mouseleave. Abaixo está um exemplo mais específico.

$("p").hover(function(){
    $(this).css("background-color", "yellow");
}, function(){
    $(this).css("background-color", "pink");
});

Isto quer dizer que passar o rato por cima de um parágrafo irá alterar a sua cor de fundo para amarelo, enquanto o oposto irá alterar de volta para rosa.

Método animate

O método animate do jQuery torna mais fácil criar animações simples utilizando apenas algumas linhas de código. A estrutura básica é a seguinte:

$(".seletor").animate(propriedades, duração, funcaoDeCallback());

Para o argumento propriedades, precisas de passar um objeto do JavaScript com as propriedades do CSS que desejas animar como chaves e os valores que desejas animar como valores. Para a duração, precisas de inserir a quantidade de tempo em milésimos de segundo que a animação deve durar. A funcaoDeCallback() é executada assim que a animação tiver terminado.

Exemplo

Um simples exemplo teria este aspeto:

$(".awesome-animation").animate({
	opacity: 1,
	bottom: += 15
}, 1000, function() {
	$(".elemento-diferento").hide();
});

Método hide

Na sua forma mais simples, .hide() esconde imediatamente o elemento correspondente, sem animação. Por exemplo:

$(".minhaClasse").hide()

Isso irá ocultar todos os elementos cuja classe seja minhaClasse. Pode ser utilizado qualquer seletor jQuery.

.hide() como método de animação

Graças às suas opções, o .hide() pode animar simultaneamente a largura, altura e transparência dos elementos correspondentes.

  • A duração pode ser fornecida em milésimos de segundo, ou através dos literais slow (600 ms) e fast (200ms), por exemplo:
$("#meuObjeto").hide(800)
  • Uma função pode ser especificada para ser chamada assim que a animação termine, uma vez por cada elemento correspondente. Esta função de callback é, em grande parte, utilizada para juntar várias animações diferentes. Por exemplo:
$("p").hide( "slow", function() {
  $(".titles").hide("fast");
  alert("O texto sumiu!");
});

Método show

Na sua forma mais simples, .show() exibe imediatamente o elemento correspondente, sem animação, por exemplo:

$(".minhaClasse").show();

Isso irá exibir todos elementos cuja classe seja minhaClasse. Pode ser utilizado qualquer seletor do jQuery.

No entanto, este método não se sobrepõe ao !important nos estilos do CSS, tal como o display: none !important.

.show() como método de animação

Graças às suas opções, o .show() pode animar simultaneamente a largura, altura e transparência dos elementos correspondentes.

  • A duração pode ser fornecida em milésimos de segundo, ou através dos literais slow (600 ms) e fast(200ms), por exemplo:
$("#meuObjeto").show("slow");
  • Uma função pode ser especificada para ser chamada assim que a animação termine, uma vez por cada elemento correspondente, por exemplo:
$("#title").show( "slow", function() {
  $("p").show("fast");
});

Método toggle do jQuery

Para mostrar/ocultar elementos podes utilizar o método toggle(). Se o elemento estiver oculto, toggle() vai mostrá-lo e vice-versa. Utilização:

$(".myclass").toggle()

Método slideDown

Este método anima a altura dos elementos correspondentes. Isto faz com que as partes inferiores da página deslizem para baixo, abrindo espaço para os itens revelados. Utilização:

$(".minhaClasse").slideDown(); //expandirá o elemento com o identificador minhaClasse por 400 ms.
$(".minhaClasse").slideDown(1000); //expandirá o elemento com o identificador minhaClasse por 1000 ms.
$(".minhaClasse").slideDown("slow"); //expandirá o elemento com o identificador minhaClasse por 600 ms.
$(".minhaClasse").slideDown("fast"); //expandirá o elemento com o identificador minhaClasse por 200 ms.

Método load

O método load() carrega informação do servidor e coloca a informação devolvida no elemento selecionado.

Observação: Também existe um método de evento do jQuery chamado load. Qual deles é chamado, depende dos parâmetros.

Exemplo

$("button").click(function(){
    $("#div1").load("demo_test.txt");
});

Encadear

O encadeamento do jQuery permite-te executar vários métodos na mesma seleção do jQuery, tudo numa só linha.

O encadeamento permite-nos transformar instruções de várias linhas:

$('#umElemento').removeClass('classeA');
$('#umElemento').addClass('classeB');

Numa única instrução:

$('#umElemento').removeClass('classeA').addClass('classeB');

Método get do Ajax

Envia um pedido http GET assíncrono para carregar dados do servidor. O seu formato geral é:

jQuery.get( url [, dados ] [, sucesso ] [, tipoDeDado ] )
  • url: o único parâmetro obrigatório. Esta string contém o endereço para onde será enviado o pedido. A informação devolvida será ignorada caso não seja especificado mais nenhum parâmetro.
  • dados: um objeto simples ou string enviado para o servidor com o pedido.
  • sucesso: uma função de callback executada no caso de o pedido ser bem sucedido. Ela recebe como argumento a informação devolvida. Também lhe é passado o estado em texto da resposta.
  • tipoDeDado: o tipo da informação esperada pelo servidor. O valor predefinido é Intelligent Guess (xml, json, script, text, html). Se este parâmetro for fornecido, a função de callback de sucesso também deve ser fornecida.

Exemplos

Solicita resource.json ao servidor, enviando informação adicional e ignorando o resultado devolvido:

$.get('http://exemplo.com/recurso.json', {category:'client', type:'premium'});

Solicita resource.json ao servidor, enviando informação adicional e lida com a resposta devolvida (formato json):

$.get('http://exemplo.com/recurso.json', {category:'client', type:'premium'}, function(response) {
     alert("sucesso");
     $("#meuPar").html(response.amount);
});

No entanto, $.get não fornece nenhum modo de lidar com erros.

O exemplo acima (que lida com erros) também pode ser escrito deste modo:

$.get('http://exemplo.com/recurso.json', {category:'client', type:'premium'})
     .done(function(response) {
           alert("sucesso");
           $("#meuPar").html(response.amount);
     })
     .fail(function(error) {
           alert("erro");
           $("#meuPar").html(error.statusText);
     });

Equivalente ao GET do Ajax

$.get( url [, dados ] [, sucesso ] [, tipoDeDado ] ) é uma função abreviada do Ajax, equivalente a:

$.ajax({
     url: url,
     dados: dados,
     sucesso: sucesso,
     tipoDeDado: tipoDeDado
});

Método post do Ajax

Envia um pedido http POST assíncrono para carregar dados do servidor. O seu formato geral é:

jQuery.post( url [, dados ] [, sucesso ] [, tipoDeDado ] )
  • url : este é o único parâmetro obrigatório. Esta string contém o endereço para onde será enviado o pedido. A informação devolvida será ignorada caso não seja especificado mais nenhum parâmetro
  • dados : um objeto simples ou string enviado para o servidor com o pedido.
  • sucesso: uma função de callback executada no caso do pedido ser bem sucedido. Ela recebe como argumento a informação devolvida. Também lhe é passado o estado de texto da resposta.
  • tipoDeDado : o tipo da informação esperada pelo servidor. O valor predefinido é Intelligent Guess (xml, json, script, text, html). Se este parâmetro for fornecido, a função de callback de sucesso também deve ser fornecida.

Exemplos

$.post('http://exemplo.com/form.php', {category:'client', type:'premium'});

Solicita form.php ao servidor, enviando informação adicional e ignorando o resultado devolvido

$.post('http://exemplo.com/form.php', {category:'client', type:'premium'}, function(response){ 
      alert("sucesso");
      $("#meuPar").html(response.amount);
});

Solicita form.php ao servidor, enviando informação adicional e lida com a resposta devolvida (formato json). Este exemplo também pode ser escrito deste modo:

$.post('http://exemplo.com/form.php', {category:'client', type:'premium'}).done(function(response){
      alert("sucesso");
      $("#meuPar").html(response.amount);
});

O seguinte exemplo faz post a um formulário utilizando Ajax e coloca os resultados numa div

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.post demo</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<form action="/" id="searchForm">
  <input type="text" name="s" placeholder="Search...">
  <input type="submit" value="Search">
</form>
<!-- o resultado da pesquisa será renderizado dentro desta div -->
<div id="result"></div>
 
<script>
// Anexa um manipulador de envio ao formulário
$( "#searchForm" ).submit(function( event ) {
 
  // Previne que o formulário submeta normalmente
  event.preventDefault();
 
  // Obtém alguns valores de elementos na página:
  var $form = $( this ),
    term = $form.find( "input[name='s']" ).val(),
    url = $form.attr( "action" );
 
  // Envia a informação utilizando o post
  var posting = $.post( url, { s: term } );
 
  // Coloca os resultados numa div
  posting.done(function( data ) {
    var content = $( data ).find( "#content" );
    $( "#result" ).empty().append( content );
  });
});
</script>
 
</body>
</html>

O seguinte exemplo utiliza a API do GitHub para obter a lista de repositórios de um utilizador através de jQuery.ajax() e coloca os resultados numa div

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery Get demo</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<form id="userForm">
  <input type="text" name="username" placeholder="Enter gitHub User name">
  <input type="submit" value="Search">
</form>
<!-- o resultado da pequisa será renderizado dentro desta div -->
<div id="result"></div>
 
<script>
// Anexa um manipulador de envio ao formulário
$( "#userForm" ).submit(function( event ) {
 
  // Previne que o formulário submeta normalmente
  event.preventDefault();
 
  // Obtém alguns valores de elementos na página:
  var $form = $( this ),
    username = $form.find( "input[name='username']" ).val(),
    url = "https://api.github.com/users/"+username+"/repos";
 
  // Envia a informação utilizando o post
  var posting = $.post( url, { s: term } );
 
  //Função Ajax para enviar um pedido get
  $.ajax({
    type: "GET",
    url: url,
    dataType:"jsonp"
    success: function(response){
        //Se o pedido for feito com sucesso então a resposta representa a informação

        $( "#result" ).empty().append( response );
    }
  });
  
});
</script>
 
</body>
</html>

Função equivalente ao POST do Ajax

$.post( url [, dados ] [, sucesso ] [, tipoDeDado ] ) é uma função Ajax abreviada, equivalente a:

$.ajax({
  type: "POST",
  url: url,
  dados: dados,
  sucesso: sucesso,
  tipoDeDado: tipoDeDado
});