Angular Calendar (カレンダー) コンポーネントの概要

Angular Calendar は、アプリで日付と曜日を表示するために使用される UI コンポーネントです。さまざまな機能をサポートしているため、ユーザーは簡単にカレンダー機能を管理したり、カレンダーにイベントをドラッグして作成したり、希望の日付に移動したり、Angular カレンダーの月表示、週表示、または日表示でイベントをシングル クリックで表示したりできます。

Angular Calendar の例

Ignite UI for Angular Calendar パッケージを使用して、次の Angular Calendar の例を作成しました。基本的なカレンダーがどのように見えるか、ユーザーが 1 つの日付を選択して強調表示する方法、特定の日付に前後に移動する方法を簡単に示します。

Ignite UI for Angular Calendar を使用した作業の開始

Ignite UI for Angular Calendar コンポーネントを使用した作業を開始するには、Ignite UI for Angular をインストールする必要があります。既存の Angular アプリケーションで、以下のコマンドを入力します。

ng add igniteui-angular

Ignite UI for Angular については、「はじめに」トピックをご覧ください。

次に、app.module.ts ファイルに IgxCalendarModule をインポートします。

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

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

あるいは、16.0.0 以降、IgxCalendarComponent をスタンドアロンの依存関係としてインポートすることも、IGX_CALENDAR_DIRECTIVES トークンを使用してコンポーネントとそのすべてのサポート コンポーネントおよびディレクティブをインポートすることもできます。

// home.component.ts

import { HammerModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { IGX_CALENDAR_DIRECTIVES } from 'igniteui-angular/calendar';
// 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 {}

Ignite UI for Angular Calendar モジュールまたはディレクティブをインポートしたので、igx-calendar コンポーネントの使用を開始できます。

対象プラットフォームがその API をサポートしない場合、適切なポリフィルを使用してください。

Angular Calendar の使用

Angular 単一選択カレンダー

IgxCalendarComponent をインスタンス化するには、セレクター要素をテンプレートに追加します。単一選択カレンダー モードで現在の月を表示します。

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

Angular 複数選択カレンダー

selection プロパティを使用してデフォルトのモードを簡単に変更できます。

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

Angular Calendar 範囲ピッカー

同じ方法に従って、範囲選択モードに切り替えることができます。

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

ローカライズおよび書式設定

カレンダーにおいてローカライズおよび書式設定はとても重要な要素です。IgxCalendarComponent でこれらは以下のプロパティによって制御およびカスタマイズします - locale、formatOptions、formatViews、weekStart。

これらの設定に加え、IgxCalendarComponent API のその他のカスタマイズ機能も使用できます。最初に週の開始日を制御する weekStart を設定します。デフォルト値が 0 (日曜日) であるため、値を 1 (月曜日) に設定します。以下のマークアップで表示書式設定をカスタマイズするために、formatOptions および formatViews プロパティもバインドしています。最後に、locale プロパティをユーザーの選択した場所に基づいて値にバインドします。

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

すべてのプロパティ値が 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 };
}

すべて適切に設定できると、カスタマイズされた日付を持つカレンダーが表示され、ユーザーの場所に基づいてロケール表現が変更されます。以下は結果です。

Angular Calendar で日付を無効にする方法

このセクションは、disabledDates 機能の使用について説明します。これには、異なる単一の日付または範囲を配列に追加し、disabledDates 記述子に渡すことができます。

DateRangeType は無効にする範囲を指定するために使用します。

現在の月の 3 日から 8 日の日付を無効にするサンプルを作成します。

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 }];
    }
}

これらの構成の結果は以下のようになります。

特別な日付

specialDates 機能は、disabledDates とほとんど同じ構成を使用します。disabled と異なる点は specialDates を選択してフォーカスする機能です。

igxCalendar に specialDates を追加します。これを行うには、DateRangeType.Specific タイプの DateRangeDescriptor 項目を作成し、日付の配列を DateRangeDescriptor.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>

以下のデモでは、休暇要求オプションのカレンダーを示します。

週番号

showWeekNumbers 入力を使用して、Calendar コンポーネント と DatePicker コンポーネントの両方の週番号を表示できるようになりました。

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

以下のデモは、週番号が有効になっているカレンダーを示しています:

カレンダー イベント

カレンダーが発するイベントを見てみましょう:

• selected - カレンダーで日付を選択すると発生されます。
• viewDateChanged - 表示されている月/年が変更されるたびに発行されます。たとえば、next または previous の月に移動した後。
• activeViewChanged - アクティブなビューが変更された後に発生します。たとえば、ユーザーがヘッダーの month または year セクションをクリックした後。

selectedイベントは、入力検証ロジックを構築するのに適しています。以下のコードを使用して、選択が 5 日を超えた場合にユーザーに警告し、選択をリセットします。

<!-- app.component.html -->
<igx-calendar #calendar
    (selected)="onSelection($event)"
    (viewDateChanged)="viewDateChanged($event)"
    (activeViewChanged)="activeViewChanged($event)">
</igx-calendar>

以下のデモを試して (選択を変更し、月と年を移動し)、リアルタイムで記録されたイベントを確認してください:

// 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 the demo below to play around (change selection, navigate through months and years) and see the events logged real time:

Angular Calendar ビュー

IgxCalendarModule によって提供される個別のビューがあり、別々に使用できます。

• Angular Calendar 日ビュー - DaysView

• Angular Calendar 月ビュー - MonthsView

• Angular Calendar 年ビュー - YearsView

• Angular Calendar Year View - YearsView

キーボード ナビゲーション

Tab キーを使用してページを移動する場合、igxCalendarComponent が W3 アクセシビリティ推奨事項に基づいて以下のタブストップを導入することに注意してください。

• [前月] ボタン
• [月の選択] ボタン
• [年の選択] ボタン
• [翌月] ボタン
• 日ビューの選択した日付、現在の日付、最初のフォーカス可能な (無効ではない) 日付

複数の選択された日付を含む Angular Calendar では、最初の日付のみがタブ位置として導入されます。たとえば、Angular Calendar の複数選択が有効で、日付を選択した場合: 2020 年 10 月 13 日、2020 年 10 月 17 日および 2020 年 10 月 21 日のみは、タブ ナビゲーション中にアクセスできます。Angular Calendar 範囲ピッカーでは、選択した範囲の最初の日付のみがページ タブ シーケンスの一部になります。

igxCalendar コンポーネントにフォーカスがある場合、以下を使用してナビゲーションできます。

• PageUp キーは前の月に移動します。
• PageDown キーは次の月に移動します。
• Shift + PageUp キーは前の年に移動します。
• Shift + PageDown> キーは次の年に移動します。
• Home キーは現在の年の最初の月をフォーカスします。
• End キーは現在の月の最後の日または最後の月をフォーカスします。

前または次の月のボタン(サブヘッダー内)にフォーカスがある場合、以下を使用します。

• Space または Enter キーは次の月または前の月のビューへスクロールします。

サブヘッダーの月ボタンのフォーカス時:

• Space または Enter キーは月ビューを開きます。

サブヘッダーの年ボタンのフォーカス時:

• Space または Enter キーは10 年ビューを開きます。

現在月の日がフォーカスされる場合:

• 矢印キーで日を移動します。注: 無効な日付はスキップされます。
• フォーカスはビューの現在の月に保持され、ナビゲーションは月の最終日 / 初日 から / までになります。
• キーボード ナビゲーションは連続です。つまり、矢印でナビゲーションしている間、すべての月を移動します。
• Enter キー を使用して、現在フォーカスされている日を選択します。

月ビュー内の月のフォーカス時:

• 矢印キーで月を移動します。
• Home キーは月ビューの最初の月にフォーカスします。
• End キーは月ビューの最後の月にフォーカスします。
• Enter キーは、現在フォーカスされている月を選択してビューと閉じます。

10 年ビュー内の年のフォーカス時:

• 上矢印 キーと 下矢印 キーで年を移動します。
• Enter キーは、現在フォーカスされている年を選択してビューと閉じます。

バージョン 8.2.0 に続いて、キーボード ナビゲーションは現在の月以外の日をフォーカスせず、ビューの月を変更します。

• Space or Enter key to open the decade view.

When a day inside the current month is focused:

• Use Arrow keys to navigate through the days. Note: The disabled dates will be skipped.
• Focus will be persisted on the current month that is in the view, while navigation from/to the last day/first day of the month.
• THe kb navigation would be continuous, which means that it will go through all months while navigating with the arrows.
• Use Enter key to select the currently focused day.

When a month inside the months view is focused, use:

• Arrow keys to navigate through the months.
• Home key to focus the first month inside the months view.
• End key to focus the last month inside the months view.
• Enter key to select the currently focused month and close the view.

When an year inside the decade view is focused, use:

• Arrow up and Arrow down keys to navigate through the years,
• Enter key to select the currently focused year and close the view.

マルチビュー カレンダー

マルチ ビューカレンダーは、3 種類すべての選択をサポートしています。monthsViewNumber 入力を使用して、表示される月の数を設定します。これは、フレックス コンテナーに水平に表示されます。設定される最大値に制限はありません。マルチ ビューカレンダーを使用する場合、現在の月に属さない日を非表示にできます。非表示にするには、hideOutsideDaysプ ロパティを使用します。キーボード ナビゲーションは、表示されている次/前の月へ移動します。

カレンダーの方向

方向の設定により、ユーザーはカレンダーのヘッダーとビューの表示方法を選択できます。

ヘッダーの方向オプション

ヘッダーの方向を変更して、カレンダーのヘッダーを水平 (カレンダー ビューの上) または垂直 (カレンダー ビューの横) に配置できます。 これを行うには、[headerOrientation] プロパティを使用し、それぞれ horizo​​ntal または vertical に設定します。

ビューの方向オプション

ビューの方向を設定して、カレンダー内の月を水平 (並べて) または垂直 (上下に) に配置できます。 これを行うには、[orientation] プロパティを使用して、それぞれ horizo​​ntal または vertical に設定します。

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

スタイル設定

Calendar テーマのプロパティ マップ

$header-background プロパティと $content-background プロパティを変更すると、関連するすべての theme プロパティが自動的に調整され、カレンダー コンポーネントのスタイルが一貫して設定されます。影響を受ける theme プロパティの詳細な概要については、以下の表を参照してください。

カレンダーのスタイル設定を開始するには、すべてのテーマ関数とコンポーネント ミックスインが存在する index ファイルをインポートする必要があります。

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

// 重要: Ignite UI for Angular 13 より前のバージョンは、次を使用してください。
// @import '~igniteui-angular/lib/core/styles/themes/index';

最もシンプルな方法として、calendar-theme を拡張し、$header-background と $content-background のみを指定して新しいテーマを作成します。これにより、インタラクション状態に応じた色やコントラストのある前景の色が自動的に算出されます。必要に応じて任意のテーマ パラメーターをオーバーライドすることも可能です。

$custom-calendar-theme: calendar-theme(
  $header-background: #ecaa53,
  $content-background: #011627,
);

最後に calendar のカスタム テーマを設定します。

:host {
    @include tokens($custom-calendar-theme);
}

以下のサンプルでは、カスタマイズした CSS 変数を使用したカレンダー コンポーネントが、SAP UI5 デザイン システムのカレンダーに視覚的に似たデザインを実現している様子を確認できます。

Tailwind によるスタイル設定

カスタム Tailwind ユーティリティ クラスを使用して calendar をスタイル設定できます。まず Tailwind を設定してください。

グローバル スタイルシートに Tailwind をインポートした上で、以下のように必要なテーマ ユーティリティを適用します:

@import "tailwindcss";
...
@use 'igniteui-theming/tailwind/utilities/material.css';

ユーティリティ ファイルには、light テーマと dark テーマの両方のバリエーションが含まれています。

• light-* クラスはライト テーマ用です。
• dark-* クラスはダーク テーマ用です。
• プレフィックスの後にコンポーネント名を追加します (例: light-calendar、dark-calendar)。

これらのクラスを適用すると、動的なテーマの計算が可能になります。そこから、任意のプロパティを使用して、生成された CSS 変数をオーバーライドできます。コロンの後に、有効な CSS カラー形式 (HEX、CSS 変数、RGB など) を指定します。

プロパティの完全なリストは、calendar-theme で確認できます。構文は次のとおりです:

<igx-calendar
class="!light-calendar
![--header-background:#4F6A5A]
![--content-background:#A3C7B2]"
[weekStart]="1">
</igx-calendar>

最終的に、calendar は次のようになります:

API リファレンス

• Calendar
• IgxCalendarComponent スタイル
• DateRangeType
• DateRangeDescriptor

その他のリソース

コミュニティに参加して新しいアイデアをご提案ください。

• Ignite UI for Angular フォーラム (英語)
• Ignite UI for Angular GitHub (英語)