Web Components Calendar Overview
The Ignite UI for Web Components Calendar component is lightweight and easy to configure. It is used for showing dates and weekdays. It is also the best way for providing monthly or yearly views to end-users. The Ignite UI for Web Components Calendar control lets you restrict the minimum and maximum date ranges that people can navigate through.
The Ignite UI for Ignite UI for Web Components Calendar provides an easy and intuitive way for displaying date information. It packs different features like single or multiple date selection modes, highlight and select date range, keyboard navigation, enabling week numbers, size and spacing options, and more.
Web Components Calendar Example
The following Web Components IgcCalendarComponent
component example shows a basic calendar with a single day selection mode. See how it works or inspect the code behind.
How To Create a Calendar in Web Components with Ignite UI
Primeiro, você precisa instalar o Ignite UI for Web Components executando o seguinte comando:
npm install igniteui-webcomponents
import { defineComponents, IgcCalendarComponent } from 'igniteui-webcomponents';
defineComponents(IgcCalendarComponent);
Para uma introdução completa ao Ignite UI for Web Components, leia o tópico Introdução.
The simplest way to start using the Ignite UI for Web Components IgcCalendarComponent
is as follows:
<igc-calendar></igc-calendar>
Selection Modes
Users can choose from three different selection modes - single selection, multiple selection or range selection. By default, the Ignite UI for Web Components IgcCalendarComponent
is using single selection mode but you can change it by setting the selection
property as shown in this example.
<igc-calendar selection="multiple"></igc-calendar>
Range Selection
Following the same approach, we can switch selection
to range mode:
<!-- Range selection mode -->
<igc-calendar selection="range"></igc-calendar>
Active View and Date
The Ignite UI for Web Components Calendar component allows you to switch between three different views: days, months and years. The activeView
property of the component reflects the current view. By default, the Calendar displays the current date when loaded initially. You could modify this by setting the activeDate
property. The activeDate
property also reflects the changes of the currently visible date made by the end user.
Header Options
By default, the Ignite UI for Web Components Calendar component renders a header area which contains information about the selected dates. You could hide the header by setting the HasHeader
property to false. You could also configure vertical
or horizontal
orientation of the header using the headerOrientation
property.
[!Note] Please note that the Ignite UI for Web Components Calendar header is not rendered when the
selection
is set to multiple.
[!Note] Please note that the Ignite UI for Web Components Calendar DOM properties use
camelCase
naming while their corresponding HTML attributes are usingkebab-case
. For example theheaderOrientation
property corresponds to theheader-orientation
attribute.
The Ignite UI for Web Components Calendar component exposes a title
slot which allows you to customize the title of the header.
<igc-calendar selection="range" header-orientation="vertical">
<span slot="title">Trip dates</span>
</igc-calendar>
O exemplo a seguir demonstra a configuração acima:
Localization and Formatting
Due to their very nature, localization and formatting are essential to any calendar. In the Ignite UI for Web Components IgcCalendarComponent
those are controlled and customized through the following properties - locale
, formatOptions
, weekStart
.
Let's go ahead and try those along with other customizations. First thing we need to set is the weekStart
, which controls the starting day of the week. It defaults to Sunday
, so we will set it to Monday
. We will also customize the formatOptions
property which specifies the options used to format the months and the weekdays in the Calendar views. Finally, we will set the locale
property to a value, based on the user's location choice:
<igc-radio-group alignment="horizontal">
<igc-radio name="locale" value="en" checked>EN</igc-radio>
<igc-radio name="locale" value="de">DE</igc-radio>
<igc-radio name="locale" value="fr">FR</igc-radio>
<igc-radio name="locale" value="ar">AR</igc-radio>
<igc-radio name="locale" value="ja">JA</igc-radio>
</igc-radio-group>
<igc-calendar
id="calendar1"
week-start="monday"
>
</igc-calendar>
this.calendar = document.getElementById('calendar1') as IgcCalendarComponent;
this.calendar.formatOptions = {
month: 'short',
weekday: 'short'
};
this.radios = document.querySelectorAll('igc-radio') as NodeListOf<IgcRadioComponent>;
this.radios.forEach(radio => {
radio.addEventListener('igcChange', () => {
if (radio.checked) {
this.calendar.locale = radio.value;
}
});
})
If everything went well, we should now have a Calendar with customized display, that also changes the locale representation, based on the user selection. Let's have a look at it:
Disabled dates
In some cases you would want to have disabled dates in the Calendar which can't be selected by the end user. This functionality is achieved by using the disabledDates
property. The disabledDates
property is an array of DateRangeDescriptor
objects. Each descriptor has a Type
and optionally a dateRange
which is an array of Date
objects.
These are the available options for the Type
property:
After
- disables the dates after the first date in thedateRange
Before
- disables the dates before the first date in thedateRange
Between
- disables the dates between the first and the second date in thedateRange
Specific
- disables the dates specified in thedateRange
arrayWeekdays
- disables all weekdaysWeekends
- disables all weekends
Vamos criar um exemplo que desabilita as datas entre os dias 3 e 8 do mês atual:
const today = new Date(Date.now());
const range = [
new Date(today.getFullYear(), today.getMonth(), 3),
new Date(today.getFullYear(), today.getMonth(), 8)
];
this.calendar.disabledDates = [{ type: DateRangeType.Between, dateRange: range }];
Essas configurações devem ter o seguinte resultado:
Special dates
The specialDates
property is using almost the same configuration principles as the disabledDates
. The special dates have a highlighted look and feel and unlike the disabled ones can be selected.
Let's add some special dates to our Calendar. In order to do this, we will create a DateRangeDescriptor
and pass the dates between the 3rd and the 8th of the current month:
const today = new Date();
const range = [
new Date(today.getFullYear(), today.getMonth(), 3),
new Date(today.getFullYear(), today.getMonth(), 8)
];
this.calendar.specialDates = [{ type: DateRangeType.Between, dateRange: range }];
The following demo illustrates a Calendar with a vacation request option:
Week numbers
You can use the showWeekNumbers
property to show the week numbers of the Calendar component. You can do this by using its corresponding boolean attribute show-week-numbers
like this:
<igc-calendar show-week-numbers></igc-calendar>
A demonstração a seguir ilustra um calendário com números de semana habilitados:
Multiple Months
Using the visibleMonths
property, you can display more than one month when the Calendar is in days
view. When multiple months are displayed, you can configure whether you want to stack them vertically or horizontally by using the orientation
property. By default, the orientation
property is set to horizontal
.
The Calendar displays leading and trailing dates from the previous and the next months. You could hide these dates by setting the hideOutsideDays
property to true or using its corresponding boolean attribute hideOutsideDays
.
<igc-calendar visible-months="2" hide-outside-days></igc-calendar>
O exemplo a seguir demonstra a configuração de vários meses:
Tamanho
Você pode controlar o tamanho e o espaçamento dos elementos internos do calendário usando a variável CSS--ig-size
. O tamanho padrão do componente é grande.
Eventos
O componente Calendar emite o evento Change
quando as datas selecionadas são alteradas pelo usuário final. Você pode assinar o evento assim:
this.calendar.addEventListener('igcChange', ev => console.log(ev.detail));
Navegação pelo teclado
If you traverse the page using the Tab key you should keep in mind that based on W3 accessability recommendations the IgcCalendarComponent
introduces the following tab stops:
- Botão de seleção de mês
- Botão de seleção de ano
- Botão anterior
- Botão Avançar
- Elemento de data ativo
When a day/month/year in the IgcCalendarComponent
component is focused, use:
- Tecla PageUp para mover para a página do mês/ano/anos anterior.
- Tecla PageDown para mover para a próxima página do mês/ano/anos.
- Tecla Home para focar o primeiro dia do mês atual/primeiro mês em exibição/primeiro ano em exibição.
- Tecla End para focar o último dia do mês atual/último mês em exibição/último ano em exibição.
- Teclas de seta para navegar pelos dias/meses/anos. Navegar antes do primeiro item e depois do último item alternará a visualização para a página do mês/ano/anos seguinte/anterior.
Quando um dia dentro da visualização days
estiver focado, use:
- Teclas Shift + PageUp para ir para o ano anterior.
- Teclas Shift + PageDown para avançar para o próximo ano.
- Pressione a tecla Espaço ou Enter para selecionar o dia em foco no momento.
Quando um mês dentro da visualização months
estiver em foco, use:
- Space or Enter key to change the
activeDate
to the currently focused month and switch todays
view.
Quando um ano dentro da visualização years
estiver focado, use:
- Space or Enter key to change the
activeDate
to the currently focused year and switch tomonths
view.
Quando os botões anterior ou seguinte (no subtítulo) estiverem em foco, use:
- Tecla de espaço ou Enter para alternar para a página do mês/ano/anos anterior/seguinte.
Quando o botão do mês (no subtítulo) estiver em destaque, use:
- Pressione a tecla Espaço ou Enter para alternar para a visualização
months
.
Quando o botão do ano (no subtítulo) estiver em foco, use:
- Pressione a tecla Espaço ou Enter para alternar para a visualização
years
.
Styling
The IgcCalendarComponent
component exposes CSS parts for almost all of its inner elements. The following table lists all of the exposed CSS parts:
Nome | Descrição |
---|---|
header |
O elemento de cabeçalho. |
header-title |
O elemento de título do cabeçalho. |
header-date |
O elemento de data do cabeçalho. |
content |
O elemento de conteúdo que contém as visualizações e os elementos de navegação. |
navigation |
O elemento do contêiner de navegação. |
months-navigation |
O elemento do botão de navegação dos meses. |
years-navigation |
O elemento do botão de navegação de anos. |
years-range |
O elemento de intervalo de anos. |
navigation-buttons |
O contêiner de botões de navegação. |
navigation-button |
Botão de navegação anterior/próximo. |
days-view-container |
O elemento contêiner de visualização de dias. |
days-view |
Elemento de visualização de dias. |
months-view |
O elemento de visualização de meses. |
years-view |
O elemento de visualização de anos. |
days-row |
Elemento da linha Days. |
label |
Elemento de rótulo do cabeçalho da semana. |
week-number |
Elemento do número da semana. |
week-number-inner |
Elemento interno do número da semana. |
date |
Elemento de data. |
date-inner |
Elemento interno de data. |
first |
O primeiro elemento de data selecionado. |
last |
O último elemento de data selecionado. |
inactive |
Elemento de data inativo. |
hidden |
Elemento de data oculto. |
weekend |
Elemento de data de fim de semana. |
range |
Intervalo do elemento selecionado. |
special |
Elemento de data especial. |
disabled |
Elemento de data desabilitado. |
single |
Elemento de data selecionado individualmente. |
preview |
Elemento de data de pré-visualização da seleção de intervalo. |
month |
Elemento mês. |
month-inner |
Elemento interno do mês. |
year |
Elemento ano. |
year-inner |
Ano elemento interno. |
selected |
Indica o estado selecionado. Aplica-se a elementos de data, mês e ano. |
current |
Indica o estado atual. Aplica-se a elementos de data, mês e ano. |
Using these CSS parts we can customize thе appearance of the IgcCalendarComponent
component like this:
igc-calendar::part(date-inner selected),
igc-calendar::part(month-inner selected),
igc-calendar::part(year-inner selected),
igc-calendar::part(month-inner selected):focus,
igc-calendar::part(year-inner selected):focus {
background: var(--ig-primary-500);
border-color: var(--ig-primary-800);
}
igc-calendar::part(date-inner selected):hover,
igc-calendar::part(month-inner selected):hover,
igc-calendar::part(year-inner selected):hover {
background: var(--ig-primary-500);
border-color: var(--ig-primary-800);
}
igc-calendar::part(label),
igc-calendar::part(navigation-button),
igc-calendar::part(months-navigation):hover,
igc-calendar::part(months-navigation):focus,
igc-calendar::part(years-navigation):hover,
igc-calendar::part(years-navigation):focus {
color: var(--ig-primary-300);
}
igc-calendar::part(navigation-button):hover,
igc-calendar::part(navigation-button):focus {
color: var(--ig-primary-800);
}
O exemplo a seguir demonstra a configuração CSS acima:
API References
IgcCalendarComponent
IgcRadioComponent
IgcRadioGroupComponent
activeDate
activeView
DateRangeDescriptor
dateRange
Styling & Themes