输入框

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

安装

上述命令仅用于单独安装。如果您已全局安装 @heroui/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 属性来控制输入框的值。

注意：HeroUI 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 属性。

服务器端验证

客户端验证提供即时反馈，但您也应该在服务器端验证数据，以确保准确性和安全性。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 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 标签支持。
• 更改、剪贴板、组合、选择和输入事件支持。
• 必填和无效状态通过 ARIA 暴露给辅助技术。
• 支持通过 ARIA 链接到输入框的描述和错误消息帮助文本。

API

Input Props

Input Events