NumberInput

NumberInput → NumberField 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 NumberField 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，NumberInput 是单个组件，通过 prop 配置：

1import { NumberInput } from "@lenso/ui";2
3export default function App() {4  return <NumberInput label="Amount" defaultValue={1024} />;5}

在 v3 中，NumberField 改为复合组件：

1import { NumberField, Label } from "@lenso/ui";2
3export default function App() {4  return (5    <NumberField defaultValue={1024}>6      <Label>Amount</Label>7      <NumberField.Group>8        <NumberField.DecrementButton />9        <NumberField.Input />10        <NumberField.IncrementButton />11      </NumberField.Group>12    </NumberField>13  );14}

主要变化

1. 组件命名

v2： NumberInput
v3： NumberField

2. 组件结构

v2： 单个组件，通过 prop 配置
v3： 复合组件：NumberField.Group、NumberField.Input、NumberField.IncrementButton、NumberField.DecrementButton

3. Prop 变更

v2 prop	v3 位置	说明
`onValueChange`	`onChange`	事件处理函数已重命名
`label`	—	改用 `Label` 组件
`description`	—	改用 `Description` 组件
`errorMessage`	—	改用 `FieldError` 组件
`variant`	`variant`（在 NumberField 上）	简化为仅 `primary` \| `secondary`
`color`	—	已移除（请改用 Tailwind CSS）
`size`	—	已移除（请改用 Tailwind CSS）
`radius`	—	已移除（请改用 Tailwind CSS）
`startContent`	—	手动将内容放入 Group 中
`endContent`	—	手动将内容放入 Group 中
`labelPlacement`	—	通过布局类自行处理
`hideStepper`	—	省略 `NumberField.IncrementButton` 与 `NumberField.DecrementButton`
`isClearable`	—	请手动实现清除功能
`classNames`	—	改在各子组件上使用 `className` prop
`isWheelDisabled`	—	已移除

迁移示例

表单校验

1{/* With description */}2<NumberInput3  description="Enter the amount"4  label="Amount"5/>6
7{/* With error message */}8<NumberInput9  errorMessage="Please enter a valid number"10  isInvalid11  label="Amount"12/>13
14{/* Required */}15<NumberInput isRequired label="Quantity" />

受控

1import { useState } from "react";2
3const [value, setValue] = useState();4
5<NumberInput6  value={value}7  onValueChange={setValue}8/>

不带步进按钮

1<NumberInput hideStepper label="Amount" />

数值约束

1{/* Min/Max */}2<NumberInput3  label="Quantity"4  maxValue={100}5  minValue={0}6/>7
8{/* Step */}9<NumberInput label="Percentage" step={0.1} />10
11{/* Format options */}12<NumberInput13  formatOptions={{style: "currency", currency: "USD"}}14  label="Price"15/>

组件结构

v3 NumberField 遵循以下结构：

1NumberField (Root)2  ├── Label (optional)3  ├── NumberField.Group4  │   ├── NumberField.DecrementButton5  │   ├── NumberField.Input6  │   └── NumberField.IncrementButton7  ├── Description (optional)8  └── FieldError (optional)

总结

组件重命名：NumberInput → NumberField
组件结构：必须使用复合组件（NumberField.Group、NumberField.Input 等）
标签 / 描述 / 错误：改用独立组件（Label、Description、FieldError）
步进按钮：必须显式包含 NumberField.IncrementButton 与 NumberField.DecrementButton
事件处理函数：onValueChange → onChange
简化变体：v3 仅支持 variant="primary" 与 variant="secondary"；color、size、radius 已移除——请改用 Tailwind CSS
移除 content prop：startContent、endContent —— 请手动放置
移除清除按钮：isClearable 已移除——请自行实现
步进控件：hideStepper 已移除——通过省略相应按钮实现
移除 labelPlacement：labelPlacement 已移除——请通过布局自行实现