Visão geral do componente Angular Calendar

    Angular Calendar é um componente de UI usado para exibir datas e dias em um aplicativo. Suportando diferentes recursos, ele permite que os usuários gerenciem facilmente funcionalidades de calendário, arrastem e criem eventos em um calendário, naveguem até uma data preferida nele e mostrem eventos em uma visualização mensal, semanal ou diária do calendário Angular com um único clique.

    O componente Ignite UI for Angular Calendar, desenvolvido como um componente nativo Angular, fornece maneiras fáceis e intuitivas de exibir informações de data, habilitar datas ou aplicar o modo de desabilitação de datas do calendário Angular. Os usuários podem escolher entre três modos de seleção diferentes - seleção única, seleção múltipla ou seleção de intervalo.

    Angular Calendar Example

    Criamos o seguinte exemplo de Angular Calendar usando o pacote Ignite UI for Angular Calendar. Ele mostra rapidamente como um calendário básico se parece e se comporta, como os usuários podem escolher e destacar uma única data e como ir e voltar para uma data específica.

    Getting Started with Ignite UI for Angular Calendar

    Para começar a usar o componente Ignite UI for Angular Calendar, 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 IgxCalendarModule no seu arquivo app.module.ts.

    Note

    O IgxCalendarComponent também depende do BrowserAnimationsModule e, opcionalmente, do HammerModule para interações por toque, então eles precisam ser adicionados ao AppModule também:

    // app.module.ts
...
import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IgxCalendarModule } from 'igniteui-angular';
// import { IgxCalendarModule } from '@infragistics/igniteui-angular'; for licensed package

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

    Como alternativa, a partir da 16.0.0, você pode importar o IgxCalendarComponent como uma dependência autônoma ou usar o token IGX_CALENDAR_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_CALENDAR_DIRECTIVES } from 'igniteui-angular';
// import { IGX_CALENDAR_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-calendar></igx-calendar>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [BrowserAnimationsModule, HammerModule, IGX_CALENDAR_DIRECTIVES]
    /* or imports: [BrowserAnimationsModule, HammerModule, IgxCalendarComponent] */
})
export class HomeComponent {}

    Agora que você importou o módulo ou as diretivas do Ignite UI for Angular Calendar, você pode começar a usar o componente igx-calendar.

    Note

    O IgxCalendarComponent usa a Intl Web API para localização e formatação de datas. Considere usar polyfills apropriados se sua plataforma de destino não os suportar.

    Using the Angular Calendar

    Angular Single Selection Calendar

    Instanciar o IgxCalendarComponent é tão fácil quanto colocar seu elemento seletor no template. Isso exibirá o mês atual no modo de calendário de seleção única.

    <!-- app.component.html -->
<!-- Single selection mode -->
<igx-calendar></igx-calendar>

    Angular Calendar Multiselect

    Podemos facilmente alterar o modo padrão usando a propriedade selection:

    <!-- app.component.html -->
<!-- Multi selection mode -->
<igx-calendar selection="multi" [showWeekNumbers]="true"></igx-calendar>

    Angular Calendar Range Picker

    Seguindo a mesma abordagem, podemos alternar para o modo de seleção de intervalo:

    <!-- app.component.html -->
<!-- Range selection mode -->
<igx-calendar selection="range"></igx-calendar>

    Note

    Observe que o cabeçalho do calendário não é renderizado quando a seleção é multi ou range.

    Localization and Formatting

    Devido à sua própria natureza, localização e formatação são essenciais para qualquer calendário. No IgxCalendarComponent, elas são controladas e personalizadas por meio das seguintes propriedades -locale, formatOptions, formatViews, weekStart.

    Vamos em frente e tentar isso junto com outras personalizações da IgxCalendarComponent API. A primeira coisa que precisamos definir é o weekStart, que controla o dia inicial da semana. O padrão é 0, que corresponde a domingo, então definiremos um valor de 1 para segunda-feira. Na marcação abaixo, também estamos vinculando as propriedades formatOptions e formatViews para personalizar a formatação de exibição. Por fim, estamos vinculando a propriedade locale a um valor, com base na escolha de localização do usuário:

    <!-- app.component.html -->
<igx-select #select [(ngModel)]="locale">
    <igx-select-item *ngFor="let locale of locales" [value]="locale">
        {{ locale }}
    </igx-select-item>
</igx-select>

<igx-calendar #calendar
    [weekStart]="1"
    [locale]="locale"
    [formatOptions]="formatOptions"
    [formatViews]="formatViews">
</igx-calendar>

    Todos os valores de propriedade devem ser definidos no arquivo AppComponent:

    // app.component.ts
@ViewChild('calendar', { read: IgxCalendarComponent }) public calendar: IgxCalendarComponent;

public formatOptions: any;
public formatViews: any;
public locales = ['EN', 'DE', 'FR', 'AR', 'ZH'];
public locale = 'EN';

public ngOnInit() {
    this.formatOptions = { day: '2-digit', month: 'long', weekday: 'long', year: 'numeric' };
    this.formatViews = { day: true, month: true, year: true };
}

    Se tudo correu bem, agora devemos ter um calendário com exibição de datas personalizadas, que também altera a representação de localidade, com base na localização do usuário. Vamos dar uma olhada:

    How to Disable Dates In Angular Calendar

    Esta seção demonstra o uso da funcionalidade disabledDates. Para esse propósito, diferentes datas ou intervalos únicos podem ser adicionados a um array e então passados para o descritor disabledDates.

    O DateRangeType é usado para especificar um intervalo que será desabilitado.

    Vamos criar um exemplo que desabilita as datas entre os dias 3 e 8 do mês atual:

    export class CalendarSample6Component {
    @ViewChild('calendar') public calendar: IgxCalendarComponent;
    public today = new Date(Date.now());
    public range = [
        new Date(this.today.getFullYear(), this.today.getMonth(), 3),
        new Date(this.today.getFullYear(), this.today.getMonth(), 8)
    ];

    public ngOnInit() {
        this.calendar.disabledDates = [{ type: DateRangeType.Between, dateRange: this.range }];
    }
}

    Essas configurações devem ter o seguinte resultado:

    Special dates

    O recurso specialDates está usando quase os mesmos princípios de configuração que o disabledDates. A capacidade de selecionar e focar specialDates é o que os diferencia dos disabled.

    Vamos adicionar algumas specialDates ao nosso igxCalendar. Para fazer isso, temos que criar um item DateRangeDescriptor do tipo DateRangeType.Specific e passar um array de datas como um dateRange:

    export class CalendarSample7Component {
    @ViewChild('calendar', { static: true })
    public calendar: IgxCalendarComponent;
    @ViewChild('alert', { static: true })
    public dialog: IgxDialogComponent;
    public range = [];

    public selectPTOdays(dates: Date[]) {
        this.range = dates;
    }

    public submitPTOdays(eventArgs) {
        this.calendar.specialDates =
            [{ type: DateRangeType.Specific, dateRange: this.range }];

        this.range.forEach((item) => {
            this.calendar.selectDate(item);
        });

        ...
    }
}

    <igx-calendar #calendar weekStart="1"
    selection="multi"
    (selected)="selectPTOdays($event)">
</igx-calendar>
<igx-dialog #alert title="Request Time Off"
    leftButtonLabel="OK"
    (leftButtonSelect)="alert.close()">
</igx-dialog>
<button igxButton="contained" (click)="submitPTOdays($event)">Submit Request</button>

    A demonstração a seguir ilustra um calendário com uma opção de solicitação de férias:

    Week numbers

    Agora você pode usar a entrada showWeekNumbers para mostrar os números da semana para os componentes Calendar e DatePicker.

    
<!-- app.component.html -->
<igx-calendar selection="multi" [showWeekNumbers]="true"></igx-calendar>

    A demonstração a seguir ilustra um calendário com números de semana habilitados:

    Calendar Events

    Vamos explorar os eventos emitidos pelo calendário:

    • selected- emitido ao selecionar data(s) no calendário.
    • viewDateChanged- emitido sempre que o mês/ano apresentado é alterado - por exemplo, após navegar para o mês next ou previous.
    • activeViewChanged- emitido após a visualização ativa ser alterada - por exemplo, após o usuário clicar na seção de month ou year no cabeçalho.
    <!-- app.component.html -->
<igx-calendar #calendar
    (selected)="onSelection($event)"
    (viewDateChanged)="viewDateChanged($event)"
    (activeViewChanged)="activeViewChanged($event)">
</igx-calendar>

    O evento selected é adequado para construir lógica de validação de entrada. Use o código abaixo para alertar o usuário se a seleção exceder 5 dias e, em seguida, redefina a seleção:

    // app.component.ts
...
public onSelection(dates: Date[]) {
    if (dates.length > 5) {
        this.calendar.selectedDates = [];
        // alert the user
    }
}
public viewDateChanged(event: IViewDateChangeEventArgs) {
    // use event.previousValue to get previous month/year that was presented.
    // use event.currentValue to get current month/year that is presented.
}

public activeViewChanged(event: CalendarView) {
    // use CalendarView[event] to get the current active view (DEFAULT, YEAR or DECADE)
}

    Use a demonstração abaixo para brincar (alterar seleção, navegar por meses e anos) e ver os eventos registrados em tempo real:

    Angular Calendar Views

    Há visualizações separadas fornecidas pelo IgxCalendarModule que podem ser usadas independentemente:

    Navegação pelo teclado

    Se você navegar pela página usando a tecla Tab, lembre-se de que, com base nas recomendações de acessibilidade do W3, o igxCalendarComponent agora apresenta as seguintes paradas de tabulação:

    • Botão do mês anterior
    • Botão de seleção de mês
    • Botão de seleção de ano
    • Botão do próximo mês
    • Data selecionada, Data atual, Primeira data focalizável (não desabilitada) na visualização de dias

    Em um Angular Calendar que contém mais de uma data selecionada, apenas a primeira data será introduzida como uma parada de tabulação. Por exemplo, quando uma seleção múltipla Angular Calendar está habilitada e você selecionou as datas: 13/10/2020, 17/10/2020 e 21/10/2020, apenas 13/10/2020 estará acessível durante a navegação por tabulação; em um Angular Calendar Range Picker, apenas a primeira data do intervalo selecionado fará parte da sequência de tabulação da página.

    Note

    Mudança comportamental, a partir da v10.2.0- A navegação por tecla Tab na visualização de dias não está mais disponível. Para navegar entre as datas na visualização de data, você deve usar as teclas de seta.

    Quando o componente igxCalendar estiver focado, use:

    • Tecla PageUp para mover para o mês anterior,
    • Tecla PageDown para mover para o próximo mês,
    • Teclas Shift + PageUp para ir para o ano anterior,
    • Teclas Shift + PageDown para avançar para o próximo ano,
    • Tecla Home para focar o primeiro dia do mês atual ou o primeiro mês em exibição
    • Tecla End para focar o último dia do mês atual ou o último mês em exibição

    Quando os botões do mês prev ou do next mês (no subtítulo) estiverem em foco, use:

    • Pressione a tecla Espaço ou Enter para rolar e visualizar o mês seguinte ou anterior.

    Quando o botão months (no subtítulo) estiver em destaque, use:

    • Tecla de espaço ou Enter para abrir a visualização de meses.

    Quando o botão year (no subtítulo) estiver em foco, use:

    • Tecla de espaço ou Enter para abrir a visualização de décadas.

    Quando um day dentro do mês atual é focado:

    • Use as teclas de seta para navegar pelos dias. Nota: As datas desabilitadas serão puladas.
    • O foco será mantido no mês atual que está na visualização, enquanto a navegação vai de / para o último dia / primeiro dia do mês.
    • A navegação na base de dados seria contínua, o que significa que ela percorrerá todos os meses enquanto navega com as setas.
    • Use a tecla Enter para selecionar o dia em foco no momento.

    Quando um month dentro da visualização de meses estiver em foco, use:

    • Teclas de seta para navegar pelos meses.
    • Tecla Home para focar o primeiro mês dentro da visualização de meses.
    • Tecla End para focar o último mês dentro da visualização de meses.
    • Pressione a tecla Enter para selecionar o mês em foco no momento e fechar a visualização.

    Quando um year dentro da visualização da década estiver focado, use:

    • Teclas de seta para cima e seta para baixo para navegar pelos anos,
    • Pressione a tecla Enter para selecionar o ano em foco no momento e fechar a visualização.
    Note

    Após a versão 8.2.0, a navegação pelo teclado não focará os dias fora do mês atual, mas mudará o mês em exibição.

    Multi View Calendar

    O calendário multivisualização suporta todos os três tipos de seleção. Use a entrada monthsViewNumber para definir o número de meses exibidos, que serão mostrados horizontalmente em um contêiner flexível. Não há limite para o valor máximo definido. Ao usar um calendário multivisualização, você pode querer ocultar os dias que não pertencem ao mês atual. Você pode fazer isso com a propriedade hideOutsideDays. A navegação pelo teclado move para os meses seguintes/anteriores quando eles estão em exibição.

    Calendar Orientation

    As configurações de orientação permitem que os usuários escolham como o cabeçalho e a visualização do calendário são exibidos.

    Opções de orientação do cabeçalho:

    Você pode alterar a orientação do cabeçalho para colocar o cabeçalho do calendário na horizontal (acima da visualização do calendário) ou na vertical (na lateral da visualização do calendário). Para fazer isso, use a propriedade [headerOrientation], definindo-a respectivamente como horizontal ou vertical

    Opções de orientação da visualização:

    Você pode definir a orientação da visualização para colocar os meses no calendário horizontalmente (lado a lado) ou verticalmente (um acima do outro). Para fazer isso, use a propriedade [orientation], definindo-a respectivamente como horizontal ou vertical.

    Note

    Você precisa de pelo menos dois meses de calendário para ver a propriedade funcionando.

    <igx-calendar [monthsViewNumber]="2" [headerOrientation]="headerOrientation" [orientation]="orientation"></igx-calendar>

    const orientations = ["horizontal", "vertical"] as const;
type Orientation = (typeof orientations)[number];

export class CalendarSample9Component {
    protected orientations = Array.from(orientations, (o) => o);
    protected headerOrientation: Orientation = "horizontal";
    protected orientation: Orientation = "horizontal";

    protected setHeaderOrientation(orientation: Orientation) {
        this.headerOrientation = orientation;
    }

    protected setOrientation(orientation: Orientation) {
        this.orientation = orientation;
    }
}

    Estilização

    Para começar a estilizar o calendário, 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';

    Seguindo a abordagem mais simples, criamos um novo tema que estende o calendar-theme e aceita alguns dos parâmetros do tema padrão.

    $custom-calendar-theme: calendar-theme(
  $header-background: #345779,
  $content-background: #fdfdfd,
  $header-foreground: #ffffff,
  $date-current-foreground: #2dabe8,
  $navigation-color: #2dabe8,
  $date-selected-foreground: #fdfdfd,
  $date-current-background: #fdfdfd,
  $navigation-hover-color: #345779,
  $ym-current-foreground: #2dabe8,
  $ym-hover-foreground: #2dabe8,
  $picker-foreground: #2dabe8,
  $picker-hover-foreground: #345779,
);

    O último passo é passar o tema do calendário personalizado:

     @include css-vars($custom-calendar-theme);

    API References

    Additional Resources

    Nossa comunidade é ativa e sempre acolhedora para novas ideias.