Input

Input 是一个允许用户输入文本的组件。可用于表单、搜索框等场景中获取用户输入。

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

用法

禁用状态

只读状态

必填项

如果将 isRequired 属性传递给输入框，标签末尾会显示一个 danger 风格的星号，且该输入框将成为必填项。

尺寸

颜色

变体

圆角

标签位置

通过设置 labelPlacement 属性为 inside、outside、outside-left 或 outside-top，可以更改标签的位置。

注意：如果未传递 label，labelPlacement 属性默认为 outside。

注意：如果 labelPlacement 为 outside，仅当提供占位符时，label 才会显示在外部。

注意：如果 labelPlacement 为 outside-top 或 outside-left，即使未提供占位符，label 也会显示在外部。

密码输入框

可以使用 type 属性将输入框类型更改为 password。

清除按钮

如果将 isClearable 属性传递给输入框，输入框末尾会显示一个清除按钮，当输入框有值时该按钮可见。

起始与结束内容

可以使用 startContent 和 endContent 属性在输入框的起始和末尾添加内容。

带描述信息

可以通过传递 description 属性为输入框添加描述信息。

带错误信息

可以组合使用 isInvalid 和 errorMessage 属性来显示无效输入。errorMessage 仅在 isInvalid 设置为 true 时显示。

使用 regex 邮箱验证的示例：

受控输入

可以使用 value 和 onValueChange 属性来控制输入框的值。

注意：HeroUI 的 Input 组件也支持原生事件，如 onChange，这对于 Formik 和 React Hook Form 等表单库非常有用。

与表单结合

Input 组件可以与 Form 组件结合使用，以利用表单状态管理。有关表单和验证行为的更多信息，请参阅表单指南。

内置验证

Input 支持以下原生 HTML 约束验证：

• isRequired 表示在提交表单前字段必须具有值。
• minLength 和 maxLength 指定文本输入的最小和最大长度。
• pattern 提供一个自定义正则表达式，文本输入必须符合该模式。
• type="email" 和 type="url" 为邮箱地址和 URL 提供内置验证。

使用原生验证时，可以通过向 errorMessage 传递一个函数并检查 validationDetails 的 ValidityState 来自定义错误消息。

自定义验证

除了内置约束外，还可以向 validate 属性提供一个函数以进行自定义验证。

实时验证

如果希望在用户输入时显示验证错误，可以控制字段值并使用 isInvalid 属性以及 errorMessage 属性。

服务端验证

客户端验证提供即时反馈，但您也应在服务器端验证数据以确保准确性和安全性。 HeroUI 允许您通过使用 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 钩子创建自己的实现。

数据属性

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 标签。
• 支持变更、剪贴板、组合、选择和输入事件。
• 通过 ARIA 向辅助技术公开必需和无效状态。
• 支持通过 ARIA 将描述和错误消息帮助文本链接到输入框。

API

Input 属性

Input 事件