数字输入框

数字输入框组件专为用户输入数字而设计，可通过步进按钮增加或减少数值

安装

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

用法

禁用状态

只读状态

必填项

如果在输入框中传递 isRequired 属性，标签末尾将显示危险状态的星号，且输入框将为必填项。

尺寸

颜色

变体

圆角

标签位置

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

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

清除按钮

如果在输入框中传递 isClearable 属性，输入框末尾将显示清除按钮，当输入框有值时可见。

隐藏步进器

您可以通过传递 hideStepper 属性来隐藏步进按钮。

起始与结束内容

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

带标签

您可以通过传递 label 属性为输入框添加标签。

带描述

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

设置最小值

您可以通过传递 minValue 属性设置输入框的最小值。

设置最大值

您可以通过传递 maxValue 属性设置输入框的最大值。

禁用滚轮

默认情况下，您可以使用滚轮增加或减少数值。通过传递 isWheelDisabled 属性可以禁用 NumberInput 中通过滚轮改变数值的功能。

格式化选项

您可以通过传递 formatOptions 属性格式化输入框的值。

错误提示信息

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

受控模式

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

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

结合表单使用

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

自定义验证

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

实时验证

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

服务器验证

客户端验证提供即时反馈，但您也应在服务器上验证数据以确保准确性和安全性。 HeroUI 允许您通过使用 Form 组件中的 validationErrors 属性来显示服务器端验证错误。 此属性应为一个对象，其中每个键是字段的 name，值是错误消息。

插槽

• base: 输入框包装器，处理对齐、布局和整体外观。
• label: 输入框的标签，显示在输入框上方、内部或左侧。
• mainWrapper: 包装 inputWrapper
• inputWrapper: 包装 label (当其位于内部时) 和 innerWrapper。
• innerWrapper: 包装 input、startContent 和 endContent。
• input: input 元素。
• clearButton: 清除按钮，位于输入框末尾。
• stepperButton: 用于增加或减少值的步进按钮。
• stepperWrapper: 步进器的包装器。
• description: NumberInput 的描述。
• errorMessage: NumberInput 的错误消息。

自定义样式

您可以通过向组件插槽传递自定义的 Tailwind CSS 类来定制 NumberInput 组件。

数据属性

NumberInput 在 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 属性。
• data-filled: 当输入有内容、占位符、起始内容或显示占位符时。
• data-has-elements: 当输入有任何元素（标签、辅助文本、描述、错误消息）时。
• data-has-helper: 当输入有辅助文本时。
• data-has-description: 当输入有描述时。
• data-has-label: 当输入有标签时。
• data-has-value: 当输入有值时（占位符未显示）。

无障碍性

• 使用原生的 <input> 元素构建，type="number"。
• 支持视觉和 ARIA 标签。
• 支持更改、剪贴板、组合、选择和输入事件。
• 通过 ARIA 向辅助技术公开必需和无效状态。
• 支持通过 ARIA 与输入框关联的描述、辅助文本和错误消息。

API

NumberInput 属性

NumberInput 事件