輸入框

輸入框是一個允許使用者輸入文字的元件。它可以用於在表單、搜尋欄位等地方獲取使用者輸入。

安裝

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

導入

使用方式

禁用

唯讀

必填

如果您將 isRequired 屬性傳遞給輸入框，它會在標籤的末尾加上一個 danger 星號，並且該輸入框將為必填。

尺寸

顏色

樣式變體

圓角

標籤位置

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

注意：如果未傳遞 label，則 labelPlacement 屬性預設為 outside。

密碼輸入框

您可以使用 type 屬性將輸入類型變更為 password。

清除按鈕

如果您將 isClearable 屬性傳遞給輸入框，它會在輸入框的末尾加上一個清除按鈕，當輸入框有值時，該按鈕會顯示。

開始 & 結束內容

您可以使用 startContent 和 endContent 屬性，在輸入框的開始和結束處添加內容。

帶有描述

您可以透過傳遞 description 屬性，為輸入框新增描述。

帶有錯誤訊息

您可以結合 isInvalid 和 errorMessage 屬性來顯示無效的輸入。errorMessage 僅在 isInvalid 設定為 true 時顯示。

使用 regex 電子郵件驗證的範例

受控

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

注意：NextUI 的 Input 也支援原生事件，例如 onChange，這對於像 Formik 和 React Hook Form 等表單函式庫非常有用。

使用表單

Input 可以與 Form 元件一起使用，以利用表單狀態管理。預設情況下，Form 元件使用 validationBehavior="aria"，這不會在任何輸入無效時阻止表單提交。有關表單和驗證行為的更多資訊，請參閱表單指南。

內建驗證

Input 支援以下原生 HTML 約束

• isRequired 表示表單必須在提交前填寫值。
• minLength 和 maxLength 指定文字輸入的最小和最大長度。
• pattern 提供文字輸入必須符合的自訂正規表達式。
• type="email" 和 type="url" 為電子郵件地址和 URL 提供內建驗證。

使用原生驗證時，可以透過將函式傳遞給 errorMessage 並檢查 validationDetails 的ValidityState 來客製化錯誤訊息。

自訂驗證

除了內建約束之外，您還可以將函式提供給 validate 屬性以進行自訂驗證。

即時驗證

如果您想在使用者輸入時顯示驗證錯誤，您可以控制欄位值並使用 isInvalid 屬性以及 errorMessage 屬性。

伺服器驗證

用戶端驗證提供即時回饋，但您也應該在伺服器上驗證資料，以確保準確性和安全性。NextUI 允許您透過在 Form 元件中使用 validationErrors 屬性來顯示伺服器端驗證錯誤。此屬性應為物件，其中每個鍵是欄位 name，而值是錯誤訊息。

插槽

• base：輸入框包裝器，它處理對齊、放置和整體外觀。
• label：輸入框的標籤，它是在輸入框上方、內部或左側顯示的標籤。
• mainWrapper：當位置為 outside / outside-left 時，包覆 inputWrapper 的容器。
• inputWrapper：包覆 label (當 label 在內部時) 和 innerWrapper 的容器。
• innerWrapper：包覆 input、startContent 和 endContent 的容器。
• input：輸入元素。
• clearButton：清除按鈕，位於輸入框的尾端。
• helperWrapper：包覆 description 和 errorMessage 的容器。
• description：輸入框的說明文字。
• errorMessage：輸入框的錯誤訊息。

自訂樣式

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

自訂實作

如果您需要更進一步自訂輸入框，可以使用 useInput Hook 來建立您自己的實作。

資料屬性

Input 在 base 元素上具有以下屬性：

• data-invalid：當輸入框無效時。基於 isInvalid 屬性。
• data-required：當輸入框為必填時。基於 isRequired 屬性。
• data-readonly：當輸入框為唯讀時。基於 isReadOnly 屬性。
• data-hover：當滑鼠懸停在輸入框上時。基於 useHover。
• data-focus：當輸入框處於焦點時。基於 useFocusRing。
• data-focus-within：當輸入框或其任何子元素處於焦點時。基於 useFocusWithin。
• data-focus-visible：當使用鍵盤將焦點放在輸入框上時。基於 useFocusRing。
• data-disabled：當輸入框被禁用時。基於 isDisabled 屬性。

無障礙性

• 使用原生 <input> 元素建構。
• 支援視覺和 ARIA 標籤。
• 支援 change、clipboard、composition、selection 和 input 事件。
• 必填和無效狀態透過 ARIA 暴露給輔助技術。
• 支援透過 ARIA 連結到輸入框的描述和錯誤訊息幫助文字。

API

輸入框 Props

輸入框事件