Visão geral do componente Angular Date Range Picker

Angular Date Range Picker é um componente leve que inclui entrada de texto e um pop-up de calendário para permitir que os usuários selecionem facilmente os valores de data de início e término. Ele pode ser personalizado para corresponder aos requisitos do aplicativo com recursos como restrições de intervalo, formatos, seleção de intervalo de dados, agrupamento dos valores de início e término e muito mais. O Date Range Picker no Angular também permite que os desenvolvedores alterem a propriedade de exibição padrão e a definam como mês, ano ou multianual.

Angular Date Range Picker Example

Criamos este exemplo básico Angular Date Range Picker para mostrar o componente em ação. Neste caso, você vê um pop-up de calendário, permitindo que os usuários selecionem valores de data inicial e final.

Getting Started with Ignite UI for Angular Date Range Picker

Para começar a usar o componente Ignite UI for Angular Datepicker, 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 IgxDateRangePicker usa o IgxCalendarComponent, ele também tem uma dependência do BrowserAnimationsModule e, opcionalmente, do HammerModule para interações de toque, então eles precisam ser adicionados ao AppModule também:

// 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 da 16.0.0 você pode importar o IgxDateRangePickerComponent como uma dependência autônoma ou usar o token IGX_DATE_RANGE_PICKER_DIRECTIVES 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 Date Range Picker

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.

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

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

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.

Além disso, a Ignite UI for Angular Date Range Picker pode ser configurada para projetar IgxPickerToggleComponent- um componente que controla a alternância do calendário e pode ser modificado conforme mostrado na seção Alternar calendário.

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

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.

User Experience

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 data de início e término, o calendário só pode ser aberto a partir do ícone do calendário, já que ambas as entradas são editáveis por padrão.

Quando o calendário estiver visível, um intervalo pode ser selecionado escolhendo as datas de início e término. Selecionar uma data definirá a data de início e término, até que uma segunda data seja escolhida. Se houver um intervalo selecionado, clicar em qualquer outra data do calendário iniciará uma nova seleção de intervalo.

As datas de início e término são separadas por um hífen quando mostradas na entrada somente leitura do componente. Ao definir entradas diferentes para início e fim, elas são separadas pela preposição to. Esta última pode ser localizada ou substituída por meio de um modelo. Veja o exemplo de modelo abaixo para mais detalhes.

Examples

Label

Para definir o rótulo do seletor de intervalo de datas, a diretiva igxLabel deve ser usada conforme mostrado no snippet abaixo:

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

Calendar toggle

Na configuração padrão, com uma única entrada somente leitura, um ícone de calendário padrão é mostrado como um prefixo. O ícone de calendário pode ser alterado ou redefinido usando o componente IgxPickerToggleComponent. Ele pode ser decorado com igxPrefix ou igxSuffix, que definirão sua posição - no início da entrada ou no final, respectivamente. Para alterar a posição padrão e mostrar o ícone como um sufixo, você precisa fazer o seguinte:

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

Quando um Date Range Picker tem duas entradas separadas, para datas de início e término, ele não expõe um ícone de calendário por padrão. O IgxPickerToggleComponent deve ser adicionado manualmente como um filho 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-date-range-start>
    <igx-date-range-end>
        ...
    </igx-date-range-end>
</igx-date-range-picker>

Dialog mode

O componente IgxDateRangePickerComponent tem dois modos - dropdown (padrão) e dialog. Para alternar para o modo dialog, faça o seguinte:

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

O valor do intervalo é definido quando as datas são selecionadas do calendário. Você notará que no modo suspenso, o botão Done não está disponível.

Custom Action Buttons

Os botões de ação do Date Range Picker podem ser modelados usando a diretiva igxPickerActions. Um cenário comum é permitir que o usuário selecione entre intervalos predefinidos, como na demonstração a seguir:

Keyboard Navigation

Note

Use as demonstrações do modo de diálogo e Exibir entradas editáveis separadas para testar as combinações de teclado definidas abaixo.

Abrir e fechar a interface do usuário do calendário IgxDateRangePickerComponent com o teclado está disponível apenas no modo dropdown e pode ser acionado por meio das combinações de teclas abaixo:

• Alt + Seta para baixo- Abre o menu suspenso que contém a IU do calendário e o focaliza
• Alt + Seta para cima- Fecha o menu suspenso e focaliza o campo de entrada (campo de entrada de início de intervalo quando duas entradas separadas são usadas)
• Esc- Fecha o menu suspenso e focaliza o campo de entrada (campo de entrada de início de intervalo quando duas entradas separadas são usadas)

A navegação pelo teclado dentro da UI do calendário do Date Range Picker está disponível em todos os modos e configurações. Quando o calendário é aberto, ele assume o foco e as seguintes combinações de teclado podem ser usadas:

• Insira as datas de início e término selecionadas
• PageUp, PageDown, Shift + PageUp, Shift + PageDown, Home, End, Tab- navegue pelo calendário

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.

Quando duas entradas separadas são usadas, a navegação pelo teclado para a diretiva igxDateTimeEditor também é aplicável ao componente Date Range Picker:

• Ctrl / Cmd + Seta para a esquerda / direita- navega entre as seções de data. Em Ctrl / Cmd + Direita, ele vai para o fim da seção. Se já estiver lá, ele vai para o fim da próxima seção. Funciona da mesma forma na direção oposta.
• Seta para cima / baixo- incrementa/diminui partes da data.
• Ctrl / Cmd +;- define o dia e a hora atuais no editor.

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 Date Range Picker suporta todas as diretivas do núcleo FormsModule, NgModel e ReactiveFormsModule (FormControl, FormGroup, etc.). Isso também inclui as funções Forms Validators. Além disso, os valores min e max do componente 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>

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>

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

API References

• Componente IgxDateRangePicker
• Componente IgxCalendar
• Estilos de IgxCalendarComponent
• Estilos IgxOverlay
• Componente do grupo de entrada Igx

Theming Dependencies

• Tema IgxCalendar
• Tema IgxOverlay
• Tema IgxIcon
• Tema IgxButton
• Tema IgxInputGroup
• Tema IgxDropDown

Additional Resources

Tópicos relacionados:

• Editor de data e hora
• Rótulo & Entrada
• Integração de Formulários Reativos
• Seletor de data

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

• Ignite UI for Angular Fóruns
• Ignite UI for Angular GitHub