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.

Spinner básico
Figura 1. Spinner básico
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.

Spinner com duas casas decimais
Figura 2. Spinner com duas casas decimais

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.