NumberField

import type { ReactElement } from 'react'
import { Field, FieldDescription, FieldLabel, NumberField } from '@gedatou/cadenza-ui'

数字输入的完整控件，基于 Base UI 的 NumberField 组合。中间是真 <input>： 可以直接打字，也可以用方向键、两侧的 ± 按钮步进；format 走 Intl.NumberFormatOptions，显示带格式、值始终是纯数字。

使用#

复制import { NumberField } from '@gedatou/cadenza-ui'

复制<NumberField defaultValue={4} min={0} max={99} />

不写 children 就有完整默认组合。标签走普通通道：根上的 id 由 Base UI 直接 路由到内层输入框，FieldLabel htmlFor 直连；没有可见标签时传 aria-label， 默认组合会转交给输入框。

组成#

一行式组框，四个部件；写了 children 默认组合整层让位。

复制NumberField
└─ NumberFieldGroup
   ├─ NumberFieldDecrement
   ├─ NumberFieldInput
   └─ NumberFieldIncrement

步进钮不写 children 时渲染默认的加减图标，并自带上游的英文 aria-label（Increase / Decrease）、tabIndex={-1}——键盘路径是输入框的 方向键。要本地化按钮名，组合时覆盖：

复制<NumberField defaultValue={4}>
  <NumberFieldGroup>
    <NumberFieldDecrement aria-label="减少" />
    <NumberFieldInput />
    <NumberFieldIncrement aria-label="增加" />
  </NumberFieldGroup>
</NumberField>

受控#

value / defaultValue / onValueChange(value, details)——受控空值是 null（清空输入时回它）；details.reason 区分变更来源。交互落定后另有 onValueCommitted(value, details)，开销大的动作挂它。

import type { NumberFieldChangeEventDetails } from '@gedatou/cadenza-ui'
import type { ReactElement } from 'react'
import { Field, FieldDescription, FieldLabel, NumberField } from '@gedatou/cadenza-ui'

格式化#

format 收 Intl.NumberFormatOptions，locale 缺省跟随运行时；显示与值 分离——展示带货币符号，onValueChange 拿到的仍是纯数字。

import type { ReactElement } from 'react'
import { Field, FieldDescription, FieldLabel, NumberField } from '@gedatou/cadenza-ui'

表单#

有 name 才渲染隐藏 input，值随表单原生提交。与 TanStack Form 的绑定见 表单指南。

键盘交互#

焦点在输入框上时：

状态与 className#

各部件外化 Base UI Field 生态的状态词表（空串存在型）：

className 处处到达 Base UI 槽位，函数形态 (state) => string 可用。

Props#

顺序规则：必填 → 非受控默认值 → 受控值 → 回调 → 行为开关 → 外观 → className。

NumberField#

根部件，管全部状态；不写 children 渲染默认组合。

NumberFieldGroup / NumberFieldInput#

组框与真输入框，纯透传：Base UI 对应部件的 props（各自元素原生属性 + ref）， seam 只补默认样式。

NumberFieldDecrement#

减号步进钮；不写 children 渲染默认减号图标，aria-label 上游默认 Decrease。

NumberFieldIncrement#

加号步进钮；不写 children 渲染默认加号图标，aria-label 上游默认 Increase。

12 个类型一并导出：NumberFieldProps / NumberFieldState / NumberFieldChangeEventDetails / NumberFieldCommitEventDetails / NumberFieldGroupProps / NumberFieldGroupState / NumberFieldInputProps / NumberFieldInputState / NumberFieldIncrementProps / NumberFieldIncrementState / NumberFieldDecrementProps / NumberFieldDecrementState。