日期範圍選擇器

日期範圍選擇器結合了兩個日期輸入框和一個範圍日曆彈出視窗，讓使用者可以輸入或選擇日期和時間範圍。

安裝

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

導入

使用方式

已停用

唯讀

必填

如果您將 isRequired 屬性傳遞給輸入框，則標籤末尾會出現一個 danger 星號，且該輸入框將為必填。

變體

可見月份

預設情況下，日曆彈出視窗會顯示單個月份。如果螢幕空間允許，visibleMonths 屬性允許一次顯示最多 3 個月份。

頁面行為

預設情況下，按下「下一個」或「上一個」按鈕時，分頁會以前進或後退 visibleMonths 值的月份數。您可以將 pageBehavior 設定為 single，將此行為變更為一次分頁一個月。

標籤位置

您可以透過將 labelPlacement 屬性設定為 inside、outside 或 outside-left 來變更標籤的位置。

注意：如果沒有傳遞 label，則 labelPlacement 屬性預設會是 outside。

附帶描述

您可以透過傳遞 description 屬性來為輸入欄位新增描述。

附帶錯誤訊息

您可以結合 isInvalid 和 errorMessage 屬性來顯示無效的輸入。

您也可以將錯誤訊息作為函式傳遞。這允許根據 ValidationResult 進行動態錯誤訊息處理。

附帶月份和年份選擇器

您可以透過將 showMonthAndYearPickers 屬性設定為 true，在日曆彈出視窗中顯示月份和年份選擇器。但是，將大於 1 的數字傳遞給 visibleMonths 屬性將會停用此功能。

附帶時間欄位

當提供 CalendarDateTime 或 ZonedDateTime 物件作為值時，DateRangePicker 會自動包含時間欄位。

選擇器圖示

您可以使用 selector 在日期範圍選擇器的開頭和結尾新增內容。

選擇器按鈕位置

您可以透過將 selectorButtonPlacement 屬性設定為 start 或 end 來變更選擇器按鈕的位置。

受控

您可以使用 value 和 onChange 屬性來控制輸入值。

時區

當提供 ZonedDateTime 物件作為值時，DateRangePicker 會感知時區。在這種情況下，會顯示時區縮寫，並且在操作值時會考慮到日光節約時間等時區問題。

@internationalized/date 包含將多種格式的字串剖析為 ZonedDateTime 物件的函式。

粒度

粒度屬性可讓您控制 DateRangePicker 顯示的最小單位。預設情況下，值會以「天」粒度（年、月和日）顯示，而 CalendarDateTime 和 ZonedDateTime 值會以「分鐘」粒度顯示。

@internationalized/date 包含將多種格式的字串剖析為 ZonedDateTime 物件的函式。

最小日期和最大日期

minValue 和 maxValue 屬性也可以用來確保數值在特定範圍內。

@internationalized/date 包含將多種格式的字串剖析為 ZonedDateTime 物件的函式。

國際日曆

DateRangePicker 支援選擇世界上多種日曆系統中的日期，包括公曆、希伯來曆、印度曆、伊斯蘭曆、佛教曆等等。日期會自動以使用者地區設定的適當日曆系統顯示。可以使用Unicode 日曆地區擴充，傳遞給 I18nProvider 元件來覆寫日曆系統。

@internationalized/date 包含將多種格式的字串剖析為 ZonedDateTime 物件的函式。

不可用日期

DateRangePicker 支援將某些日期標記為不可用。這些日期使用者無法選取，並在日曆中以刪除線的外觀顯示。在日期欄位中，如果使用者輸入不可用的日期，則會顯示無效狀態。

@internationalized/date 包含將多種格式的字串剖析為 ZonedDateTime 物件的函式。

非連續

allowsNonContiguousRanges 屬性允許選取範圍，即使中間有不可用的日期。在 onChange 事件中發出的值仍然會是具有開始和結束屬性的單個範圍，但不可用的日期將不會顯示為選取狀態。應用程式需要根據業務邏輯將完整選取的範圍分割成多個範圍。

@internationalized/date 包含將多種格式的字串剖析為 ZonedDateTime 物件的函式。

預設值

@internationalized/date 包含將多種格式的字串剖析為 ZonedDateTime 物件的函式。

插槽

• base：基礎元素。它處理對齊、放置和一般外觀。
• label：日期範圍選取器的標籤，它顯示在日期輸入上方、內部或左側。
• calendar：日曆元素。
• selectorButton：選取器按鈕元素。
• selectorIcon：選取器圖示元素。
• popoverContent：日曆快顯視窗元素。
• calendarContent：日曆的內容元素。
• inputWrapper：包裝 label（當它在內部時）和 innerWrapper。
• input：輸入元素。
• segment：區段元素。
• separator：分隔符號元素。
• bottomContent：底部內容元素。
• timeInputWrapper：輸入元素的包裝元素。
• helperWrapper：包裝 description 和 errorMessage。
• description：日期輸入的描述。
• errorMessage：日期輸入的錯誤訊息。

自訂樣式

您可以透過將自訂的 Tailwind CSS 類別傳遞到元件插槽，來自訂 DateRangePicker 元件。

資料屬性

DateRangePicker 在 base 元素上具有以下屬性

• data-slot：所有插槽都有此屬性。表示元素代表哪個插槽（例如，canlendar）。
• data-open：指示日曆快顯視窗是否開啟。
• data-invalid：當日期範圍選取器無效時。根據 isInvalid 屬性。
• data-required：當日期範圍選取器為必填時。根據 isRequired 屬性。
• data-readonly：當日期範圍選取器為唯讀時。根據 isReadOnly 屬性。
• data-disabled：當日期範圍選取器被禁用時。根據 isDisabled 屬性。
• data-has-start-content：當日期範圍選取器具有開始內容時。基於 startContent 屬性。
• data-has-end-content：當日期範圍選取器具有結束內容時。基於 endContent 屬性。
• data-has-multiple-months：當日期範圍選取器的 visibleMonth 大於 2 時。

無障礙功能

• 每個日期和時間單位都顯示為可個別聚焦和編輯的區段，讓使用者可以使用鍵盤輕鬆編輯任何日期格式和地區設定中的日期。
• 使用者也可以開啟日曆快顯視窗，在標準月份網格中選取日期範圍。包含本地化的螢幕閱讀器訊息，以便在選取和可見日期範圍變更時發出通知。
• 日期區段可使用易於操作的數字鍵盤編輯，日期範圍可透過在日曆上拖曳來選擇（使用觸控螢幕），並且所有互動都可透過觸控式螢幕閱讀器存取。
• 與 HTML 表單整合，支援 required、minimum 和 maximum 值、不可用的日期、自訂驗證函式、即時驗證和伺服器端驗證錯誤。

API

DateRangePicker 屬性

DateRangePicker 事件