Visão geral do componente Angular Date Range Picker

O Angular 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.

Angular Date Range Picker Example

Abaixo está um exemplo que demonstra o IgxDateRangePickerComponent componente em ação, onde um pop-up de calendário permite que os usuários selecionem datas de início e término.

Getting Started with Ignite UI for Angular Date Range Picker

Para começar a usar o componente Ignite UI for Angular IgxDateRangePickerComponent, primeiro você precisa instalar Ignite UI for Angular. Em um aplicativo Angular existente, digite o seguinte comando:

ng add igniteui-angular

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

O próximo passo é importar o IgxDateRangePickerModule no seu arquivo app.module.ts.

Como o IgxDateRangePickerComponent usa o IgxCalendarComponent, ele também tem uma dependência do BrowserAnimationsModule e, opcionalmente, do HammerModule para interações de toque, portanto, eles também precisam ser adicionados ao BrowserAnimationsModule e, opcionalmente, do HammerModule para interações de toque, portanto, eles também precisam ser adicionados ao AppModule BrowserAnimationsModule

// app.module.ts

import { IgxDateRangePickerModule } from 'igniteui-angular';
// import { IgxDateRangePickerModule } from '@infragistics/igniteui-angular'; for licensed package

import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

@NgModule({
    ...
    imports: [..., IgxDateRangePickerModule, BrowserAnimationsModule, HammerModule],
    ...
})
export class AppModule {}

Como alternativa, a partir de 16.0.0 você pode importar o IgxDateRangePickerComponent como uma dependência autônoma ou usar o IGX_DATE_RANGE_PICKER_DIRECTIVES token para importar o componente e todos os seus componentes e diretivas de suporte.

// home.component.ts

import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IGX_DATE_RANGE_PICKER_DIRECTIVES } from 'igniteui-angular';
// import { IGX_DATE_RANGE_PICKER_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-date-range-picker [value]="range"></igx-date-range-picker>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [BrowserAnimationsModule, HammerModule, IGX_DATE_RANGE_PICKER_DIRECTIVES]
    /* or imports: [BrowserAnimationsModule, HammerModule, IgxDateRangePickerComponent] */
})
export class HomeComponent {}

Agora que você importou o módulo Ignite UI for Angular Date Range Picker ou as diretivas, você pode começar a usar o componente igx-date-range-picker.

Using the Angular Date Range Picker Component

Display and Value

Para instanciar um seletor de intervalo de datas em seu modo padrão, use o seguinte código:

<igx-date-range-picker [value]="range"></igx-date-range-picker>

public range: DateRange = { start: new Date(2020, 4, 20), end: new Date(2020, 4, 25) };

Note

O valor do Seletor de Intervalo de Datas é do tipo DateRange, que contém uma data de início e uma 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. A seleção de 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.

Para criar uma ligação de dados bidirecional, use ngModel:

<igx-date-range-picker [(ngModel)]="range"></igx-date-range-picker>

Display Separate Editable Inputs

O componente Angular Date Range Picker também permite configurar duas entradas separadas para data de início e término. Isso pode ser obtido usando IgxDateRangeStartComponent e IgxDateRangeEndComponent como filhos do seletor de intervalo de datas, conforme mostrado na demonstração abaixo:

<igx-date-range-picker [(ngModel)]="range">
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-end>
</igx-date-range-picker>

Tanto o IgxDateRangeStartComponent quanto IgxDateRangeEndComponent estendem o IgxInputGroupComponent existente. Para que tal configuração funcione, é necessário definir um IgxInput. Além disso, todos os outros componentes e diretivas disponíveis para o IgxInputGroupComponent também podem ser usados.
Para habilitar a edição de data para ambas as entradas, você precisa decorá-las com a diretiva igxDateTimeEditor.

Por padrão, quando clicado, o abre IgxDateRangePickerComponent 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.

<igx-date-range-picker [mode]="'dialog'"></igx-date-range-picker>

Em uma configuração padrão com uma única entrada somente leitura, o calendário pode ser aberto clicando em qualquer lugar na entrada, incluindo o ícone do calendário. Quando há duas entradas separadas para a data de início e término, e no modo suspenso, o calendário só pode ser aberto a partir do ícone do calendário, pois ambas as entradas são editáveis por padrão. Para duas entradas no dialog modo, clicar em qualquer lugar na entrada abre o calendário

O valor do intervalo é definido quando as datas são selecionadas no calendário. Você notará que, no modo suspenso, o Done botão não está disponível. No modo de diálogo, um Cancel botão permite reverter a seleção ao fechar.

O IgxDateRangePickerComponent 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

A seção de navegação do teclado do calendário contém todas as combinações de teclado que podem ser usadas no calendário.

Layout

Projecting components

Para enriquecer o UX do Date Range Picker padrão, o componente permite projetar componentes filhos - o mesmo que no IgxInputGroupComponent: igxLabel, igx-hint / igxHint, igx-prefix / igxPrefix, igx-suffix / igxSuffix, excluindo IgxInput. Informações mais detalhadas sobre isso podem ser encontradas no tópico Label & Input.

<igx-date-range-picker #dateRangePicker [(ngModel)]="range">
    <label igxLabel>Flight dates</label>
    <igx-hint *ngIf="dateRangePicker.invalid">
        Please choose start and end date!
    </igx-hint>
</igx-date-range-picker>

Ou para duas entradas:

<igx-date-range-picker #dateRangePicker [(ngModel)]="range">
    <igx-date-range-start>
        ...
        <label igxLabel>Start Date</label>
        <igx-hint *ngIf="dateRangePicker.invalid">
            Please choose start and end date!
        </igx-hint>
        ...
    </igx-date-range-start>
    <igx-date-range-end>
        ...
        <label igxLabel>End Date</label>
        ...
    </igx-date-range-end>
</igx-date-range-picker>

Alternar e limpar ícones

Na configuração padrão, com uma única entrada somente leitura, um ícone de calendário padrão é mostrado como um prefixo e um ícone claro - como um sufixo. Esses ícones podem ser alterados ou redefinidos usando o IgxPickerToggleComponent e IgxPickerClearComponent. Eles podem ser decorados com um ou igxPrefix igxSuffix outro, que definirá sua posição - no início ou no final, respectivamente:

<igx-date-range-picker>
    <igx-picker-toggle igxSuffix>
        <igx-icon>calendar_view_day</igx-icon>
    </igx-picker-toggle>
    <igx-picker-clear igxSuffix>
        <igx-icon>clear</igx-icon>
    </igx-picker-clear>
</igx-date-range-picker>

Quando um Seletor de Intervalo de Datas tem duas entradas separadas para datas de início e término, ele não expõe esses ícones por padrão. O IgxPickerToggleComponent e IgxPickerClearComponent deve ser adicionado manualmente como filhos do IgxDateRangeStartComponent ou IgxDateRangeEndComponent assim:

<igx-date-range-picker>
    <igx-date-range-start>
        ...
        <igx-picker-toggle igxPrefix>
            <igx-icon>calendar_view_day</igx-icon>
        </igx-picker-toggle>
        <igx-picker-clear igxSuffix>
            <igx-icon>clear</igx-icon>
        </igx-picker-clear>
        ...
    </igx-date-range-start>
    <igx-date-range-end>
        ...
    </igx-date-range-end>
</igx-date-range-picker>

Custom And 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.

public today = new Date();

public nextSeven = new Date(
    this.today.getFullYear(),
    this.today.getMonth(),
    this.today.getDate() + 7
);

public customRanges: CustomDateRange[] = [
    {
        label: 'Next 7 days',
        dateRange: {
          start: this.today,
          end: this.nextSeven
        }
      }
];

<igx-date-range-picker [usePredefinedRanges]="true" [customRanges]="customRanges"></igx-date-range-picker>

Além disso, o conteúdo ou as ações personalizadas podem ser modelados usando a igxPickerActions diretiva. A demonstração a seguir mostra os intervalos predefinidos e personalizados junto com as ações modeladas:

Formatting

O componente Seletor de intervalo de datas oferece suporte a diferentes formatos de exibição e entrada.

O formato de exibição do valor pode ser um dos formatos Angular DatePipe listados. Isso permite que ele suporte opções de formato predefinidas, como shortDate e longDate.

A propriedade inputFormat aceita uma string de formato construída usando caracteres suportados pelo DatePipe, por exemplo, MM/dd/yyyy, mas não suporta opções de formato predefinidas, como shortDate e longDate. Se a propriedade inputFormat não for definida, o token de ID de localidade Angular será usado ao criá-la.

<igx-date-range-picker [(ngModel)]="range" required
    inputFormat="dd/MM/yyyy" displayFormat="shortDate">
</igx-date-range-picker>

Se a propriedade inputFormat não estiver definida, o formato de entrada será inferido do displayFormat, caso possa ser analisado como contendo apenas partes numéricas de data e hora.

Note

O IgxDateRangePicker agora suporta entrada IME. Quando a composição termina, o controle converte os números de caracteres largos em caracteres ASCII.

Forms and Validation

O componente Seletor de intervalo de datas dá suporte a todas as diretivas do núcleo Módulo de Formulários, Modelo NgNgModel e Módulo ReactiveForms (FormControl, FormGroup, etc.). Isso também inclui o Validadores de formulários Funções. Além disso, o componente valores mínimo e máximo e disabledDates também atuam como validadores de formulário.

O NgModel e os validadores podem ser definidos no IgxDateRangePickerComponent ou nas entradas individuais de data de início e término.

Os seguintes trechos e exemplos ilustram o uso do validador required em um formulário orientado a modelo.

Primeiro, precisamos configurar o modelo para um único componente de intervalo somente leitura, o que é feito no nível do componente:

<igx-date-range-picker [(ngModel)]="range" required>
    <label igxLabel>Period</label>
</igx-date-range-picker>

A mesma configuração pode ser usada ao definir duas entradas separadas. Note que, neste caso, a validação também é aplicada a ambas as entradas.

<igx-date-range-picker [(ngModel)]="range" required>
    <igx-date-range-start>
        <label igxLabel>Start Date</label>
        <input igxInput igxDateTimeEditor type="text">
        <igx-picker-toggle igxPrefix>
            <igx-icon>calendar_today</igx-icon>
        </igx-picker-toggle>
    </igx-date-range-start>
    <igx-date-range-end>
        <label igxLabel>End Date</label>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-end>
</igx-date-range-picker>

Ao usar duas entradas separadas, é possível definir o modelo e as propriedades necessárias em cada entrada. Observe que a validação é específica para cada entrada individual.

<igx-date-range-picker>
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-range-end>
</igx-date-range-picker>

Min and max values

Você pode especificar as propriedades minValue e maxValue para restringir a entrada do usuário desabilitando datas do calendário que estejam fora do intervalo definido por esses valores.

public minDate = new Date(2020, 1, 15);
public maxDate = new Date(2020, 11, 1);

<igx-date-range-picker [(ngModel)]="range" required
    [minValue]="minDate" [maxValue]="maxDate">
</igx-date-range-picker>

<igx-date-range-picker [minValue]="minDate" [maxValue]="maxDate">
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-range-end>
</igx-date-range-picker>

O IgxDateRangePickerComponent também é um validador, o que significa que ele controla sua validade internamente usando minValue e maxValue. Você também pode acessar ambos por meio de ngModel:

<igx-date-range-picker #dateRangePicker="ngModel" [(ngModel)]="range" required
    [minValue]="minDate" [maxValue]="maxDate">
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-start>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor type="text">
    </igx-date-range-end>
</igx-date-range-picker>

<!-- minValue & maxValue will be true if the current range does not satisfy them -->
<div *ngIf="dateRangePicker.minValue || dateRangePicker.maxValue">
    <p>Value not in range.</p>
</div>

Disabled And 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.

export class DateRangeSampleComponent implements OnInit {
    @ViewChild('dateRange') public dateRange: IgxDateRangePicker;

    public minDate = new Date(2025, 4, 1);
    public maxDate = new Date(2025, 4, 31);

    public ngOnInit() {
        this.dateRange.disabledDates = [
        {
            type: DateRangeType.Between,
            dateRange: [minDate, maxDate]
        }
        ] as DateRangeDescriptor[];
    }
}

Você pode ver mais informações sobre todas as possibilidades que a DisabledDates propriedade oferece aqui: datas desativadas pelo calendário.

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 a SpecialDates propriedade. Datas especiais

Templating

Quando dois editores são usados, o separador padrão pode ser substituído usando a diretiva igxDateRangeSeparator. Aqui está como alterar o separador de data para um hífen-:

<igx-date-range-picker>
    <igx-date-range-start>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.start" type="text" required>
    </igx-date-range-start>
    <ng-template igxDateRangeSeparator>-</ng-template>
    <igx-date-range-end>
        <input igxInput igxDateTimeEditor [(ngModel)]="range.end" type="text" required>
    </igx-date-range-end>
</igx-date-range-picker>

Calendar specific settings

Você pode personalizar ainda mais o calendário pop-up usando várias propriedades. Mais informações sobre como isso afeta o calendário podem ser encontradas no tópico IgxCalendarComponent.

Nome	Tipo	Descrição
`orientation`	'vertical' or 'horizontal'	Permite definir se o calendário deve ser exibido vertical ou horizontalmente.
`displayMonthsCount`	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.
`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.

 <igx-date-range-picker [hideHeader]="true"
                        [orientation]="'vertical'"
                        [headerOrientation]="'horizontal'"
                        [displayMonthsCount]="1">
</igx-date-range-picker>

As partes de cabeçalho, subtítulo e título do cabeçalho do calendário podem ser personalizadas aproveitando as igxCalendarHeader diretivas , igxCalendarSubheader e o igxCalendarHeaderTitle modelo, por exemplo:

<igx-date-range-picker [value]="date">
  <ng-template igxCalendarHeader let-format>
    {{ format.month.combined | titlecase }}{{format.day.combined }}{{ format.weekday.combined }}
  </ng-template>
  <ng-template igxCalendarSubheader let-format>
    <span (click)="format.yearView()">{{ format.year.combined }}</span>
    <span (click)="format.monthView()">{{ format.month.combined | titlecase }}</span>
  </ng-template>
    <ng-template igxCalendarHeaderTitle let-format>
    <span>My calendar</span>
  </ng-template>
</igx-date--range-picker>

Estilização

Para começar a estilizar o igxDateRangePicker, precisamos importar o arquivo index, onde todas as funções do tema e mixins de componentes estão localizados:

@use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

O componente Date Range Picker expõe date-range-picker-theme e utiliza vários componentes e diretivas, incluindo igxInputGroupComponent, igxCalendar e igxOverlay. Qualquer estilo global para os componentes e diretivas mencionados acima afetará o igxDateRangeComponent. Como o componente Date Range Picker usa os temas input group e calendar , temos que criar novos temas que estendam calendar-theme e input-group-theme e usar alguns de seus parâmetros para estilizar o date range picker em conjunto com o date range picker theme. Usaremos uma única paleta de cores personalizada para definir as cores a serem usadas em todos os temas:

// COMMON
$purple: #9E379F;
$blue: #61AEDB;
$light-gray: #efefef;

$custom-palette: palette(
  $primary: $blue, 
  $secondary: $purple, 
  $surface: $light-gray
);

$today-text: color($custom-palette, "primary", 500);
$text-color: color($custom-palette, "secondary", 200);
$color-focused: color($custom-palette, "secondary", 500);

// DATE-RANGE
$custom-date-range-theme: date-range-picker-theme(
  $label-color: $color-focused
);

// INPUT GROUP
$custom-input-group-theme: input-group-theme(
  $filled-text-color: $text-color,
  $idle-text-color: $text-color,
  $focused-text-color: $color-focused,
  $idle-bottom-line-color: $purple,
  $hover-bottom-line-color: $color-focused,
  $interim-bottom-line-color: $color-focused
);

// CALENDAR
$custom-calendar-theme: calendar-theme(
  $date-current-foreground: $today-text,
  $border-radius: 0.5,
  $date-border-radius: 0.5
);

O último passo é passar os temas personalizados:

@include css-vars($custom-date-range-theme);
@include css-vars($custom-input-group-theme);
@include css-vars($custom-calendar-theme);

Warning

Se o componente estiver usando um Emulated ViewEncapsulation, é necessário penetrate neste encapsulamento usando::ng-deep

:host {
  ::ng-deep {
    @include date-range-picker($custom-date-range-theme);
    @include input-group($custom-input-group-theme);
    @include calendar($custom-calendar-theme);
  }
}

Scoping Styles

Em relação ao escopo de estilo, você deve consultar as seções de estilo [Estilos de componentes com escopo de sobreposição](overlay-styling.md#Estilos de sobreposição com escopo) e Estilos de escopo de grupo de entrada, pois elas fornecem mais informações.

Application Demo

A demonstração abaixo define um formulário para passagens aéreas que usa o IgxDateRangePickerComponent. Se nenhuma data for selecionada, um IgxHint é usado para exibir um erro de validação. A seleção das datas é restrita pelas propriedades minValue e maxValue do IgxDateRangePickerComponent

Visão geral do componente Angular Date Range Picker

Angular Date Range Picker Example

Getting Started with Ignite UI for Angular Date Range Picker

Using the Angular Date Range Picker Component

Display and Value

Note

Display Separate Editable Inputs

Keyboard Navigation

Layout

Projecting components

Alternar e limpar ícones

Custom And Predefined Date Ranges

Formatting

Note

Forms and Validation

Min and max values

Disabled And Special dates

Templating

Calendar specific settings

Estilização

Warning

Scoping Styles

Application Demo

API References

Theming Dependencies

Additional Resources

Temas

Visão geral do componente Angular Date Range Picker

Angular Date Range Picker Example

Getting Started with Ignite UI for Angular Date Range Picker

Using the Angular Date Range Picker Component

Display and Value

Note

Display Separate Editable Inputs

Popup modes

Keyboard Navigation

Layout

Projecting components

Alternar e limpar ícones

Custom And Predefined Date Ranges

Formatting

Note

Forms and Validation

Min and max values

Disabled And Special dates

Templating

Calendar specific settings

Estilização

Warning

Scoping Styles

Application Demo

API References

Theming Dependencies

Additional Resources

Temas