输入框

输入框是一个允许用户输入文本的组件。它可以用于在表单、搜索字段等地方获取用户输入。

安装

上面的命令仅用于单独安装。如果 @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（当它在内部时）和 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、剪贴板、composition、selection 和 input 事件。
• 通过 ARIA 将 required 和 invalid 状态暴露给辅助技术。
• 支持通过 ARIA 链接到输入框的描述和错误消息帮助文本。

API

输入框属性

输入框事件