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 que demonstra o IgrDateRangePicker 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

    Para começar a usar o IgrDateRangePicker, primeiro você precisa instalar o Ignite UI for React executando o seguinte comando:

    npm install igniteui-react

    Depois disso, você precisa importar o IgrDateRangePicker e seu CSS necessário, da seguinte forma:

    import { IgrDateRangePicker } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

    Agora você pode começar com uma configuração básica do React IgrDateRangePicker.

    Para obter uma introdução completa ao Ignite UI for React, leia o tópico Introdução.

    Usage

    O IgrDateRangePicker permite que os usuários selecionem uma data de início e término escolhendo um intervalo de datas em um pop-up suspenso/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 a em IgrDateRangePicker seu modo de entrada única padrão, use o seguinte código:

    <IgrDateRangePicker/>

    Para alternar o IgrDateRangePicker para usar duas entradas, defina a useTwoInputs propriedade como true.

    <IgrDateRangePicker useTwoInputs/>

    Value

    Além de ser selecionado ou digitado pelo usuário, o IgrDateRangePicker valor do intervalo do também pode ser definido usando a value propriedade. É importante observar que o valor deve seguir o formato: { start: startDate, end: endDate }, onde startDate e endDate são Date 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} />
);

    Além disso, o valor pode ser definido como atributo. Nesse caso, ele deve representar um objeto que pode ser analisado corretamente como JSON, onde os start campos e end devem ter valores de data no formato ISO 8601:

    <IgrDateRangePicker value={{start: new Date('2025-01-01'), end: new Date('2025-01-02')}}/>

    Read-only & Non-editable

    Você também pode tornar o IgrDateRangePicker somente leitura, o que desabilita a alteração do valor do intervalo por meio da digitação e da seleção de calendário, desabilita a navegação pelo teclado e faz com que o calendário e os ícones claros apareçam visualmente desabilitados. Isso é útil quando o intervalo é atribuído por meio do atributo value e deve ser somente exibição. Para habilitar esse comportamento, basta definir a readOnly propriedade.

    <IgrDateRangePicker useTwoInputs readOnly/>

    Como alternativa, você pode usar a nonEditable propriedade, que, ao contrário readOnly, impede apenas a edição da(s) entrada(s) por meio da digitação, enquanto ainda permite a seleção por meio do calendário e a limpeza por meio do ícone de limpeza.

    <IgrDateRangePicker useTwoInputs nonEditable/>

    Por padrão, quando clicado, o abre IgrDateRangePicker seu pop-up de calendário no dropdown modo. Como alternativa, o calendário pode ser aberto no dialog modo definindo a mode propriedade como dialog.

    <IgrDateRangePicker mode='dialog'/>

    Keyboard Navigation

    O IgrDateRangePicker apresenta navegação intuitiva pelo teclado, permitindo que os usuários aumentem, diminuam ou pulem facilmente entre diferentes partes componentes, tudo sem a necessidade de usar um 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 + ArrowDown Opens the calendar dropdown
    Alt + ArrowUp Closes the calendar dropdown

    Você também pode navegar no pop-up do calendário usando o teclado. A navegação é a mesma do IgrCalendar componente.

    Chaves Descrição
    ↑ / ↓ / ← / → Navega pelos dias do mês
    ENTER Seleciona o dia focado no momento
    PageUp Move para a visualização do mês anterior
    PageDown Passa para a visualização do próximo mês
    SHIFT + PageUp Mudanças para o ano anterior
    SHIFT + PageDown 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 o IgrDateRangePicker componente usando a label propriedade quando ele estiver no modo de entrada única. No modo de duas entradas, você pode usar as labelStart propriedades e labelEnd para definir rótulos para os campos de entrada da data de início e 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 de data exibido nos campos de entrada. Existem três propriedades disponíveis para esse fim: locale, inputFormat, e displayFormat.

    A locale propriedade permite que você defina o identificador de localidade desejado, que determina como a data é formatada com base em convenções regionais. Por exemplo, para exibir a data em um formato japonês, você pode definir a propriedade locale da seguinte forma:

    <IgrDateRangePicker locale='ja-JP'/>

    Se você quiser definir manualmente o formato de data, poderá usar a inputFormat propriedade passando uma cadeia de caracteres de formato personalizado:

    <IgrDateRangePicker inputFormat='dd/MM/yy'/>

    A displayFormat propriedade também aceita uma cadeia de caracteres de formato personalizado, mas só se aplica quando o campo de entrada está ocioso (ou seja, não focado). Quando o campo é focado, o formato é revertido para o padrão ou para o definido por inputFormat, se ambas as propriedades forem usadas juntas:

    <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 definir as propriedades e max para restringir a min entrada do usuário desativando as datas do calendário fora do intervalo definido. Essas propriedades atuam como validadores, portanto, mesmo que o usuário digite manualmente uma data fora do intervalo, elas IgrDateRangePicker 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 fichas de intervalo de datas personalizadas ao pop-up do calendário para uma seleção mais rápida do intervalo usando a customRanges propriedade. Por exemplo, você pode criar um chip de intervalo de datas personalizado para selecionar rapidamente o intervalo para os próximos 7 dias, terminando com a data atual. Além disso, ao definir a usePredefinedRanges propriedade, um conjunto de chips de intervalos predefinidos será exibido junto com os 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 chip recém-criado "Next 7 days" 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 pode definir datas desativadas no calendário para restringir o intervalo de datas que o usuário pode escolher. Para definir as datas desativadas, você pode usar a disabledDates propriedade.

    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} />
);

    Forms

    O IgrDateRangePicker componente também pode ser usado perfeitamente com o elemento de formulário HTML. As min propriedades , max, e required atuam como validadores de formulário.

    Additional configuration

    Properties

    Além das propriedades que já abordamos, o IgrDateRangePicker 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 pode adicionar conteúdo personalizado e modificar a IgrDateRangePicker aparência do componente usando os slots disponíveis.

    Os prefix slots e suffix 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 duas entradas, você pode usar os prefix-start slots , prefix-end, suffix-start, e suffix-end para direcionar as entradas individuais.

    Outro conjunto de slots úteis são clear-icon e calendar-icon, que permitem personalizar os ícones dos botões de limpeza 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 o separator slot:

    <IgrDateRangePicker useTwoInputs>
  <span slot='separator'>till</span>
</IgrDateRangePicker>

    O actions slot permite que você insira um botão de ação personalizado com sua própria lógica. Por exemplo, o botão abaixo alterna a coluna de números da semana 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 dos slots que já abordamos, os seguintes slots também estão disponíveis no IgrDateRangePicker 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, o IgrDateRangePicker também 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 o IgrDateRangePicker componente usa o IgrCalendar componente, ele também herda as partes CSS do Calendário, permitindo que você estilize os dois componentes perfeitamente. Você pode encontrar a lista completa de partes CSS do Calendário expostas aqui: Estilo do Calendário. Além das partes CSS do Calendário, o IgrDateRangePicker também expõe algumas partes CSS exclusivas 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);
}

    API References

    Additional Resources