日曆 (Calendar)

日曆包含一個群組元素，其中包含一個或多個日期網格（例如月份），以及用於在日期範圍之間導覽的上一個和下一個按鈕。每個日曆網格都包含單元格，這些單元格包含可以使用箭頭鍵按下和導覽以選擇日期的按鈕元素。

安裝

以上指令僅用於個別安裝。如果已全域安裝 @nextui-org/react ，您可以跳過此步驟。

匯入

用法

日曆預設沒有選取。可以使用 defaultValue 屬性為日曆提供初始的、非受控的值。或者，可以使用 value 屬性提供受控的值。

日期值是使用 @internationalized/date 套件中的物件提供的。此函式庫處理跨日曆、時區和其他本地化問題的正確國際日期操作。

已停用

isDisabled 布林值屬性會停用日曆。儲存格無法被聚焦或選取。

唯讀

isReadOnly 布林值屬性會使日曆的值變為不可變。與 isDisabled 不同，日曆仍然可被聚焦。

受控

日曆預設沒有選取。可以使用 defaultValue 屬性為日曆提供初始的、非受控的值。或者，可以使用 value 屬性提供受控的值。

最小日期值

預設情況下，「日曆」允許選擇任何日期。您也可以使用 minValue 來防止使用者選擇特定範圍之外的日期。

此範例僅接受今天之後的日期。

最大日期值

預設情況下，「日曆」允許選擇任何日期。您也可以使用 maxValue 來防止使用者選擇特定範圍之外的日期。

此範例僅接受今天之前的日期。

不可用日期

「日曆」支援將某些日期標記為不可用。這些日期仍然可以使用鍵盤聚焦，以便導覽保持一致，但使用者無法選取。在此範例中，它們會以紅色顯示。isDateUnavailable 屬性接受一個回呼函式，該函式會被呼叫來評估每個可見的日期是否不可用。

受控的焦點值

「日曆」會嘗試避免讓使用者一開始就選取無效的日期。但是，如果根據應用程式邏輯，選取的日期無效，則可以設定 isInvalid 屬性。這會提醒輔助技術使用者選取項目無效，並且也可以用於樣式設定。此外，errorMessage 插槽可用於協助使用者修正問題。

預設情況下，「日曆」第一次掛載時，焦點會放在選取的日期上。如果未提供 value 或 defaultValue 屬性，則焦點會放在目前的日期上。但是，「日曆」支援使用 focusedValue 和 onFocusChange 屬性來控制焦點所在的日期。這也決定了哪個月份可見。defaultFocusedValue 屬性允許在「日曆」第一次掛載時設定初始焦點日期，而無需進行控制。

無效日期

此範例會根據目前的地區設定驗證選取的日期是否為平日而非週末。

具有月份和年份選擇器

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

國際日曆

「日曆」支援選取世界各地使用的多種日曆系統中的日期，包括公曆、希伯來曆、印度曆、伊斯蘭曆、佛教曆等等。日期會自動以使用者地區設定的適當日曆系統顯示。可以使用 Unicode 日曆地區設定延伸 (傳遞給 Provider 元件) 來覆寫日曆系統。

可見月份

預設情況下，「日曆」會顯示單一月份。 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

日曆屬性

日曆事件

類型

支援的日曆