数字输入 · NumberInput

输入和调整数字，结合上下界、步长和格式化。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

数字输入 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
数字输入 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
数字输入 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
数字输入 · 状态 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
数字输入 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Number Input

A form input for numeric values with built-in validation, min/max constraints, and step controls. Use NumberInput for quantities, measurements, percentages, and similar inputs.

属性	类型	默认值	说明
label *	string		输入框的标签文本（始终渲染以确保无障碍访问）。
value *	number \| null \| undefined		输入框的当前值。
onChange *	(value: number) => void		有效文本编辑在失焦或按 Enter 时提交；步进或清除控件更改值时也会触发回调。
size	'sm' \| 'md' \| 'lg'	'md'	尺寸变体。
isLabelHidden	boolean		视觉隐藏标签（屏幕阅读器仍可访问）。
description	string		显示在标签和输入框之间的描述文本。
isOptional	boolean		字段是否可选（与 isRequired 互斥）。
onKeyDown	(e: KeyboardEvent<HTMLInputElement>) => void		Callback fired on keydown events on the input.
isRequired	boolean		字段是否必填（与 isOptional 互斥）。
isDisabled	boolean		输入框是否禁用。
isReadOnly	boolean	false	将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留在 Tab 顺序中。只读时所有步进方式均被禁用：方向键、滚轮和步进按钮。同时设置时 isDisabled 优先。
disabledMessage	string		说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持输入框可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 NumberInput。
placeholder	string		占位符文本。
labelTooltip	string		在标签末尾的信息图标中显示的工具提示文本。
startIcon	IconType		显示在输入框起始位置的图标。
labelIcon	IconType		显示在标签文本前的图标。
status	{type: 'error' \| 'warning' \| 'success', message?: string}		带可选消息的验证状态。
statusVariant	'attached' \| 'detached' \| 'tooltip'	'attached'	状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。
min	number \| null		允许的最小值。更小的输入会在失焦或按 Enter 时提交为该值。
max	number \| null		允许的最大值。更大的输入会在失焦或按 Enter 时提交为该值。
step	number \| null	1	输入框的步进增量。
formatValue	(value: number) => string		输入框未聚焦时格式化已提交的值。聚焦编辑时显示原始数值，并通过 aria-valuetext 提供格式化值。
isWheelEnabled	boolean	true	是否允许在已聚焦的输入框上滚动滚轮来步进数值。当页面滚动应始终优先时请禁用。
hasNumberSteppers	boolean	false	是否在输入框末尾显示递增和递减按钮。
units	string \| null		在输入框末尾显示的单位文本（例如"%"或"GB"）。
isIntegerOnly	boolean		仅允许整数值（不允许浮点数）。
hasClear	boolean	false	输入有值时显示清除 (×) 按鈕。启用后， onChange 回调还接受 null 表示用户已清空输入。
htmlName	string		用于表单提交的 HTML name 属性。
autoComplete	string		HTML autocomplete 属性。
width	SizeValue		Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.
hasAutoFocus	boolean		是否在挂载时聚焦输入框。
onFocus	(e: FocusEvent<HTMLInputElement>) => void		输入框获得焦点时触发的回调。
onBlur	(e: FocusEvent<HTMLInputElement>) => void		输入框失去焦点时触发的回调。
onEnter	() => void		用户按下 Enter 键时触发的回调。
containerXstyle	StyleXStyles		字段容器（标签、控件和状态整体）的 StyleX 样式。在 InputGroup 内（请改为设置 InputGroup 的样式）或 `horizontal-labels` FormLayout 中无效。不接受根级 `xstyle`、`className` 和 `style`。
containerClassName	string		字段容器的类名，作用目标同 `containerXstyle`。
containerStyle	CSSProperties		字段容器的内联样式，作用目标同 `containerXstyle`。
controlXstyle	StyleXStyles		可视控件框的 StyleX 样式：绘制边框和背景并包含图标与尾部控件的元素，而非原生输入元素。
controlClassName	string		可视控件框的类名。
controlStyle	CSSProperties		可视控件框的内联样式。

使用建议

可以直接粘贴带格式的数字：粘贴 1,234,234,234 会按字段所在区域设置解析，失去焦点时提交为 1234234234。输入过程中不会拦截按键。
Set min, max, and step to guide users toward valid values.
Show units (e.g. "%" or "GB") so users know what the number represents.
Set isWheelEnabled={false} when the input appears in a scrolling surface where wheel gestures should always scroll the page.
避免：Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.
避免：Set both isOptional and isRequired on the same field.
避免：Wrap a disabled NumberInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-number-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled",
        "readonly"
      ]
    }
  ],
  "derived": [
    {
      "property": "padding",
      "expand": "container"
    },
    {
      "property": "borderRadius",
      "vars": [
        "--_field-radius"
      ]
    }
  ]
}

组件结构

Label: The label for the number input.
Description: Additional description text below the label.
Icon: An optional icon within the input.
Placeholder: Placeholder text shown when the input is empty.
Number steppers: Optional buttons that increment or decrement by the configured step.