範圍日曆

範圍日曆包含一個群組元素，其中包含一個或多個日期網格（例如月份），以及用於在時間之間導覽的上一個和下一個按鈕。每個日曆網格都包含按鈕元素組成的儲存格，可以使用箭頭鍵按下和導覽以選擇日期範圍。選取開始日期後，使用者可以使用鍵盤導覽至另一個日期，或將滑鼠游標懸停在其上，然後按一下或按下 Enter 鍵即會提交選取的日期範圍。

安裝

以上命令僅適用於個別安裝。如果 @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 屬性允許在日曆首次掛載時設定初始聚焦日期，而無需控制它。

無效日期

這個範例會驗證根據目前的語言環境，選取的日期是否為平日而不是週末。

帶有月份和年份選擇器

日曆支援月份和年份選擇器，以便快速選擇。您可以將 showMonthAndYearPickers 設定為 true 來啟用此功能。但是，如果將 visibleMonths 設定為大於 1 的數字，此功能將會停用。

國際日曆

日曆支援選取世界各地使用的許多日曆系統中的日期，包括公曆、希伯來曆、印度曆、伊斯蘭曆、佛教曆等等。日期會自動以使用者語言環境的適當日曆系統顯示。可以使用傳遞給 Provider 元件的 Unicode 日曆語言環境擴充來覆寫日曆系統。

可見月份

預設情況下，日曆會顯示單一月份。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：儲存格是否為無效選取的一部分。

無障礙功能

• 一次顯示一個或多個月份，或用於像週視圖等用例的自訂時間範圍。也支援最小值和最大值、不可用的日期和非連續選取。
• 支援世界各地使用的 13 種日曆系統，包括格里曆、佛教曆、伊斯蘭曆、波斯曆等。也提供特定地區的格式設定、數字系統和從右到左的支援。
• 可以使用鍵盤導覽和選取日曆儲存格，並且包含本地化的螢幕閱讀器訊息，以在選取和可見日期範圍變更時通知。

API

RangeCalendar 屬性

範圍日曆事件

支援的日曆