Como utilizar o componente spinner da jQuery UI
Veja neste artigo como utilizar o componente spinner da biblioteca jQuery UI para facilitar a entrada de valores pelo usuário em páginas web.
Visão geral da jQuery UI
A jQuery UI é uma biblioteca baseada em Javascript (jQuery) e CSS que permite adicionar funcionalidades à interfade de páginas web de forma bastante simples e prática. Para utilizá-la basta referenciar três arquivos a partir do código HTML:
- Arquivo JS referente a biblioteca jQuery;
- Arquivo JS referente à biblioteca jQuery UI;
- Arquivo CSS contendo a folha de estilos da jQuery UI;
Isso pode ser feito adicionando o seguinte trecho de código ao cabeçalho (head) do documento.
<link rel="stylesheet" href="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css" />
<script src="http://code.jquery.com/jquery-1.8.2.js"></script>
<script src="http://code.jquery.com/ui/1.9.0/jquery-ui.js"></script>
Listagem 1. Referenciando a biblioteca
É importante que a referência ao script da jQuery seja feita antes da referência à jQuery UI, pois esta segunda depende da primeira para funcionar.
Feito isso, para cada funcionalidade que se deseja adicionar (calendários, abas, menus, etc) existem funções que devem ser invocadas a partir de um script interno ou externo à página. Nos exemplos desse artigo, serão utilizados apenas scripts internos, adicionados abaixo do código da Listagem 1, no cabeçalho do documento.
Usando o componente Spinner
O componente spinner é um campo para digitação de valores (geralmente números ou datas) que possui dois botões de controle, os quais permitem aumentar ou reduzir o valor do input.
Esse controle é largamente utilizado em situações onde é necessário que o usuário informe com frequência valores numéricos ou datas, evitando a necessidade de digitação constante. Com ele, o usuário pode usar os botões de controle para fazer pequenos incrementos ou decrementos no valor, sem precisar usar o teclado.
Na jQuery UI, o spinner é formado a partir de um input, cujo atributo type não precisa ser definido, pois a biblioteca se encarrega de fazer as configurações necessárias.
Sendo assim, após adicionar os scripts indicados acima no head do documento, podemos adicionar um input no corpo da página para testar a funcionalidade do spinner. Isso pode ser feito, por exemplo, inserindo o código abaixo entre as body.
<h1>Usando o spinner</h1>
<p>
<input id="valor" />
</p>
Listagem 2. Input que dará origem ao spinner
Em seguida, utilizando a sintaxe jQuery, selecionamos o input e chamamos a partir dele a função “spinner”, definida no arquivo “jquery-ui.js”. O código a seguir cria um spinner básico quando adicionado ao documento.
<script>
$(function() {
$("#valor").spinner();
});
</script>
Listagem 3. Criando o spinner básico
Salvando os códigos acima em um arquivo de extensão .html e abrindo no browser, o resultado é o apresentado na figura a seguir.
Observação: Vale notar que o foi estilizado com bordas arredondadas e em tom de cinza, que é o padrão básico da jQuery UI definindo no arquivo css.
Pressionando os botões de controle, o valor do input é alterado em uma unidade para mais ou para menos, mantendo apenas um valor numérico inteiro, que é o formato padrão.
Trabalhando com valores decimais
Considerando que nem sempre os valores utilizados nesse tipo de campo são inteiros, a jQuery UI fornece funcionalidades de formatação do conteúdo do sppiner, permitindo utilizar números decimais e valores monetários.
Para configurar o spinner para exibir valores decimais, basta passar o argumento nomeado “step” ao chamar a função spinner. No exemplo abaixo temos o código completo da página onde estamos definindo que o spinner trabalha com duas casas decimais e inicializamos seu valor como 1.08.
<html>
<head>
<meta charset="utf-8" />
<title>Spinner jQuery UI</title>
<link rel="stylesheet" href="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css" />
<script src="http://code.jquery.com/jquery-1.8.2.js"></script>
<script src="http://code.jquery.com/ui/1.9.0/jquery-ui.js"></script>
<script>
$(function() {
$("#valor").spinner({
step:0.01
});
});
</script>
</head>
<body>
<h1>Usando o spinner</h1>
<p>
<input id="valor" value="1.08"/>
</p>
</body>
</html>
Listagem 4. Definindo quantidade de casas decimais
O resultado é mostrado na imagem a seguir.
Definindo a faixa de valores
É muito comum precisarmos limitar os valores informados pelo usuário em uma faixa predefinida. No caso do spinner, isso pode implementado com a definição dos argumentos min e Max na chamada da função. No exemplo a seguir a faixa de valores aceita vai de 1 a 10.
<html>
<head>
<meta charset="utf-8" />
<title>Spinner jQuery UI</title>
<link rel="stylesheet" href="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css" />
<script src="http://code.jquery.com/jquery-1.8.2.js"></script>
<script src="http://code.jquery.com/ui/1.9.0/jquery-ui.js"></script>
<script>
$(function() {
$("#valor").spinner({
min:1,
max:10
});
});
</script>
</head>
<body>
<h1>Usando o spinner</h1>
<p>
<input id="valor" value="1.08"/>
</p>
</body>
</html>
Listagem 5. Limitando a faixa de valores
Ao atingir os extremos, os botões de controle não executam mais nenhuma ação. Porém, o usuário não é impedido de digitar valores acima o abaixo da faixa diretamente, para evitar esse tipo de situação é preciso aplicar um método de validação.
Controlando eventos do componente
É possível também controlar alguns eventos que ocorrem no componente quando seu valor é alterado, por exemplo, o evento spin que é disparado quando um dos botões é pressionado.
Para realizar esse tratamento basta definir um método dentro da chamada da função spinner, como se vê na Listagem 6, onde exibimos o valor do spinner em um span.
<html>
<head>
<meta charset="utf-8" />
<title>Spinner jQuery UI</title>
<link rel="stylesheet" href="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css" />
<script src="http://code.jquery.com/jquery-1.8.2.js"></script>
<script src="http://code.jquery.com/ui/1.9.0/jquery-ui.js"></script>
<script>
$(function() {
$("#valor").spinner({
spin: function( event, ui ) {
$("#selecionado").text(ui.value.toString());
}
});
});
</script>
</head>
<body>
<h1>Usando o spinner</h1>
<p>
<input id="valor" value="1.08"/>
</p>
<h2>Valor selecionado: <span id="selecionado"></span></h2>
</body>
</html>
Listagem 6. Controlando o evento spin
Conclusão
O componente spinner possui ainda um conjunto de outras propriedades, métodos e eventos cuja documentação pode ser encontrada no endereço http://api.jqueryui.com/spinner/. Nesse link também são encontrados diversos exemplos de utilização para facilitar o aprendizado.
Artigos relacionados
-
Artigo
-
Artigo
-
Artigo
-
Artigo
-
Artigo