時間輸入

TimeInput 元件由一個標籤和一組表示時間各個單位的區段（例如：小時、分鐘和秒）組成。每個區段都是可獨立聚焦的，使用者可以透過鍵入或使用箭頭鍵來增加或減少數值進行編輯。這種方式允許數值被正確地格式化和解析，無論地區或時間格式為何，並提供了一個使用鍵盤輕鬆且無錯誤地編輯時間的方法。

安裝

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

導入

使用方式

TimeInput 預設會顯示一個佔位符。可以使用 `defaultValue` 屬性為 `TimeField` 提供一個初始、不受控制的值。或者，可以使用 `value` 屬性提供一個受控制的值。

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

TimeInput 僅支援選取時間，但也接受包含日期元件的值。預設情況下，TimeInput 將在 onChange 事件中發出 Time 物件，但是如果將 CalendarDateTime 或 ZonedDateTime 物件作為 value 或 defaultValue 傳入，則會發出該類型的值，僅變更時間並保留日期元件。

必填

TimeInput 支援 isRequired 屬性，以確保使用者輸入值，以及最小值和最大值，以及自訂的用戶端和伺服器端驗證。

已停用

布林值屬性 isDisabled 會使 TimeInput 處於停用狀態。輸入欄位無法取得焦點或選取。

唯讀

布林值屬性 isReadOnly 會使 TimeInput 的值不可變。與 isDisabled 不同，TimeInput 仍可取得焦點。

無標籤

TimeInput 支援 label 屬性來顯示或不顯示標籤。

含描述

欄位的描述。提供提示，例如選擇內容的特定要求。

含錯誤訊息

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

您也可以將錯誤訊息當做函式傳遞。這樣可以根據 ValidationResult 進行動態錯誤訊息處理。

標籤位置

標籤相對於它所標記元素的整體位置。

開始內容

如果您想要在時間輸入欄位之前顯示一些內容，您可以設定 startContent 屬性。

結束內容

如果您想要在時間輸入欄位之後顯示一些內容，您可以設定 endContent 屬性。

受控

可以使用 defaultValue 屬性，為 TimeInput 提供一個初始的、非受控的值。可以使用 value 屬性，提供一個受控的值。

時區

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

在大多數情況下，您的數據將以 ISO 8601 格式化的字串從伺服器接收和發送。@internationalized/date 包含將多種格式的字串解析為 ZonedDateTime 物件的函式。您使用的格式將取決於您需要儲存哪些資訊。

• parseZonedDateTime – 此函式會解析具有明確時區和可選 UTC 偏移的日期（例如，2021-11-07T00:45[America/Los_Angeles] 或 2021-11-07T00:45-07:00[America/Los_Angeles]）。此格式會保留最大量的資訊。如果使用者選擇的確切本地時間和時區很重要，請使用此格式。儲存所選的時區和偏移，而不是轉換為 UTC，可確保本地時間的正確性，而無需考慮日光節約規則的變更（例如，如果某個地區廢除日光節約時間）。適用此情況的範例包括日曆事件、提醒以及在特定位置發生的其他時間。
• parseAbsolute – 此函式會解析在地球上所有位置同時發生的絕對日期和時間。它可以使用 UTC 表示（例如，2021-11-07T07:45:00Z），或使用特定的偏移儲存（例如，2021-11-07T07:45:00-07:00）。必須傳遞時區識別碼，例如 America/Los_Angeles，結果將轉換為該時區。無論時區如何，絕對時間都是表示過去發生的事件或需要精確時間的未來事件的最佳方式。
• parseAbsoluteToLocal – 此函式將絕對日期和時間解析為目前使用者的本地時區。它是 parseAbsolute 的快捷方式，並接受相同的格式。

粒度

granularity 屬性可讓您控制 TimeInput 顯示的最小單位。預設情況下，時間會以「分鐘」粒度顯示。可以將 granularity 屬性設定為「秒」來顯示更細粒度的時間值。

最小時間值

minValue 屬性可讓您驗證某個時間之前的值。

最大時間值

maxValue 屬性可讓您驗證某個時間之前的值。

預留位置值

當未設定任何值時，會顯示預留位置。預留位置的格式受 granularity 和 placeholderValue 屬性的影響。placeholderValue 也會在使用者首次與它們互動時（例如，使用向上和向下箭頭鍵）控制每個區段的預設值。預設情況下，placeholderValue 是午夜，但您可以根據需要將其設定為更合適的值。

隱藏時區

當 TimeInput 的值提供的是 ZonedDateTime 物件時，預設會顯示時區縮寫。但是，如果時區已在其他位置顯示或根據使用案例隱含，則可以使用 hideTimeZone 選項隱藏它。

小時週期

預設情況下，TimeInput 會根據使用者的地區設定，以 12 小時或 24 小時格式顯示時間。但是，如果特定使用情境需要，可以使用 hourCycle 屬性來覆寫此設定。此範例強制 TimeInput 使用 24 小時制，無論地區設定為何。

插槽

• base：輸入框外層容器，負責處理對齊、位置和整體外觀。
• label：時間輸入框的標籤，顯示在時間輸入框的上方、內部或左側。
• inputWrapper：包覆 label（當標籤在內部時）和 innerWrapper。
• input：時間輸入元素。
• innerWrapper：包覆區段、startContent 和 endContent。
• segment：輸入元素的區段。
• helperWrapper：輔助文字的容器。此容器包覆輔助文字和錯誤訊息。
• description：時間輸入框的說明。
• errorMessage：時間輸入框的錯誤訊息。

資料屬性

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

• data-has-helper：當時間輸入框具有說明或錯誤訊息時。基於 description 或 errorMessage 屬性。
• data-required：當時間輸入框為必填時。基於 isRequired 屬性。
• data-disabled：當時間輸入框被禁用時。基於 isDisabled 屬性。
• data-readonly：當時間輸入框為唯讀時。基於 isReadOnly 屬性。
• data-invalid：當時間輸入框無效時。基於 isInvalid 屬性。
• data-has-start-content：當時間輸入框具有起始內容時。基於 startContent 屬性。
• data-has-end-content：當時間輸入框具有結束內容時。基於 endContent 屬性。

無障礙功能

• 支援特定地區的格式、數字系統、小時週期和從右至左的佈局。
• 時間可以選擇性地包含時區。所有修改都遵循時區規則，例如日光節約時間。
• 每個時間單位都顯示為可個別聚焦和編輯的區段，讓使用者可以輕鬆地使用鍵盤以任何格式和地區設定來編輯時間。
• 時間區段可以使用易於使用的數字鍵盤進行編輯，並且所有互動都可以使用基於觸控的螢幕閱讀器存取。

API

TimeInput 屬性

TimeInput 事件