Visão geral do seletor de intervalo de datas do React
O Ignite UI for React Seletor de Intervalo de Datas é um componente leve que inclui uma entrada de texto e um pop-up de calendário, permitindo que os usuários selecionem facilmente as datas de início e término. É altamente personalizável para atender a vários requisitos de aplicativos, oferecendo recursos como restrições de intervalo de datas, formatos de data configuráveis e muito mais.
Date Range Picker Example
Abaixo está um exemplo demonstrando oIgrDateRangePicker componente em ação, onde um pop-up de calendário permite que os usuários selecionem datas de início e término.
Começando
To start using the IgrDateRangePicker, you first need to install the Ignite UI for React by running the following command:
npm install igniteui-react
After that, you need to import the IgrDateRangePicker and its necessary CSS, as follows:
import { IgrDateRangePicker } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';
Now you can start with a basic configuration of the React IgrDateRangePicker.
Para uma introdução completa ao Ignite UI for React, leia o tópico Comecando.
Usage
PermiteIgrDateRangePicker que os usuários selecionem uma data de início e término, seja escolhendo um intervalo de datas em um menu suspenso/pop-up de calendário ou digitando diretamente nos campos de entrada - um para a data de início e outro para a data de término.
O seletor oferece dois modos para exibir valores de data: entrada única e duas entradas. No modo de entrada única, o campo não é editável e o intervalo de datas não pode ser editado digitando. No modo de duas entradas, no entanto, os usuários podem editar as datas de início e término digitando em campos de entrada separados.
Quando o calendário está visível, um intervalo de datas pode ser selecionado escolhendo uma data de início e término. Selecionar uma data definirá a data de início e término e, assim que uma segunda data for escolhida, definirá a data de término. Se um intervalo já estiver selecionado, clicar em qualquer outra data no calendário iniciará uma nova seleção de intervalo.
Display Date Range Picker
Para instanciar aIgrDateRangePicker em seu modo padrão de entrada única, use o seguinte código:
<IgrDateRangePicker/>
Para mudar oIgrDateRangePicker para usar duas entradas, defina auseTwoInputs propriedade paratrue.
<IgrDateRangePicker useTwoInputs/>
Value
Além de ser selecionado ou digitado pelo usuário, o valor de intervalo doIgrDateRangePicker também pode ser definido usando avalue propriedade. É importante notar que o valor deve seguir o formato: { start: startData, fim: fimData }, ondestartDate eendDate sãoDate objetos que representam o intervalo selecionado.
const dateRangeRef = useRef<IgrDateRangePicker>();
let startDate = new Date(2025, 4, 6);
let endDate = new Date(2025, 4, 8);
useEffect (() => {
dateRangeRef.current.value = { start: startDate, end: endDate }
}, [])
return (
<IgrDateRangePicker ref={dateRangeRef} />
);
<IgrDateRangePicker value={{start: new Date('2025-01-01'), end: new Date('2025-01-02')}}/>
Read-only & Non-editable
Você também pode fazer com que oIgrDateRangePicker modo somente leitura, que desativa a alteração do valor do intervalo tanto por meio da digitação quanto da seleção do calendário, desativa a navegação por teclado e faz com que os ícones do calendário e do clear apareçam visualmente desativados. Isso é útil quando o intervalo é atribuído via o atributo valor e é destinado a ser apenas exibido. Para habilitar esse comportamento, basta definir areadOnly propriedade.
<IgrDateRangePicker useTwoInputs readOnly/>
Alternativamente, você pode usar anonEditable propriedade que, ao contrárioreadOnly, só impede a edição do(s) input(s) digitando(s), enquanto ainda permite a seleção pelo calendário e a limpeza pelo ícone de limpeza.
<IgrDateRangePicker useTwoInputs nonEditable/>
Popup modes
Por padrão, ao clicar, eleIgrDateRangePicker abre o pop-up do calendário nodropdown modo. Alternativamente, o calendário pode ser aberto nodialog modo definindo amode propriedade paradialog.
<IgrDateRangePicker mode='dialog'/>
Keyboard Navigation
O programaIgrDateRangePicker oferece navegação intuitiva por teclado, permitindo que os usuários incrementem, diminuam ou pulem facilmente entre diferentes componentes, tudo isso sem precisar usar mouse.
As opções de navegação do teclado disponíveis variam dependendo se o componente está no modo de entrada única ou de duas entradas.
Modo de duas entradas:
| Chaves | Descrição |
|---|---|
| ← | Move o cursor um caractere para a esquerda |
| → | Move o cursor um caractere para a direita |
| CTRL + ArrowLeft | Move o cursor para o início da seção de máscara de entrada atual ou para o início da anterior, se já estiver no início |
| CTRL + ArrowRight | Move o cursor para o final da seção de máscara de entrada atual ou para o final da próxima, se já estiver no final |
| ArrowUp | Incrementa a parte atualmente "focada" da máscara de entrada em uma etapa |
| ArrowDown | Diminui a parte atualmente "focada" da máscara de entrada em um passo |
| CASA | Move o cursor para o início da máscara de entrada |
| FIM | Move o cursor para o final da máscara de entrada |
| CTRL +; | Define a data atual como o valor do componente |
Modos de entrada única e dupla:
| Chaves | Descrição |
|---|---|
| ALT + ↓ | Opens the calendar dropdown |
| ALT + ↑ | Closes the calendar dropdown |
Você também pode navegar dentro do pop-up do calendário usando o teclado. A navegação é a mesma doIgrCalendar componente.
| Chaves | Descrição |
|---|---|
| ↑ / ↓ / ← / → | Navega pelos dias do mês |
| ENTER | Seleciona o dia focado no momento |
| PÁGINA ACIMA | Move para a visualização do mês anterior |
| PÁGINA ABAIXO | Passa para a visualização do próximo mês |
| SHIFT + PAGE UP | Mudanças para o ano anterior |
| SHIFT + PAGE DOWN | Muda para o próximo ano |
| CASA | Concentra o primeiro dia do mês atual que está em exibição (ou o mês mais antigo quando a exibição de mais de um mês é exibida) |
| FIM | Concentra o último dia do mês atual que está em exibição. (ou o último mês, quando a visualização de mais de um mês é exibida) |
| Escape | Fecha o pop-up do calendário |
Layout
Label
Você pode definir um rótulo para oIgrDateRangePicker componente usando alabel propriedade quando ele está em modo de entrada única. No modo de duas entradas, você pode usar aslabelStart propriedades elabelEnd para definir etiquetas para os campos de entrada de início e data de término, respectivamente.
<IgrDateRangePicker label='Date Range'/>
<IgrDateRangePicker useTwoInputs labelStart='Start Date' labelEnd='End Date'/>
Format
Você também tem a opção de personalizar o formato da data exibido nos campos de entrada. Existem três propriedades disponíveis para esse propósito:locale,inputFormat, edisplayFormat.
Alocale propriedade permite definir o identificador de local desejado, que determina como a data é formatada com base em convenções regionais. Por exemplo, para exibir a data em formato japonês, você pode definir a propriedade de localização assim:
<IgrDateRangePicker locale='ja-JP'/>
Se você quiser definir manualmente o formato de data, pode usar ainputFormat propriedade passando uma string de formato personalizada:
<IgrDateRangePicker inputFormat='dd/MM/yy'/>
AdisplayFormat propriedade também aceita uma string de formato personalizada, mas ela só se aplica quando o campo de entrada está ocioso (ou seja, não focado). Quando o campo é focado, o formato retorna ao padrão ou ao definido porinputFormat, se ambas as propriedades forem usadas juntos:
<IgrDateRangePicker inputFormat='dd/MM/yy' displayFormat='yy/MM/dd'/>
Calendar Layout and Formatting
You can further customize the pop-up calendar using various properties:
| Nome | Tipo | Descrição |
|---|---|---|
orientation |
'vertical' or 'horizontal' | Permite definir se o calendário deve ser exibido vertical ou horizontalmente. |
visibleMonths |
corda | Controla quantos meses são visíveis por vez, com um valor de 1 ou 2. |
showWeekNumbers |
corda | Ativa ou desativa a coluna de número da semana no calendário. |
open |
booleano | Determina se o seletor de calendário está aberto. |
keepOpenOnSelect |
booleano | Mantém o seletor de calendário aberto após uma seleção de data. |
keepOpenOnOutsideClick |
booleano | Mantém o seletor de calendário aberto ao clicar fora dele. |
weekStart |
corda | Define o dia de início da semana. |
hideOutsideDays |
booleano | Oculta os dias que estão fora da exibição do mês atual. |
hideHeader |
booleano | Oculta o cabeçalho do calendário (aplicável somente no modo de diálogo). |
headerOrientation |
'vertical' or 'horizontal' | Aligns the calendar header vertically or horizontally (dialog mode only). |
activeDate |
Data | Define a data inicialmente destacada no calendário. Se não for definida, a data atual se tornará a data ativa. |
<IgrDateRangePicker orientation='vertical' visibleMonths={1} showWeekNumbers/>
Min & Max
Você também pode configurar asmin propriedades andmax para restringir a entrada do usuário desativando datas do calendário fora do intervalo definido. Essas propriedades atuam como validadores, então mesmo que o usuário digite manualmente uma data fora do intervalo, elasIgrDateRangePicker se tornarão inválidas.
<IgrDateRangePicker min={new Date('2025-05-06')} max={new Date('2025-05-10')}/>
Custom & Predefined Date Ranges
Você também pode adicionar chips personalizados de intervalo de datas ao pop-up do calendário para uma seleção de intervalo mais rápida usando acustomRanges propriedade. Por exemplo, você pode criar um chip personalizado de intervalo de datas para selecionar rapidamente o intervalo dos próximos 7 dias, terminando com a data atual. Além disso, ao definir ausePredefinedRanges propriedade, um conjunto de chips de ranges predefinidos será exibido junto com os chips personalizados.
const today = new Date();
const nextSeven = new Date(
today.getFullYear(),
today.getMonth(),
today.getDate() + 7
);
const nextWeek: CustomDateRange[] = [
{
label: "Next 7 days",
dateRange: {
start: today,
end: nextSeven
}
}
];
return (
<IgrDateRangePicker usePredefinedRanges customRanges={nextWeek} />
);
Agora, quando você clicar no recém-criado chip "Próximos 7 dias" no pop-up do calendário, o intervalo será selecionado automaticamente, de hoje até os próximos 7 dias.
Disabled & Special dates
Você também tem a opção de definir datas desativadas no calendário para restringir a faixa de datas que o usuário pode escolher. Para definir as datas de desativação, você pode usar odisabledDates imóvel.
const dateRangeRef = useRef<IgrDateRangePicker>();
const minDate = new Date(2025, 4, 5);
const maxDate = new Date(2025, 4, 15);
useEffect (() => {
dateRangeRef.current.disabledDates = [
{
type: DateRangeType.Between,
dateRange: [minDate, maxDate]
}
] as DateRangeDescriptor[];
}, [])
return (
<IgrDateRangePicker ref={dateRangeRef} />
);
Você pode ver mais informações sobre todas as possibilidades que odisabledDates imóvel oferece aqui: Datas para pessoas com deficiência
Você também pode fazer o mesmo se quiser definir uma ou mais datas especiais no calendário; A única diferença é que você precisa usar ospecialDates imóvel em vez disso. Datas especiais
Forms
OIgrDateRangePicker componente também pode ser usado de forma fluida com o elemento de formulário HTML. Asmin propriedades emaxrequired atuam como validadores de formulário.
Additional configuration
Properties
Além das propriedades que já abordamos, oIgrDateRangePicker componente oferece uma variedade de propriedades adicionais que permitem configurar ainda mais seu comportamento.
| Nome | Tipo | Descrição |
|---|---|---|
disabled |
booleano | Desativa o componente. |
nonEditable |
booleano | Desativa a digitação no(s) campo(s) de entrada. |
placeholder |
corda | Texto de espaço reservado para o modo de entrada único. |
placeholderStart |
corda | Texto de espaço reservado para a entrada da data de início (modo de duas entradas). |
placeholderEnd |
corda | Texto de espaço reservado para a entrada da data de término (modo de duas entradas). |
outlined |
booleano | Determina se a parte de entrada terá a aparência de contorno no tema Material. |
prompt |
corda | O caractere de prompt usado para partes não preenchidas da máscara de entrada. |
resourceStrings |
IgcDateRangePickerResourceStrings | Cadeias de caracteres de recurso para localização do seletor de intervalo de datas e do calendário. |
Slots
Você também tem a capacidade de adicionar conteúdo personalizado e modificar a aparência doIgrDateRangePicker componente usando os slots disponíveis.
Osprefix slots andsuffix permitem inserir conteúdo personalizado antes ou depois do campo de entrada (disponível apenas no modo de entrada única):
<IgrDateRangePicker>
<IgrIcon slot='prefix' name='down_arrow_icon'></IgrIcon>
<IgrIcon slot='suffix' name='upload_icon'></IgrIcon>
</IgrDateRangePicker>
No modo de dois comandos, você pode usar osprefix-start slots ,prefix-end,suffix-start, esuffix-end para direcionar os comandos individuais.
Outro conjunto de espaços úteis sãoclear-icon os andcalendar-icon, que permitem personalizar os ícones dos botões de limpar e calendário nos campos de entrada:
<IgrDateRangePicker>
<IgrIcon slot="clear-icon" name="apps_icon"></IgrIcon>
<IgrIcon slot="calendar-icon" name="bin_icon"></IgrIcon>
</IgrDateRangePicker>
No modo de duas entradas, você também pode personalizar o texto padrão "para" entre os campos usando oseparator slot:
<IgrDateRangePicker useTwoInputs>
<span slot='separator'>till</span>
</IgrDateRangePicker>
Oactions slot permite inserir um botão de ação personalizado com sua própria lógica. Por exemplo, o botão abaixo alterna a coluna dos números das semanas no calendário:
const dateRangeRef = useRef<IgrDateRangePicker>();
const toggleWeekNumbers = () => {
dateRangeRef.current.showWeekNumbers = !dateRangeRef.current.showWeekNumbers;
};
return (
<IgrDateRangePicker ref={dateRangeRef}>
<IgrButton slot="actions" onClick={toggleWeekNumbers}>Toggle Week Numbers</IgrButton>
</IgrDateRangePicker>
);
Além das slots que já abordamos, as seguintes também estão disponíveis noIgrDateRangePicker componente:
| Nome | Descrição |
|---|---|
title |
Renderiza o conteúdo do título do calendário. Aplicável somente no modo de diálogo. |
helper-text |
Renders content below the input field(s). |
header-date |
Substitui o texto padrão de data/intervalo atual no cabeçalho do calendário. Aplicável somente no modo de diálogo. |
clear-icon-start |
Ícone claro personalizado para a entrada inicial (modo de duas entradas). |
clear-icon-end |
Ícone claro personalizado para a entrada final (modo de duas entradas). |
calendar-icon-start |
Ícone de calendário personalizado para a entrada inicial (modo de duas entradas). |
calendar-icon-end |
Ícone de calendário personalizado para a entrada final (modo de duas entradas). |
calendar-icon-open |
Ícone ou conteúdo mostrado quando o seletor está aberto (aplica-se a ambas as entradas no modo de duas entradas). |
calendar-icon-open-start |
Ícone ou conteúdo para o estado aberto da entrada inicial (modo de duas entradas). |
calendar-icon-open-end |
Ícone ou conteúdo para o estado aberto da entrada final (modo de duas entradas). |
Methods
Além das propriedades e slots, tambémIgrDateRangePicker expõe alguns métodos que você pode usar:
| Nome | Descrição |
|---|---|
show |
Exibe o componente seletor de calendário. |
hide |
Hides the calendar picker component. |
toggle |
Alterna o seletor de calendário entre os estados mostrado e oculto. |
clear |
Limpa os campos de entrada, removendo qualquer entrada do usuário. |
select |
Seleciona um valor de intervalo de datas no seletor. |
setCustomValidity |
Define uma mensagem de validação personalizada. Se a mensagem fornecida não estiver vazia, a entrada será marcada como inválida. |
Styling
Como oIgrDateRangePicker componente usa oIgrCalendar componente, ele também herda as partes CSS do Calendar, permitindo que você estilize ambos os componentes de forma fluida. Você pode encontrar a lista completa das partes expostas do CSS do Calendário aqui: Estilização do Calendário. Além das partes CSS do Calendário, eleIgrDateRangePicker também expõe algumas partes únicas de CSS que você pode usar para personalizar sua aparência:
| Nome | Descrição |
|---|---|
separator |
O elemento separador entre as duas entradas. |
ranges |
O wrapper que renderiza os intervalos personalizados e predefinidos. |
label |
O wrapper de rótulo que renderiza o conteúdo acima da entrada de destino. |
container |
O wrapper principal que contém todos os principais elementos de entrada. |
input |
O elemento de entrada nativo. |
prefix |
O wrapper de prefixo. |
suffix |
O wrapper de sufixo. |
calendar-icon |
O wrapper do ícone de calendário para o estado fechado. |
calendar-icon-start |
O wrapper do ícone de calendário para o estado fechado da entrada inicial (duas entradas). |
calendar-icon-end |
O wrapper do ícone de calendário para o estado fechado da entrada final (duas entradas). |
calendar-icon-open |
O wrapper do ícone de calendário para o estado aberto. |
calendar-icon-open-start |
O wrapper do ícone de calendário para o estado aberto da entrada inicial (duas entradas). |
calendar-icon-open-end |
O wrapper do ícone de calendário para o estado aberto da entrada final (duas entradas). |
clear-icon |
O wrapper de ícone claro (entrada única). |
clear-icon-start |
O wrapper de ícone claro para a entrada inicial (duas entradas). |
clear-icon-end |
O wrapper de ícone claro para a entrada final (duas entradas). |
actions |
O wrapper de ações. |
helper-text |
O wrapper de texto auxiliar que renderiza o conteúdo abaixo da entrada de destino. |
igc-date-range-picker::part(label) {
color: var(--ig-gray-600);
}
igc-date-range-picker::part(calendar-icon-start),
igc-date-range-picker::part(calendar-icon-end) {
background-color: var(--ig-primary-500);
color: var(--ig-primary-500-contrast);
}
igc-date-range-picker::part(calendar-icon-open-start),
igc-date-range-picker::part(calendar-icon-open-end) {
background-color: var(--ig-primary-700);
color: var(--ig-primary-700-contrast);
}
igc-date-range-picker::part(clear-icon-start),
igc-date-range-picker::part(clear-icon-end) {
background-color: var(--ig-error-500);
color: var(--ig-error-500-contrast);
}