範囲カレンダー

範囲カレンダーは、1つ以上の日付グリッド（例：月）を含むグループ要素と、時間内を移動するための前へボタンと次へボタンで構成されています。各カレンダーグリッドは、日付範囲を選択するために押したり、矢印キーを使って移動できるボタン要素を含むセルで構成されています。開始日が選択されると、ユーザーはキーボードを使用するか、上にマウスを移動することで別の日付に移動でき、それをクリックするかEnterキーを押すと選択した日付範囲が確定します。

インストール

npx nextui-cli@latest add calendar

上記のコマンドは個別のインストール専用です。 @nextui-org/react がグローバルにインストール済みの場合は、このステップをスキップできます。

インポート

使い方

RangeCalendarはデフォルトでは選択されていません。defaultValue プロパティを使用すると、初期の、非制御の値を RangeCalendar に提供できます。または、value プロパティを使用して制御された値を提供できます。

日付の値は、@internationalized/dateパッケージのオブジェクトを使用して提供されます。このライブラリは、カレンダー、タイムゾーン、およびその他のローカリゼーションに関する問題について、正しい国際日付操作を処理します。

無効化

isDisabled ブール型のプロパティにより、カレンダーが無効になります。セルはフォーカスまたは選択できません。

読み取り専用

isReadOnly ブール型のプロパティにより、カレンダーの値が不変になります。isDisabledとは異なり、カレンダーはフォーカス可能なままです。

制御

カレンダーはデフォルトでは選択されていません。defaultValue プロパティを使用すると、初期の、非制御の値をカレンダーに提供できます。または、value プロパティを使用して制御された値を提供できます。

最小日付値

デフォルトでは、カレンダーでは任意の日付を選択できます。minValue を使用して、ユーザーが特定の範囲外の日付を選択できないようにすることもできます。

この例では、今日以降の日付のみを受け入れます。

最大日付値

デフォルトでは、カレンダーは任意の日付を選択できます。maxValue を使用して、ユーザーが特定範囲外の日付を選択できないようにすることもできます。

この例では、今日より前の日付のみを受け付けます。

利用不可の日付

カレンダーは、特定の日付を利用不可としてマークすることをサポートしています。これらの日付は、キーボード操作によるナビゲーションの一貫性を保つためフォーカス可能ですが、ユーザーが選択することはできません。この例では、赤色で表示されます。isDateUnavailable プロパティは、表示されている各日付が利用不可かどうかを評価するために呼び出されるコールバックを受け入れます。

非連続範囲

allowsNonContiguousRanges プロパティを使用すると、途中に利用不可の日付があっても範囲を選択できます。onChange イベントで発行される値は、開始と終了プロパティを持つ単一の範囲ですが、利用不可の日付は選択されたものとして表示されません。ビジネスロジックに必要な場合は、選択された範囲全体を複数に分割するのはアプリケーション側の責任です。

この例では、週末の選択を禁止していますが、複数週にまたがる範囲の選択は許可しています。

フォーカスされた値の制御

カレンダーは、そもそもユーザーが無効な日付を選択できないようにしようとします。ただし、アプリケーションロジックに従って選択された日付が無効である場合は、isInvalid プロパティを設定できます。これにより、支援技術のユーザーに選択が無効であることを警告し、スタイリングの目的にも使用できます。さらに、errorMessage スロットを使用して、ユーザーが問題を修正するのを支援できます。

デフォルトでは、カレンダーが最初にマウントされたときに、選択された日付にフォーカスされます。value または defaultValue プロパティが提供されていない場合、現在の日付にフォーカスされます。ただし、カレンダーは focusedValue および onFocusChange プロパティを使用して、どの日付にフォーカスするかを制御することをサポートしています。これにより、どの月が表示されるかも決定されます。defaultFocusedValue プロパティを使用すると、カレンダーが最初にマウントされたときに、制御せずに初期フォーカス日付を設定できます。

無効な日付

この例では、選択した日付が現在のロケールに従って平日であり、週末ではないことを検証します。

国際カレンダー

カレンダーは、グレゴリオ暦、ヘブライ暦、インド暦、イスラム暦、仏暦など、世界中で使用されている多くのカレンダーシステムでの日付選択をサポートしています。日付は、ユーザーのロケールに適したカレンダーシステムで自動的に表示されます。カレンダーシステムは、Unicode カレンダーロケール拡張機能 を使用してオーバーライドでき、Provider コンポーネントに渡されます。

表示される月

デフォルトでは、カレンダーには 1 か月が表示されます。visibleMonths プロパティを使用すると、一度に最大 3 か月を表示できます。

ページ動作

デフォルトでは、次へまたは前へボタンを押すと、ページネーションは visibleMonths 値だけ進みます。この動作は、pageBehavior を single に設定することで、代わりに単月でページングするように変更できます。

プリセット

以下は、topContent および bottomContent をカスタマイズして、いくつかのプリセット値を持たせる例です。

スロット

• base: カレンダーのラッパー。配置、配置、および一般的な外観を処理します。
• prevButton: カレンダーの前へボタン。
• nextButton: カレンダーの次へボタン。
• headerWrapper: ピッカー（月/年）をラップします。
• header: ヘッダー要素。
• title: カレンダータイトルで使用するための、表示されている日付範囲の説明。
• gridWrapper: カレンダーグリッドのラッパー。
• grid: 日付グリッド要素 (例: <table>)。
• gridHeader: 日付グリッドのヘッダー要素 (例: <th>)。
• gridHeaderRow: 日付グリッドのヘッダー行要素 (例: <tr>)。
• gridHeaderCell: 日付グリッドのヘッダーセル要素 (例: <td>)。
• gridBody: 日付グリッドのボディ要素 (例: <tbody>)。
• gridBodyRow: 日付グリッドのボディ行要素 (例: <tr>)。
• cell: 日付グリッドのセル要素 (例: <td>)。
• cellButton: セル内のボタン要素。
• pickerWrapper: ピッカーのラッパー。
• pickerMonthList: 月リストピッカー。
• pickerYearList: 年リストピッカー。
• pickerHighlight: ピッカーのハイライトされた項目。
• pickerItem: ピッカーの項目。
• helperWrapper: カレンダーのヘルパーメッセージ。
• errorMessage: カレンダーのエラーメッセージ。

データ属性

Calendarは、CalendarCell要素に次の属性を持ちます。

• data-focused: セルがフォーカスされているかどうか。
• data-hovered: セルに現在マウスがホバーしているかどうか。
• data-pressed: セルが現在押されているかどうか。
• data-unavailable: セルが、カレンダーのisDateUnavailable プロパティに従って利用不可であるかどうか。利用不可の日付はフォーカス可能ですが、ユーザーが選択することはできません。利用不可であることを示すために、異なる色や取り消し線などの視覚的な手がかりで表示する必要があります。
• data-disabled: セルが、カレンダーの minValue、maxValue、および isDisabled プロパティに従って無効になっているかどうか。
• data-focus-visible: セルがキーボードでフォーカスされているかどうか。
• data-outside-visible-range: セルがカレンダーの表示範囲外にあるかどうか。
• data-outside-month: セルが現在の月の範囲外にあるかどうか。
• data-selected: セルが選択されているかどうか。
• data-selected-start: セルが範囲選択の最初の日に該当するかどうか。
• data-selected-end: セルが範囲選択の最後の日に該当するかどうか。
• data-invalid: セルが無効な選択の一部であるかどうか。

アクセシビリティ

• 一度に1つ以上の月を表示したり、週表示などのユースケースに合わせてカスタムの時間範囲を表示したりできます。最小値と最大値、利用不可の日付、および非連続な選択もサポートされています。
• グレゴリオ暦、仏教暦、イスラム暦、ペルシャ暦など、世界中で使用されている13種類のカレンダーシステムをサポートします。ロケール固有の書式設定、数字システム、右から左へのサポートも利用できます。
• カレンダーセルはキーボードを使用して移動および選択でき、選択範囲や表示日付範囲が変更されたときにアナウンスするローカライズされたスクリーンリーダーメッセージが含まれています。

API

RangeCalendarのProps

RangeCalendar イベント

サポートされているカレンダー

/**
 * Supported react-aria i18n calendars.
 */
export type SupportedCalendars =
  | "buddhist"
  | "ethiopic"
  | "ethioaa"
  | "coptic"
  | "hebrew"
  | "indian"
  | "islamic-civil"
  | "islamic-tbla"
  | "islamic-umalqura"
  | "japanese"
  | "persian"
  | "roc"
  | "gregory";