Calendário JQuery (datePicker). API JQuery UI - Calendário de widgets Datepicker jquery ui datepicker
Olá a todos, queridos leitores do Habr!
Este artigo é sobre jQuery UI e seu widget seletor de data.
Muitas vezes acontece que em uma página você precisa selecionar um período de data (e às vezes até várias datas separadas). Mas o Datepicker da jQuery UI permite selecionar apenas uma data em um único calendário.
Portanto, uma solução comum na prática é criar dois campos de entrada com controle do tipo “de e para”. Você também pode encontrar muitas maneiras de “muletas” para resolver esse problema - isso não nos convém.
Portanto, nosso objetivo é resolver o problema com o mínimo esforço usando apenas o jQuery UI Datepicker.
Para resolver esse problema, existe uma pequena extensão para jQuery UI Datepicker, que aumenta seus recursos padrão sem conectar widgets, plug-ins e estilos de terceiros.
Para aqueles que não estão interessados em usar o widget padrão $.datepicker(), preparei alguns links, espero que também sejam úteis:
Artigo sobre Habré (selecionar várias datas, escolher um período).
- Excelente plugin DateTimePicker da XDSoft (seleção de período de data, seleção de tempo e outros recursos diversos), vale a pena dar uma olhada
Existem outras soluções, mas não vou insistir nelas. Se você tiver seus próprios calendários de seleção de datas favoritos, ficarei feliz em ler sobre eles nos comentários do artigo.
Descrição da extensão Uma extensão é um arquivo que estende os recursos do widget $.datepicker() usando seu modelo de objeto. Não afeta a funcionalidade do Datepicker no modo padrão. Portanto, você não precisa se preocupar com o fato de seu código (já escrito) parar ou funcionar de maneira diferente.A extensão permite alterar o comportamento de seleção de data em dois modos:
- Selecione um período (duas datas: início e fim do período)
- Selecione várias datas (matriz de datas)
$("#date_range").datepicker(( range: "period", // valores possíveis: period, multiple range_multiple_max: 3, // número máximo de datas selecionadas no modo "Multiple Dates" onSelect: function(dateText, inst , extensionRange ) ( // argumento de retorno adicionado extensionRange, contém um objeto de extensão ) )); // O método "setDate" agora pode aceitar um array: 2 elementos com range="period" ou mais elementos com range="multiple" // $("#date_range").datepicker("setDate", ["+2d ", "+1w"]); // é recomendado utilizar o evento "onSelect" para alterar os valores dos campos do formulário (ou variáveis do seu script) // porém, para um controle mais flexível, você pode obter um objeto de extensão e trabalhar com informações sobre o selecionado datas var extensionRange = $("#date_range").datepicker ("widget").data("datepickerExtensionRange"); console.log(extensionRange.datesText); // array de datas (data no formato usado no datepicker) console.log(extensionRange.startDateText); // início do período (data no formato utilizado no datepicker) console.log(extensionRange.endDateText); // fim do período (data no formato usado no selecionador de data) console.log(extensionRange.dates); // array de datas (objeto data) console.log(extensionRange.startDate); // início do período (objeto data) console.log(extensionRange.endDate); //fim do período (objeto data)
Novos estilos para células de calendário
Selected() /* data selecionada */ .selected-start() /* primeira data do período */ .selected-end() /* última data do período */ .first-of-month() /* primeiro data do mês */ .last-of-month() /* última data do mês */
Em uma das lições aprendemos como conectar a biblioteca jQuery UI de diferentes maneiras. Hoje o tema da lição será o widget selecionador de data - jQuery UI Datapicker.
Por que este widget é necessário? Para disponibilizar ao usuário um calendário ao inserir uma data, ao preencher o formulário, ele não precisa pensar em qual formato inserir as datas. Por sua vez, o administrador do recurso recebe os dados no mesmo formato.
Neste endereço: https://jqueryui.com/datepicker/ Você verá várias opções para o widget datapicker, veremos apenas as duas principais.
jQuery UI Datepicker - Exibir menus de mês e anoQuando o usuário clica no campo de texto de entrada, aparece um calendário com seleção de data e um menu adicional com seleção de mês e ano. A opção com uma data é adequada em sites onde o cliente indica, por exemplo, a data da sua visita.
O código HTML consiste em uma única tag de entrada com o identificador "datapicker" envolto em um parágrafo - a tag p. Em vez de um parágrafo, esta entrada pode ser colocada em qualquer elemento de bloco do site.
Data:
O código jQuery deve ser copiado (ver código-fonte) e colado em seu site, como no exemplo. Após carregar a árvore DOM, receberemos o elemento pelo ID #datapicker no campo de texto e chamaremos o método .datepicker. Agora você precisa passar um objeto para o método no qual descreve configurações adicionais: changeMonth: true, changeYear: true . Agora é possível selecionar o mês e o ano através de uma lista suspensa, o que é um pouco mais conveniente do que fazer uma escolha semelhante através do calendário;
$(função()(
$("#datepicker").datepicker((
changeMonth: verdadeiro,
mudançaAno: verdadeiro
});
});
O widget Datapicker com seleção de intervalo de datas é adequado para sites com sistema de reservas. O usuário especifica a data de início no primeiro calendário e a data de término no segundo calendário. Vamos criar dois campos de texto de entrada com identificadores “de” e “para” e dois rótulos vinculados aos seus campos de texto.
De
para
Obtemos um elemento com o identificador #from - o primeiro campo de texto e chamamos o método datapicker nele.
$(função()(
var dateFormat = "mm/dd/aa",
de = $("#de")
.datepicker((
Vamos definir a data padrão mais uma semana.
Data padrão: "+1w",
Capacidade de alterar o mês usando uma lista suspensa.
ChangeMonth: verdadeiro,
número de meses: 3))
Quando ocorre o evento on, ou seja, o usuário seleciona algo na lista suspensa, então quando a data selecionada muda, encontramos o segundo selecionador de data e definimos a data mínima igual à selecionada.
On("alterar", função() (
to.datepicker("opção", "minDate", getDate(this));
}),
to = $("#to").datepicker
Ao alterar a data selecionada, encontramos o primeiro selecionador de data e definimos a data máxima igual à selecionada.
On("alterar", função() (
from.datepicker("opção", "maxDate", getDate(this));
});
Todo o código e exemplos visuais de todas as opções com diferentes parâmetros do widget jQuery Datapicker estão no site jqueryui. com.
jQuery UI Datepicker - Localizar calendárioPor padrão, o calendário é exibido em inglês, mas isso pode ser alterado; a biblioteca jQuery UI oferece suporte a vários idiomas.
Baixe o arquivo de idioma necessário no Github
Incluímos o módulo de idioma necessário na tag head.
Criamos um campo de texto para o calendário e uma lista suspensa com o id “locale” listando os idiomas necessários.
Data:
Inglês
Russo (russo)
Após carregar a árvore DOM, procure o objeto datapicker. Alteramos as configurações de todos os selecionadores de data.
$(função()(
$("#datepicker").datepicker($.datepicker.regional[ "ru" ]);
Mudança de localização para "datepicker" .
$("#locale").on("alterar", function() (
Altere a localização ao selecionar um novo valor na lista suspensa.
$("#datepicker").datepicker("opção",
$.datepicker.regional[ $(this).val() ]);
Widget selecionador de data
Este artigo é sobre o widget Datepicker - um calendário interativo conveniente que facilita a inserção de datas. Receber informações de calendário como texto dos usuários é sempre um desafio porque existem muitos formatos diferentes para expressar datas. O widget Datepicker facilita a seleção de uma data e a apresentação dela de maneira consistente, reduzindo assim a probabilidade de erros.
Criando um widget selecionador de dataExistem duas maneiras principais de criar um widget Datepicker. A maneira mais comum de anexá-lo a um elemento de entrada é usar o método datepicker(). Isso não altera imediatamente a aparência do elemento, mas assim que o elemento recebe o foco de entrada (clicando nele ou navegando até ele a partir de outros elementos usando a tecla), um calendário será exibido próximo a ele, com o qual você pode selecione a data desejada.
Calendários do tipo descrito são chamados calendários pop-up. Um exemplo de criação de tal calendário é fornecido abaixo:
entrada jQuery UI (largura: 200px; alinhamento de texto: esquerda) $(function() ( $("#datep").datepicker(); )); Data de:
A imagem mostra o que acontece quando você move o foco para um campo de entrada:
O usuário pode inserir a data manualmente ou selecioná-la usando o calendário. Assim que o elemento de entrada perder o foco ou o usuário pressionar a tecla (ou), o calendário desaparecerá.
Localização do widget DatepickerComo você pode ver, no exemplo mostrado, o calendário é exibido em inglês. O widget jQuery UI Datepicker fornece suporte bastante abrangente para vários padrões de formatação de data usados em todo o mundo, incluindo 61 opções de localização. Para acessá-los, você precisa importar um script auxiliar JavaScript para o seu documento e informar ao widget Datepicker qual opção de localização usar. Um exemplo correspondente é dado abaixo:
... ... $(function() ( $("#datep").datepicker($.datepicker.regional["ru"]); )); ...
O arquivo jquery-ui-i18n.js está localizado na pasta development-bundle/ui/i18n do arquivo da biblioteca jQuery UI, que você deve ter baixado de jqueryui.com. Copie-o para a mesma pasta onde o arquivo de origem está localizado e adicione-o ao documento conforme mostrado no código. O resultado é mostrado na figura:
A segunda maneira de usar o widget Datepicker envolve incorporá-lo em um documento. Para fazer isso, selecione um elemento div ou span usando jQuery e chame o método datepicker(). O calendário integrado é exibido enquanto o elemento HTML no qual ele se baseia estiver visível. Um exemplo de criação de um calendário integrado é fornecido abaixo:
rótulo da UI do jQuery (margem direita: 12px;) entrada (largura: 200px; alinhamento de texto: esquerda; margem direita: 10px) #wrapper > * (float: esquerda) $(function() ( $("#inline" ).datepicker($.datepicker.regional["ru"] )); Data de:
Este exemplo usa um elemento span como elemento HTML base para criar um widget Datepicker. O resultado é mostrado na figura:
O calendário integrado pode ser útil se você não quiser trabalhar com objetos pop-up. Claro que existem aplicações em que o trabalho com datas é tão intenso que faz sentido ter sempre um calendário à mão. Mas na maioria dos casos, faz sentido deixar o calendário oculto até precisar dele.
A dificuldade de ocultar e mostrar o widget Datepicker incorporado é que adicioná-lo a um documento requer a alteração do layout da página, o que pode causar problemas de apresentação. Do meu ponto de vista, na maioria das situações é muito mais conveniente usar um widget pop-up.
Configurando o widget DatepickerSe você já lidou com processamento de dados antes, sabe bem como é difícil trabalhar com essa categoria de dados. Um reflexo dessa complexidade é a variedade de propriedades suportadas pelo widget Datepicker. As seções a seguir são dedicadas a uma descrição dos grupos de propriedades relacionadas com as quais este widget está configurado.
Configurações básicasVárias opções de configuração são usadas para configurar as propriedades básicas de calendários pop-up e incorporados. Essas propriedades são muito importantes porque permitem controlar como o widget é integrado ao documento. A lista deles é apresentada na tabela abaixo:
| altField | Permite que você especifique um campo adicional que será atualizado quando você selecionar uma data no calendário |
| botãoImageOnly | Especifica que a imagem especificada pela opção buttonImage deve ser usada em vez de um botão secundário para abrir o calendário. |
| botãoImagem | Define a URL da imagem usada para o botão secundário de abertura do calendário pop-up. Não usado por padrão |
| botão de texto | Define o texto que será exibido no botão abrir do calendário pop-up. O texto padrão são reticências (...) |
| data padrão | Permite definir a data que será destacada ao abrir o calendário |
| desabilitado | Indica se o widget deve ser desabilitado inicialmente. O valor padrão é falso |
| mostrar em | Define a ação que aciona a abertura do calendário pop-up. O valor padrão é foco |
A configuração mais simples também é a mais útil. Usando a opção defaultDate, você pode especificar uma data que será destacada automaticamente quando você abrir o calendário.
Se a opção defaultDate não estiver definida, a data atual será usada. (Claro, isso se refere à data definida no sistema do usuário. Fusos horários, horário de verão ou configurações incorretas podem fazer com que a data exibida ao usuário não seja a esperada.)
Esta opção só é usada se não houver nenhum atributo de valor no elemento de entrada. Se este atributo estiver presente (seja ele incluído no documento por você ou resultado de uma pré-seleção do usuário), então o widget Datepicker usará seu valor.
Se quiser que o calendário abra com uma data de início diferente, você pode defini-lo usando um dos métodos descritos na tabela abaixo:
| nulo | A data atual é usada |
| Objeto de data | Usa o valor representado como um objeto JavaScript Date |
| +dias, -dias | Usa uma data que difere da data atual pelo número especificado de dias. Portanto, +3 significa uma data que ocorrerá três dias após a atual e -2 significa uma data que ocorrerá há dois dias. |
| +1d +7w -1m +1a | É usada uma data medida a partir da data atual e expressa em termos do número de dias (d), semanas (w), meses (m) e anos (y) que determinam quanto a data é adiantada (+) ou para trás (-) no tempo. É permitido misturar valores positivos e negativos em uma data. Por exemplo, a combinação de valores -1d +1m, utilizada em conjunto com a data 12 de novembro de 2011, corresponde a 11 de dezembro de 2011 |
Um exemplo de uso da opção defauitDate para especificar uma data daqui a cinco anos é fornecido abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( defaultDate: "+5y" )); ));
Vamos supor que a data atual seja dezembro de 2013. Então, conforme mostra a figura abaixo, a data determinada pelo valor da opção defauitDate corresponde a dezembro de 2018:
Você encontrará o formato descrito para indicar datas relativas mais de uma vez. Este é um formato muito flexível que fornece a precisão necessária. Da mesma forma que no exemplo, você pode omitir qualquer intervalo que não pretenda alterar. Por exemplo, em vez do valor “+0d +0w +0m +5y” é bem possível usar o valor “+5y”. O bom desse formato é que ele permite misturar valores positivos e negativos para intervalos diferentes, o que permite determinar com precisão a data desejada.
Definir um evento que aciona a abertura de um calendário pop-upA opção showOn permite controlar o evento em resposta ao qual o calendário pop-up deve ser exibido. Esta opção pode assumir um de três valores:
focoO calendário pop-up é aberto quando o elemento de entrada recebe o foco. Este é o valor padrão.
botãoO calendário pop-up é aberto clicando no botão.
ambosO calendário pop-up aparece quando o botão é clicado e quando o elemento de entrada recebe o foco.
Se você usar o botão ou ambos os valores, o widget Datepicker criará um elemento de botão e o colocará no documento imediatamente após o elemento de entrada. Um exemplo de uso da opção showOn é fornecido abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( showOn: "ambos" )); ));
Conforme mostrado na figura, um botão apareceu no documento. Como a opção showOn está definida para ambos neste exemplo, o calendário pop-up será mostrado quando o botão for clicado e quando o elemento de entrada receber o foco.
O botão adicionado pelo widget Datepicker não é um widget de botão jQuery UI. Se você deseja que todos os botões sejam do mesmo tipo, selecione um elemento de botão e chame o método button() do jQuery UI.
O elemento button pode ser estilizado usando as opções buttonImage e buttonText. Se você definir a opção buttonImage como o URL de uma imagem, o widget Datepicker colocará essa imagem no botão. Além disso, o texto padrão associado a um botão (reticências) pode ser substituído por outro texto usando a opção buttonText, conforme mostrado no exemplo abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( showOn: "ambos", buttonText: "Selecionar" )); ) );
Usando as opções buttonImage e buttonImageOnly juntas, você pode se livrar completamente do botão, substituindo-o por uma imagem. Um exemplo correspondente é dado abaixo:
rótulo da UI do jQuery (margem direita: 12px) entrada (largura: 200px; alinhamento de texto: esquerda) #dpcontainer * (alinhamento vertical: meio) #dpcontainer img (largura: 35px;) $(function() ( $.datepicker .setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( showOn: "ambos", buttonImage: "right.png", buttonImageOnly: true )); Data de:
Este exemplo define a imagem como right.png e define a opção buttonImageOnly como true. Além disso, vários estilos CSS foram adicionados ao documento para controlar o posicionamento da imagem em relação ao rótulo e aos elementos de entrada. O widget Datepicker não consegue descobrir exatamente onde colocar o elemento img, então os estilos CSS tiveram que ser aplicados para posicionar o elemento img corretamente no documento. O resultado de usar uma imagem em vez de um botão é mostrado na figura:
O objetivo de um widget Datepicker é permitir ao usuário selecionar uma data, mas em muitos casos é necessário colocar algumas restrições neste processo. A tabela abaixo descreve configurações que permitem definir restrições que forçam o usuário a selecionar apenas datas válidas:
| alterar mês | Se esta opção for verdadeira, o calendário exibe uma lista suspensa que permite navegar diretamente por mês. O valor padrão é falso |
| mudança de ano | Se esta opção for verdadeira, o calendário exibe uma lista suspensa que permite navegar diretamente por ano. O valor padrão é falso |
| restringirInput | Se esta opção for verdadeira, o widget Datepicker verifica se o conteúdo do campo de entrada corresponde ao formato de data especificado. O valor padrão é verdadeiro |
| ocultarSeNãoAnteriorPróximo | Se esta opção for verdadeira, os ícones que permitem avançar e retroceder no calendário em relação à data exibida serão completamente ocultos, em vez de simplesmente desativados. O valor padrão é falso |
| datamáx. | Define a data máxima disponível para seleção. Por padrão não há restrição |
| minData | Define a data mínima disponível para seleção. Por padrão não há restrição |
| número de meses | Determina o número de meses exibidos simultaneamente no calendário. O valor padrão é 1 |
| mostrarCurrentAtPos | Se o calendário estiver configurado para exibir vários meses de uma vez, esta opção especifica o número da posição na qual o mês atual ou padrão deve ser exibido. O valor padrão é 0 |
| stepMonths | Determina quantos meses para frente ou para trás a data do calendário deve ser movida quando você clica no botão de avançar ou retroceder |
| intervalo de ano | Define o intervalo de anos disponíveis para seleção na lista suspensa adicionada usando a opção changeYear. Por padrão, esta lista inclui os dez anos anteriores, os próximos dez anos e o ano atual. |
Ao definir a opção constrainInput como true, você pode limitar a entrada de caracteres em um campo de texto apenas aos caracteres que estão em conformidade com um formato estritamente definido. O conjunto de caracteres permitido é determinado pelas configurações de localização discutidas acima. Se o widget Datepicker não tiver sido localizado, você pode esperar que os caracteres permitidos incluam apenas números e o caractere de barra (/).
Usar o valor especificado para a opção constrainInput não significa que o usuário não poderá inserir uma data inválida, como 99/99/99, mas reduz significativamente a probabilidade de erros. Esta configuração é ainda mais importante se a opção showOn estiver definida como botão, pois então o calendário pop-up não abrirá automaticamente quando o campo de entrada receber o foco.
Os usuários geralmente estão dispostos a usar um calendário para selecionar uma data, mas devem vê-lo para fazer isso. Se o calendário não for exibido na tela, nem todo usuário perceberá que para abrir o calendário basta clicar em um botão. Qualquer opção dada ao usuário para inserir diretamente uma data em um campo de texto aumenta a probabilidade de que o formato da data inserida esteja incorreto. Um exemplo de uso da opção constrainInput é fornecido abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( constrainInput: true, minDate: "-3", maxDate: "+ 1" )); ));
Aqui, o valor true é atribuído à opção constrainInput apenas para maior clareza, pois é o valor padrão para esta opção. As duas opções restantes permitem limitar o intervalo de datas disponíveis para seleção a uma data mínima e máxima.
Tal como acontece com a opção defaultDate discutida anteriormente, os valores para as opções minDate e maxDate podem ser nulos (uma data indefinida), um objeto JavaScript Date, um número de dias e uma string de data relativa. Neste exemplo, a representação numérica é selecionada para indicar o número de dias relativos à data atual.
Na figura você pode ver que o Datepicker desativa as células do calendário que não são selecionáveis:
Observe que os botões do mês são desativados automaticamente se não forem necessários. Esses botões estão localizados na parte superior esquerda e direita do calendário e permitem que você passe rapidamente para o mês seguinte ou anterior. Conforme mostrado na figura, todas as datas selecionáveis estão no mês atual e, portanto, ambos os botões estão desabilitados. Nessas situações, esses botões podem ser completamente ocultados, se necessário, definindo a opção hideIfNoPrevNext como true.
O valor minDate não precisa estar no passado e o valor maxDate no futuro, nem precisa ser os dois valores ao mesmo tempo. Para permitir que o usuário selecione datas de um intervalo que é precedido de algum período "preparatório", você pode definir a opção minDate para um valor no futuro, evitando assim que o usuário selecione datas dentro desse período, conforme mostrado no exemplo abaixo :
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker((minDate: "+4" )); ))
Neste exemplo, especificamos que o usuário não deve poder selecionar datas anteriores a 4 dias após a data atual. A opção maxDate é indefinida, o que significa que o usuário poderá selecionar qualquer data após o "período de atraso" especificado. O resultado é mostrado na figura:
Observe que o botão do próximo mês está habilitado nesta situação, enquanto o botão do mês anterior está desabilitado (devido à falta de datas anteriores disponíveis para o usuário selecionar).
As opções minDate e maxDate funcionam em conjunto com a opção defaultDate, o que significa que a vinculação de intervalos à data atual é opcional.
Crie um calendário que exiba vários meses de uma vezO widget Datepicker permite definir a quantidade de meses que devem ser exibidos simultaneamente no calendário usando a opção numberOfMonths. Isto pode ser feito especificando o número necessário de meses ou uma matriz de dois elementos que definem as dimensões da grade do calendário mensal.
O exemplo abaixo implementa uma abordagem baseada em array, que considero mais adequada para widgets Datepicker integrados, já que o tamanho da grade geralmente é muito grande para widgets pop-up (voltaremos a isso mais tarde).
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( numberOfMonths: )); ));
Este exemplo especifica uma grade de calendário com altura de um mês e largura de três meses. O resultado é mostrado na figura:
Uma matriz de dois elementos é equivalente ao valor numérico 3. Se o valor da opção numberOfMonths for especificado como um número, o widget exibirá o número correspondente de meses em uma linha.
A razão pela qual raramente uso essa abordagem ao trabalhar com calendários pop-up é que, com grades grandes, você precisa fazer certas suposições sobre a janela do navegador e os tamanhos de exibição. A janela pop-up do widget Datepicker não é uma caixa de diálogo do sistema operacional. É um elemento HTML com estilo inteligente que aparece como parte de um documento HTML. Isso significa que quando grandes grades de calendário são exibidas em uma tela pequena ou em uma pequena janela do navegador, grande parte do restante das informações contidas no documento aparecerá fora da tela.
Fornecendo acesso direto a meses e anosEm vez de simplesmente exibir meses e anos no cabeçalho do calendário, você pode fornecer acesso direto aos períodos relevantes usando listas suspensas. Esse recurso fornece velocidade quando os usuários precisam selecionar datas entre uma ampla variedade de datas possíveis e é implementado usando as opções changeMonth e changeYear.
Definir qualquer uma dessas opções como verdadeira ativará a lista suspensa correspondente e você poderá controlar de forma independente se as listas estão ativadas. Um exemplo de uso dessas opções é fornecido abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( changeMonth: true, changeYear: true, yearRange: "-1:+ 2" )); ));
Neste cenário, ambas as listas suspensas estão habilitadas. Além disso, a opção yearRange é usada para limitar o intervalo de anos entre os quais o usuário pode fazer a transição. O intervalo necessário é especificado usando o valor "-1:+2", o que significa que o calendário permite ao usuário retroceder um ano e avançar dois anos a partir do ano atual.
As listas suspensas e o intervalo de anos especificado são mostrados na figura:
Ao definir intervalos de anos, você pode usar a opção yearRange para especificar os anos reais. Portanto, neste exemplo, você poderia especificar o valor: "2012:2015".
Controlando a aparência do widget DatepickerExistem diversas propriedades que permitem personalizar a aparência do widget Datepicker quando ele é exibido ao usuário. Para tarefas comuns de seleção de datas, você pode se contentar com a aparência padrão do calendário com a qual já está familiarizado nos exemplos anteriores, mas a capacidade de personalizar a aparência para atender às necessidades de seu aplicativo Web específico é extremamente útil.
As propriedades que permitem alterar a aparência do widget Datepicker são mostradas na tabela abaixo:
| anexarTexto | Especifica o texto da dica de ferramenta contendo informações adicionais, como uma explicação sobre a formatação da data, que será inserida no documento após o elemento de entrada |
| fecharTexto | Define o texto do botão fechar calendário que aparece na barra de botões auxiliares quando está ativado. O valor padrão é "Fechar" |
| texto atual | Define o texto do botão voltar ao mês atual que aparece na barra de botões auxiliares quando ativado. O valor padrão é "Hoje" |
| duração | Define a velocidade ou duração da animação especificada pela opção showAnim. O valor padrão é normal |
| gotoAtual | Se esta opção for verdadeira, o botão Hoje encontrado na barra de botões auxiliares, se habilitado, retornará para a data selecionada em vez da data atual. O valor padrão é falso |
| selecioneOutros Meses | Se esta opção for verdadeira, as datas exibidas como resultado da configuração da opção showOtherMonths como verdadeira ficarão disponíveis para seleção. |
| mostrarAnim | Determina o tipo de animação usada para mostrar e ocultar calendários pop-up. O valor padrão é falso |
| showButtonPanel | Se esta opção for verdadeira, o calendário exibirá um painel auxiliar com botões que permitem ao usuário navegar até a data atual e (se um widget pop-up for usado) fechar o calendário. O valor padrão é falso |
| mostrarOpções | Define as opções de animação especificadas pela opção showAnim |
| mostrarOutros Meses | Se esta opção for verdadeira, os campos vazios na grade do calendário serão preenchidos com datas dos meses anteriores e subsequentes. O valor padrão é falso |
| showWeek | Se esta opção for verdadeira, o calendário exibirá uma coluna com os números das semanas. O valor padrão é falso |
| cabeçalho da semana | Especifica o título da coluna do calendário com números de semana habilitados pela opção showWeek. O valor padrão é "Qua" |
Em algumas aplicações, é importante saber o número da semana do ano em que cai uma determinada data. Por exemplo, isso é exigido em muitos programas de contabilidade. No widget Datepicker, você controla a exibição das informações da semana usando as opções showWeek e weekHeader, conforme mostrado no exemplo abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( showWeek: true, weekHeader: "Semana No." )); ) ) ;
Se a opção showWeek for verdadeira, uma coluna com os números das semanas será exibida no calendário. O cabeçalho padrão para esta coluna é "Semana", mas pode ser alterado usando a opção weekHeader. O exemplo mostra a coluna semanas, que foi renomeada para "Semana #":
Por padrão, o calendário exibe apenas as datas do mês atual. Isso significa que pode haver células vazias na grade do calendário. Você pode permitir que células vazias sejam preenchidas com datas dos meses anteriores e subsequentes definindo a opção showOtherMonths como true, conforme mostrado no exemplo abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( showOtherMonths: true )); ));
O resultado é mostrado na figura abaixo. Neste caso, as datas pertencentes a outros meses ficam disponíveis se a opção selectOtherMonths estiver definida como true:
Definir a opção showButtonBar como true faz com que uma barra de botões adicionais seja adicionada na parte inferior da janela do widget Datepicker. No caso de calendário pop-up, o painel contém dois botões: “Hoje” e “Fechar”. O botão Hoje permite retornar à data atual e o botão Fechar fecha a janela do calendário. O texto usado para esses botões pode ser alterado usando as opções currentText e closeText.
Se a opção goToCurrent estiver definida como verdadeira, o calendário retornará para a data selecionada em vez da data atual. Este recurso será útil se o widget Datepicker estiver configurado com um valor de opção defaultDate específico. Se o objetivo da escolha de uma data estiver relacionado a eventos passados ou futuros, nem sempre é apropriado retornar à data atual. Um exemplo correspondente é dado abaixo:
$(function() ( $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#datep").datepicker(( showButtonPanel: true, currentText: "Go", gotoCurrent: true, defaultDate : "+1m +1y" )).val("20/12/2014" ));
Observe que usar a opção goToCurrent faz com que o botão seja pressionado para pular para a data selecionada. Neste exemplo, a data selecionada é o atributo de valor do elemento de entrada, mas se o usuário selecionar uma data diferente e reabrir o calendário, clicar no botão retornará o calendário à data selecionada pelo usuário, em vez da data especificada.
Os métodos suportados pelo widget Datepicker estão listados na tabela abaixo:
| selecionador de data("destruir") | Remove completamente a funcionalidade do widget Datepicker do elemento base |
| selecionador de data("desativar") | Pausa o widget Datepicker para o elemento subjacente |
| selecionador de data("habilitar") | Retoma um widget Datepicker pausado anteriormente para o elemento subjacente |
| datepicker("opção", opções) | Permite obter ou definir os valores de uma ou mais opções do widget Datepicker |
| datepicker("está desabilitado") | Retorna verdadeiro se o widget Datepicker estiver desabilitado |
| selecionador de data("ocultar") | Oculta o calendário pop-up se estiver visível |
| selecionador de data("mostrar") | Exibe um calendário pop-up se estiver invisível |
| selecionador de data("atualizar") | Atualiza o calendário para refletir as alterações feitas no item subjacente |
| selecionador de data("getData") | Obtém a data selecionada no calendário |
| datepicker("datadefinida", data) | Define o valor especificado como a data selecionada do calendário |
Os momentos mais comuns em que uso os métodos getDate e setDate são quando desejo dar aos usuários a capacidade de selecionar intervalos de datas inteiros usando vários widgets Datepicker. Nessas situações, prefiro não exibir as datas selecionadas nos campos de texto e exibir apenas o número de dias entre as datas limite especificadas. Um exemplo correspondente é dado abaixo:
rótulo jQuery UI (margem: 12px) entrada (largura: 200px; alinhamento de texto: esquerda) #wrapper > * (float: esquerda) #result (margem: automático; preenchimento: 10px; largura: 200px; limpar: esquerda) $( function() ( $("#result").hide(); $.datepicker.setDefaults($.datepicker.regional["ru"]); $("#dateStart, #dateEnd").datepicker(( minDate: "-7d", maxDate: "+7d", onSelect: function(date, datepicker) ( if (datepicker.id == "dateStart") ( $("#dateEnd").datepicker("setDate", data) . datepicker("enable").datepicker("option", "minDate", date) ) if (!$("#dateEnd").datepicker("isDisabled")) ( var startDate = $("#dateStart"). datepicker("getDate"); var endDate = $("#dateEnd").datepicker("getDate"); ; ) )).filter("#dateEnd").datepicker("desabilitar" )); Início: Fim: Número de dias:
Este exemplo cria dois calendários, um dos quais fica desativado imediatamente após o carregamento do documento. Para responder à seleção de datas do usuário, é utilizado o evento onSelect (do qual falaremos com mais detalhes posteriormente).
Depois que o usuário seleciona uma data no primeiro calendário, usamos o método setDate para preparar o segundo calendário e o método getDate para recuperar datas de ambos os calendários e então calcular a diferença em dias entre a primeira e a segunda data (para simplificar, nós suponha que ambas as datas sejam do mesmo e do mesmo mês). A visualização do documento na janela do navegador é mostrada na figura:
Como todos os widgets jQuery UI, o widget Datepicker oferece suporte a um conjunto de eventos que permitem ser notificado sobre mudanças importantes no estado do aplicativo. Esses eventos são mostrados na tabela abaixo:
Não demonstrarei novamente como o método onSelect funciona porque ele já foi usado em alguns exemplos, incluindo o discutido na seção anterior. A única coisa que quero salientar é que os argumentos passados para o manipulador de eventos são representações de string da data selecionada e da instância do Datepicker que gerou o evento.
O evento onChangeMonth permite responder ao evento que ocorre quando o usuário seleciona um mês ou ano diferente, seja por meio de listas suspensas habilitadas pelo uso das opções changeMonth e changeYear ou dos botões da página do mês.
Usando o método onClose, você pode responder ao fechamento de um calendário pop-up. Este evento é acionado mesmo que o usuário não tenha selecionado uma data no calendário. Os argumentos do manipulador de eventos são uma representação de string da data (ou uma string vazia se o usuário fechou a janela sem fazer uma seleção) e a instância do Datepicker que gerou o evento.
Descrição: Em uma janela pop-up ou calendário embutido para selecionar uma data.
Nova versão: 1.0
JQuery UI Datepicker Selecione uma data para adicionar a altura da página para personalizar o plugin. Você pode personalizar o formato e o idioma da data, limitar o intervalo de datas selecionável, adicionar botões e outras opções de navegação.
Por padrão, quando um campo de texto associado está em foco, uma pequena sobreposição de seletor de data aberta aparece. Para um calendário online, basta selecionar a data anexada ao DIV ou intervalo.
interação do tecladoQuando o seletor de data está aberto, os seguintes comandos de teclado estão disponíveis:
- PAGE UP: Vai para o mês anterior.
- PÁGINA PARA BAIXO: Mover para o próximo mês.
- CTRL + PAGE UP: Move para o ano anterior.
- CTRL + PAGE DOWN: Vai para o próximo ano.
- CTRL + HOME: Move o mês atual. Se o seletor de data estiver fechado, ele estará aberto.
- CTRL + ESQUERDA: Vai para o dia.
- CTRL + DIREITA: Vai para o dia seguinte.
- CTRL + UP: Vai para a semana anterior.
- CTRL + BAIXO: Vai para a próxima semana.
- ENTER: Selecione a data em foco.
- CTRL + END: Fecha o seletor de data e limpa a data.
- ESCAPE: Data de fechamento da torneira, sem escolha.
Altere as configurações padrão de todos os seletores de data.
20/08/2012 Romchik
Bom dia. Outro dia encontrei um problema - o usuário deve especificar uma data em um determinado formato na entrada. Sem quebrar a cabeça por muito tempo, decidi ter certeza de que, ao clicar na entrada, um calendário apareceria. Isso não é difícil de implementar, mas por quê? Se houver um widget de calendário jQuery maravilhoso - datepicker. A seguir falaremos sobre como instalar, configurar e conectar o datepicker.
Primeiro, darei um exemplo claro do que quero fazer:
Pois bem, é claro que após selecionar uma data, o calendário desaparece e a data selecionada aparece no campo de texto.
Vamos começar a implementação.
Acesse o site oficial do jQueryUI. Para evitar baixar nada desnecessário, clique em “Desmarcar todos os componentes”
E selecione “Núcleo”:
Isso é basicamente tudo. Mas este widget tem exibições predefinidas (temas)
No canto superior direito você pode selecionar um tema adequado, selecionar a versão do widget e clicar em “Download”:
Na próxima etapa, descompacte o arquivo.
Vamos concordar imediatamente com a estrutura da nossa página:
Agora colocamos os arquivos jquery-1.8.0.min.js e jquery-ui-1.8.23.custom.min.js do arquivo baixado na pasta js. Agora colocamos a pasta com o nome do tema para o datepicker (no meu caso é ui-lightness) da pasta css do arquivo baixado na pasta css da nossa página. Isso conclui a instalação do widget de calendário jQuery Datepicker.
Vamos começar a conectar o Datepicker. Como já disse, quero chamar o calendário ao clicar em um campo de texto. Vamos adicionar id=”datepicker” à nossa entrada para que possamos acessá-la facilmente.
Agora vamos escrever um pequeno script jQuery que chamará o calendário quando você clicar neste campo de teste:
$(function())( $("#datepicker").datepicker(); ));
Nós salvamos e verificamos.
Configurando um widget de calendário usando jQuery Datepicker.A primeira coisa que configuraremos é um tema para nosso calendário. Abaixo darei uma tabela com o nome do tema para Datepicker e sua exibição:
| Leveza da interface do usuário | |
| Escuridão da IU | |
| Suavidade | |
| Começar | |
| Redmond | |
| Ensolarado | |
| Nublado | |
| O Sapo | |
| Estalido | |
| Moedor de pimenta | |
| Beringela | |
| Colmeia Negra | |
| Cupertino | |
| rua sul | |
| Blitzer | |
| Humanidade | |
| Espreitadelas quentes | |
| Excitar bicicleta | |
| Vader | |
| Ponto Luv | |
| Calço de menta | |
| Chá preto | |
| Trontástico | |
| Bolsa chique |
Como você pode ver, existem temas suficientes para escolher o certo, mas se por algum motivo você não encontrou esse tema, você pode facilmente alterar um dos padrões alterando o arquivo de estilo do selecionador de data.
As configurações do datepicker não param por aí, e ao chamar a função datepicker podemos passar parâmetros adicionais:
| Parâmetro | Descrição | Exemplo |
| desativar: verdadeiro (falso) Padrão: falso | Ativar ou desativar o selecionador de data | $(“.selector”).datepicker(( desabilitado: verdadeiro )); |
| altField Padrão: vazio | Especifica o seletor do elemento que será atualizado | $(“.selector”).datepicker(( altField: “#actualDate” )); |
| altFormat Padrão: vazio | dateFormat - formato de data a ser usado para altField | $(“.selector”).datepicker(( altFormat: “aa-mm-dd” )); |
| anexarTex Padrão: vazio | Texto a ser exibido após cada campo de data | $(“.selector”).datepicker((appendText: “(aaaa-mm-dd)” )); |
| autoSize: verdadeiro (falso) Padrão: falso | Elemento de dimensionamento automático | $(“.selector”).datepicker(( autoSize: true )); |
| Formato de data: Padrão: mm/dd/aa Na tabela abaixo vou mostrar quais valores ele pode assumir. | Especifica o formato da data | $(“.selector”).datepicker(( dateFormat: “aa-mm-dd” )); |
| diasNomes Padrão ["Domingo segunda terça quarta quinta sexta sábado"] | Nomes completos dos dias da semana | $(“.selector”).datepicker(( dayNames: [“Segunda”, “Terça”, “Quarta”, “Quinta”, “Sexta”, “Sábado”, “Domingo”] )); |
| diaNomesMin Padrão: ["Su", "Mo", "Tu", "Nós", "Th", "Fr", "Sa"] | Abreviatura de dias da semana | $(“.selector”).datepicker(( dayNamesMin: [“Seg”,”Ter”,”Qua”,”Qui”,”Sex”,”Sábado”,”Dom”] )); |
| diaNomesShort Padrão: ["Dom", "Seg", "Ter", "Qua", "Qui", "Sex", "Sábado"] | Nomes abreviados de dias da semana | $(“.selector”).datepicker(( dayNamesShort: [“Seg”, “Ter”, “Qua”, “Qui”, “Sex”, “Sábado”, “Dom”] )); |
| data padrão Padrão: vazio Usa parâmetros dateFormat como parâmetros | Especifica a data padrão | $(“.selector”).datepicker(( data padrão: +7 )); |
| mêsNomes Padrão: ["Janeiro", "Fevereiro", "Março", "Abril", "Maio", "Junho", "Julho", "Agosto", "Setembro", "Outubro", "Novembro", "Dezembro"] | Nomes completos dos meses | $(“.selector”).datepicker(( mêsNomes: [“Janeiro”, “Fevereiro”, “Março”, “Abril”, “Maio”, “Junho”, “Julho”, “Agosto”, “Setembro”, "Outubro Novembro Dezembro"] )); |
| mêsNamesShort Padrão ["janeiro", "fevereiro", "março", "abril", "maio", "junho", "julho", "agosto", "setembro", "outubro", "novembro", "dezembro"] | Nome abreviado dos meses | $(“.selector”).datepicker((monthNamesShort: [“Jan”, “Fevereiro”, “Março”, “Abr”, “Maio”, “Junho”, “Jul”, “Agosto”, “Setembro”, "outubro", "novembro", "dezembro"] )); |
Aqui forneci apenas os parâmetros básicos que podem ser úteis para você. Se você quiser ver a lista completa de parâmetros, acesse a documentação oficial
Agora vamos ver os valores que o parâmetro dateFormat assume
É isso agora.
Examinamos a instalação, conexão e configuração de um dos maravilhosos widgets jQuery - o widget de calendário datepicker.
Espero que você tenha gostado do artigo. Se você tiver alguma dúvida, escreva nos comentários.
E com isso me despeço de você e do sucesso do desenvolvimento web.