Skip to content
Lenso UI

NumberField 数字输入框

数字输入字段，包含增减按钮、校验与国际化格式化能力。

用法

import { NumberField } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";
// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Label, NumberField, TextField } from "@lenso/ui";import { Controls, styles } from "./parts";
export function Basic() {  return (    <TextField name="width" xstyle={styles.field}>      <NumberField defaultValue={1024} min={0} name="width">        <Label>Width</Label>        <Controls />      </NumberField>    </TextField>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

import {NumberField, Label, Description, FieldError} from '@lenso/ui';
export default () => (  <NumberField>    <Label />    <NumberField.Group>      <NumberField.DecrementButton />      <NumberField.Input />      <NumberField.IncrementButton />    </NumberField.Group>    <Description />    <FieldError />  </NumberField>)

NumberField 允许用户输入数值，并可选择是否显示增减按钮。它支持国际化格式化、校验与键盘导航。

示例

变体

NumberField 组件支持两种视觉变体：

  • primary（默认）— 带阴影的标准样式，适用于大多数场景
  • secondary — 低强调、无阴影，适合在 Surface 等表面背景上使用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
export function Variants() {  return (    <div {...stylex.props(styles.column)}>      {(["primary", "secondary"] as const).map((variant) => (        <TextField key={variant} name={`${variant}-width`}>          <NumberField defaultValue={100} min={0} name={`${variant}-width`} variant={variant}>            <Label>{variant === "primary" ? "Primary variant" : "Secondary variant"}</Label>            <Controls />          </NumberField>        </TextField>      ))}    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表面样式

在 Surface 内使用时，请使用 variant="secondary"，以应用适合表面背景的低强调变体。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, Label, NumberField, Surface, TextField } from "@lenso/ui";import { Controls, styles } from "./parts";
export function OnSurface() {  return (    <Surface xstyle={styles.surface}>      <TextField name="width">        <NumberField defaultValue={1024} min={0} name="width" variant="secondary">          <Label>Width</Label>          <Controls fullWidth />          <Description>Enter the width in pixels</Description>        </NumberField>      </TextField>      <TextField name="percentage">        <NumberField          defaultValue={0.5}          format={{ style: "percent" }}          min={0}          max={1}          name="percentage"          step={0.1}          variant="secondary"        >          <Label>Percentage</Label>          <Controls fullWidth />          <Description>Value must be between 0 and 100</Description>        </NumberField>      </TextField>    </Surface>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带描述

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
export function WithDescription() {  return (    <div {...stylex.props(styles.column)}>      <TextField name="width">        <NumberField defaultValue={1024} min={0} name="width">          <Label>Width</Label>          <Controls />          <Description>Enter the width in pixels</Description>        </NumberField>      </TextField>      <TextField name="percentage">        <NumberField          defaultValue={0.5}          format={{ style: "percent" }}          min={0}          max={1}          name="percentage"          step={0.1}        >          <Label>Percentage</Label>          <Controls />          <Description>Value must be between 0 and 100</Description>        </NumberField>      </TextField>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

必填字段

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
export function Required() {  return (    <div {...stylex.props(styles.column)}>      <TextField name="quantity">        <NumberField required min={0} name="quantity">          <Label required>Quantity</Label>          <Controls />        </NumberField>      </TextField>      <TextField name="rating">        <NumberField required defaultValue={1} min={1} max={10} name="rating">          <Label required>Rating</Label>          <Controls />          <Description>Rate from 1 to 10</Description>        </NumberField>      </TextField>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

禁用状态

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
export function Disabled() {  return (    <div {...stylex.props(styles.column)}>      <TextField disabled name="width">        <NumberField disabled defaultValue={1024} min={0} name="width">          <Label>Width</Label>          <Controls />          <Description>Enter the width in pixels</Description>        </NumberField>      </TextField>      <TextField disabled name="percentage">        <NumberField          disabled          defaultValue={0.5}          format={{ style: "percent" }}          min={0}          max={1}          name="percentage"          step={0.1}        >          <Label>Percentage</Label>          <Controls />          <Description>Value must be between 0 and 100</Description>        </NumberField>      </TextField>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

宽度充满

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "./parts";
export function FullWidth() {  return (    <div {...stylex.props(styles.wide)}>      <TextField name="width" fullWidth>        <NumberField fullWidth defaultValue={1024} min={0} name="width">          <Label>Width</Label>          <NumberField.Group>            <NumberField.DecrementButton />            <NumberField.Input />            <NumberField.IncrementButton />          </NumberField.Group>        </NumberField>      </TextField>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表单校验

将 isInvalid 与 FieldError 配合使用，以展示校验消息。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { FieldError, Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
export function Validation() {  return (    <div {...stylex.props(styles.column)}>      <TextField invalid name="quantity">        <NumberField required min={0} name="quantity" value={-5} allowOutOfRange>          <Label required>Quantity</Label>          <Controls />          <FieldError match>Quantity must be greater than or equal to 0</FieldError>        </NumberField>      </TextField>      <TextField invalid name="percentage">        <NumberField          format={{ style: "percent" }}          min={0}          max={1}          name="percentage"          step={0.1}          value={1.5}          allowOutOfRange        >          <Label>Percentage</Label>          <Controls />          <FieldError match>Percentage must be between 0 and 100</FieldError>        </NumberField>      </TextField>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

控制 value 以与其他组件同步或执行自定义格式化。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Button, Description, Label, NumberField, TextField } from "@lenso/ui";import { useState } from "react";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
export function Controlled() {  const [value, setValue] = useState<number | null>(1024);  return (    <div {...stylex.props(styles.column)}>      <TextField name="width">        <NumberField min={0} name="width" value={value} onValueChange={setValue}>          <Label>Width</Label>          <Controls />          <Description>Current value: {value}</Description>        </NumberField>      </TextField>      <div {...stylex.props(styles.row)}>        <Button variant="tertiary" onClick={() => setValue(0)}>          Reset to 0        </Button>        <Button variant="tertiary" onClick={() => setValue(2048)}>          Set to 2048        </Button>      </div>    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

步进值

配置增减步进值以实现精确控制。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
export function WithStep() {  return (    <div {...stylex.props(styles.column)}>      {[1, 5, 10].map((step) => (        <TextField key={step} name={`step${step}`}>          <NumberField defaultValue={0} min={0} max={100} step={step} name={`step${step}`}>            <Label>Step: {step}</Label>            <Controls />            <Description>Increments by {step}</Description>          </NumberField>        </TextField>      ))}    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

格式化选项

支持将数字格式化为货币、百分比、小数或单位，并具备国际化能力。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { Controls, styles } from "./parts";
const formats: {  name: string;  label: string;  description: string;  value: number;  format: Intl.NumberFormatOptions;  max?: number;  step?: number;}[] = [  {    name: "currency-eur",    label: "Currency (EUR - Accounting)",    description: "Accounting format with EUR currency",    value: 99,    format: { currency: "EUR", currencySign: "accounting", style: "currency" },  },  {    name: "currency-usd",    label: "Currency (USD)",    description: "Standard USD currency format",    value: 99.99,    format: { currency: "USD", style: "currency" },  },  {    name: "percentage",    label: "Percentage",    description: "Percentage format (0-1, where 0.5 = 50%)",    value: 0.5,    format: { style: "percent" },    max: 1,    step: 0.01,  },  {    name: "decimal",    label: "Decimal (2 decimal places)",    description: "Decimal format with 2 decimal places",    value: 1234.56,    format: { maximumFractionDigits: 2, minimumFractionDigits: 2, style: "decimal" },  },  {    name: "unit",    label: "Unit (Kilograms)",    description: "Unit format with kilograms",    value: 1000,    format: { style: "unit", unit: "kilogram", unitDisplay: "short" },  },];
export function WithFormatOptions() {  return (    <div {...stylex.props(styles.column)}>      {formats.map((item) => (        <TextField key={item.name} name={item.name}>          <NumberField            defaultValue={item.value}            min={0}            max={item.max}            name={item.name}            format={item.format}            step={item.step}          >            <Label>{item.label}</Label>            <Controls />            <Description>{item.description}</Description>          </NumberField>        </TextField>      ))}    </div>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表单示例

完整的表单集成示例，包含校验与提交处理。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import {  Button,  Description,  FieldError,  Form,  Label,  NumberField,  Spinner,  TextField,} from "@lenso/ui";import { useState, type FormEvent } from "react";import { Controls, styles } from "./parts";
export function FormExample() {  const [value, setValue] = useState<number | null>(null);  const [isSubmitting, setIsSubmitting] = useState(false);  const stockAvailable = 3;  const isOutOfStock = value !== null && value > stockAvailable;  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {    event.preventDefault();    if (value === null || value < 1 || value > stockAvailable || isSubmitting) return;    setIsSubmitting(true);    setTimeout(() => {      console.log("Order submitted:", { quantity: value });      setValue(null);      setIsSubmitting(false);    }, 1500);  };  return (    <Form xstyle={styles.form} onSubmit={handleSubmit}>      <TextField name="quantity" invalid={isOutOfStock} validationMode="onChange">        <NumberField          required          min={1}          max={5}          name="quantity"          value={value}          onValueChange={setValue}        >          <Label required>Order quantity</Label>          <Controls />          {isOutOfStock ? (            <FieldError match>Only {stockAvailable} items left in stock</FieldError>          ) : (            <Description>Only {stockAvailable} items available</Description>          )}        </NumberField>      </TextField>      <Button        xstyle={styles.full}        disabled={value === null || value < 1 || value > stockAvailable}        isLoading={isSubmitting}        type="submit"        variant="primary"      >        {isSubmitting ? (          <>            <Spinner color="current" size="sm" />            Processing...          </>        ) : (          "Place Order"        )}      </Button>    </Form>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带校验

通过受控 value 实现自定义校验逻辑。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, FieldError, Label, NumberField, TextField } from "@lenso/ui";import { useState } from "react";import { Controls, styles } from "./parts";
export function WithValidation() {  const [value, setValue] = useState<number | null>(null);  const isInvalid = value !== null && (value < 0 || value > 1);  return (    <TextField      invalid={isInvalid}      name="percentage"      validationMode="onChange"      xstyle={styles.field}    >      <NumberField        required        format={{ style: "percent" }}        min={0}        max={1}        name="percentage"        step={0.1}        value={value}        onValueChange={setValue}        allowOutOfRange      >        <Label required>Percentage</Label>        <Controls />        {isInvalid ? (          <FieldError match>Percentage must be between 0 and 100</FieldError>        ) : (          <Description>Enter a value between 0 and 100</Description>        )}      </NumberField>    </TextField>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义图标

自定义增减按钮图标。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Description, Label, NumberField, TextField } from "@lenso/ui";import { styles } from "./parts";
export function CustomIcons() {  return (    <TextField name="width" xstyle={styles.field}>      <NumberField defaultValue={1024} min={0} name="width">        <Label>Width (Custom Icons)</Label>        <NumberField.Group>          <NumberField.DecrementButton>            <svg              aria-hidden="true"              height="16"              viewBox="0 0 16 16"              width="16"              xmlns="http://www.w3.org/2000/svg"            >              <path                clipRule="evenodd"                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m-2-6.5a.75.75 0 0 0 0 1.5h4a.75.75 0 0 0 0-1.5z"                fill="currentColor"                fillRule="evenodd"              />            </svg>          </NumberField.DecrementButton>          <NumberField.Input xstyle={styles.input} />          <NumberField.IncrementButton>            <svg              aria-hidden="true"              height="16"              viewBox="0 0 16 16"              width="16"              xmlns="http://www.w3.org/2000/svg"            >              <path                clipRule="evenodd"                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m.75-7.75a.75.75 0 0 0-1.5 0V6H4.75a.75.75 0 0 0 0 1.5H6v1.25a.75.75 0 0 0 1.5 0V7.5h1.25a.75.75 0 0 0 0-1.5H7.5z"                fill="currentColor"                fillRule="evenodd"              />            </svg>          </NumberField.IncrementButton>        </NumberField.Group>        <Description>Custom icon children</Description>      </NumberField>    </TextField>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

步进箭头

使用垂直布局的 chevron 图标，呈现不同的视觉风格。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Label, NumberField, TextField } from "@lenso/ui";import * as stylex from "@stylexjs/stylex";import { styles } from "./parts";
export function WithChevrons() {  return (    <TextField name="amount" xstyle={styles.field}>      <NumberField        defaultValue={99}        min={0}        name="amount"        format={{ currency: "EUR", currencySign: "accounting", style: "currency" }}      >        <Label>Number field with chevrons</Label>        <NumberField.Group>          <NumberField.Input xstyle={styles.flexInput} />          <div {...stylex.props(styles.chevrons)}>            <NumberField.IncrementButton xstyle={[styles.chevronButton, styles.up]}>              <svg                aria-hidden="true"                height="11"                viewBox="0 0 16 16"                width="11"                xmlns="http://www.w3.org/2000/svg"              >                <path                  clipRule="evenodd"                  d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 1 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06"                  fill="currentColor"                  fillRule="evenodd"                />              </svg>            </NumberField.IncrementButton>            <NumberField.DecrementButton xstyle={[styles.chevronButton, styles.down]}>              <svg                aria-hidden="true"                height="11"                viewBox="0 0 16 16"                width="11"                xmlns="http://www.w3.org/2000/svg"              >                <path                  clipRule="evenodd"                  d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06"                  fill="currentColor"                  fillRule="evenodd"                />              </svg>            </NumberField.DecrementButton>          </div>        </NumberField.Group>      </NumberField>    </TextField>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Label, NumberField, TextField } from "@lenso/ui";import { Controls, styles } from "./parts";
export function RenderFunction() {  return (    <TextField name="width" xstyle={styles.field}>      <NumberField        defaultValue={1024}        min={0}        name="width"        render={(props) => <div {...props} data-custom="foo" />}      >        <Label>Width</Label>        <Controls />      </NumberField>    </TextField>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";// Adapted from HeroUI v3.2.6 (e385ac202b2cdb94b1bf6fa76d32c31c8259cc5e), Apache-2.0.import { Label, NumberField, TextField } from "@lenso/ui";import { styles } from "./parts";
export function CustomStyles() {  return (    <TextField name="guests" xstyle={styles.guests}>      <NumberField defaultValue={2} min={1} name="guests" variant="secondary">        <Label xstyle={styles.label}>Guests</Label>        <NumberField.Group xstyle={styles.customGroup}>          <NumberField.DecrementButton xstyle={styles.customButton} />          <NumberField.Input xstyle={styles.customInput} />          <NumberField.IncrementButton xstyle={styles.customButton} />        </NumberField.Group>      </NumberField>    </TextField>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

若要自定义组件类，可使用 @layer components 指令。了解更多。

@layer components {  .number-field {    @apply flex flex-col gap-1;  }
  /* When invalid, the description is hidden automatically */  .number-field[data-invalid="true"] [data-slot="description"],  .number-field[aria-invalid="true"] [data-slot="description"] {    @apply hidden;  }
  .number-field__group {    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;  }
  .number-field__input {    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 tabular-nums;  }
  .number-field__increment-button,  .number-field__decrement-button {    @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent;  }}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

基础类 [!toc]

  • .number-field – 根容器，样式非常克制（flex flex-col gap-1）
  • .number-field__group – 输入与按钮的容器，包含边框与背景样式
  • .number-field__input – 数字输入字段
  • .number-field__increment-button – 用于增加数值的按钮
  • .number-field__decrement-button – 用于减少数值的按钮

变体类 [!toc]

  • .number-field--primary – 带阴影的主变体（默认）
  • .number-field--secondary – 无阴影的次变体，适合用在 surface 上

说明： 子组件（Label、Description、FieldError）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。

交互状态

NumberField 会根据状态自动管理以下 data 属性：

  • Invalid：[data-invalid="true"] 或 [aria-invalid="true"] – 无效时会自动隐藏 description 插槽
  • Disabled：[data-disabled="true"] – 当 isDisabled 为 true 时应用
  • Focus Within：[data-focus-within="true"] – 当输入框或按钮聚焦时应用
  • Focus Visible：[data-focus-visible="true"] – 当焦点可见（键盘导航）时应用
  • Hovered：[data-hovered="true"] – 当悬停在按钮上时应用

更多属性可通过渲染 prop 获得（见下方的 NumberFieldRenderProps）。

API 参考

NumberField

NumberField 继承 React Aria NumberField 组件的全部 props。

Base Props

Prop类型默认值描述
childrenReact.ReactNode | (values: NumberFieldRenderProps) => React.ReactNode-子组件（Label、Group、Input 等）或渲染函数。
classNamestring | (values: NumberFieldRenderProps) => string-用于样式的 CSS 类，支持渲染 prop。
styleReact.CSSProperties | (values: NumberFieldRenderProps) => React.CSSProperties-行内样式，支持渲染 prop。
fullWidthbooleanfalse数字字段是否占满容器宽度
idstring-元素的唯一标识符。
variant"primary" | "secondary""primary"组件的视觉变体。primary 为默认带阴影样式。secondary 为低强调、无阴影变体，适合用在 surface 上。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, NumberFieldRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

Value Props

Prop类型默认值描述
valuenumber-当前值（受控）。
defaultValuenumber-默认值（非受控）。
onChange(value: number | undefined) => void-值变化时触发的事件处理函数。

Formatting Props

Prop类型默认值描述
formatOptionsIntl.NumberFormatOptions-数字格式化选项（货币、百分比、小数、单位等）。
localestring-数字格式化的区域设置。

Validation Props

Prop类型默认值描述
isRequiredbooleanfalse提交表单前是否要求用户输入。
isInvalidboolean-当前值是否无效。
validate(value: number) => ValidationError | true | null | undefined-自定义校验函数。
validationBehavior'native' | 'aria''native'使用原生 HTML 表单校验或 ARIA 属性。
validationErrorsstring[]-服务端校验错误。

Range Props

Prop类型默认值描述
minValuenumber-允许的最小值。
maxValuenumber-允许的最大值。
stepnumber1增减操作的步进值。

State Props

Prop类型默认值描述
isDisabledboolean-是否禁用输入。
isReadOnlyboolean-是否可选中但不可修改。

Form Props

Prop类型默认值描述
namestring-input 元素的名称，用于 HTML 表单提交。
autoFocusboolean-元素渲染后是否应获得焦点。

Accessibility Props

Prop类型默认值描述
aria-labelstring-没有可见标签时的无障碍标签。
aria-labelledbystring-用于标注该字段的元素 ID。
aria-describedbystring-用于描述该字段的元素 ID。
aria-detailsstring-包含更多详情的元素 ID。

Composition Components

NumberField 需要与以下独立组件组合使用，请分别导入并直接使用：

  • NumberField.Group – 输入与按钮的容器
  • NumberField.Input – 数字输入字段
  • NumberField.IncrementButton – 用于增加数值的按钮
  • NumberField.DecrementButton – 用于减少数值的按钮
  • Label – 字段标签组件（@lenso/ui）
  • Description – 辅助说明文本组件（@lenso/ui）
  • FieldError – 校验错误信息组件（@lenso/ui）

这些组件各自拥有 props API。请直接在 NumberField 内组合使用：

<NumberField isRequired isInvalid={hasError} minValue={0} maxValue={100}>  <Label>Quantity</Label>  <NumberField.Group>    <NumberField.DecrementButton />    <NumberField.Input />    <NumberField.IncrementButton />  </NumberField.Group>  <Description>Enter a value between 0 and 100</Description>  <FieldError>Value must be between 0 and 100</FieldError></NumberField>

NumberField.Group Props

NumberField.Group 继承 React Aria Group 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode | (values: GroupRenderProps) => React.ReactNode-子组件（Input、Buttons）或渲染函数。
classNamestring | (values: GroupRenderProps) => string-用于样式的 CSS 类。

NumberField.Input Props

NumberField.Input 继承 React Aria Input 组件的 props。

Prop类型默认值描述
classNamestring-用于样式的 CSS 类。
variant"primary" | "secondary""primary"输入的视觉变体。primary 为默认带阴影样式。secondary 为低强调、无阴影变体，适合用在 surface 上。

NumberField.IncrementButton Props

NumberField.IncrementButton 继承 React Aria Button 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode<IconPlus />按钮的图标或内容。默认为加号图标。
classNamestring-用于样式的 CSS 类。
slot"increment""increment"必须设置为 "increment"（会自动设置）。

NumberField.DecrementButton Props

NumberField.DecrementButton 继承 React Aria Button 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode<IconMinus />按钮的图标或内容。默认为减号图标。
classNamestring-用于样式的 CSS 类。
slot"decrement""decrement"必须设置为 "decrement"（会自动设置）。

NumberFieldRenderProps

在 className、style 或 children 上使用渲染 prop 时，可使用以下值：

Prop类型描述
isDisabledboolean字段是否禁用。
isInvalidboolean字段当前是否无效。
isReadOnlyboolean字段是否只读。
isRequiredboolean字段是否必填。
isFocusedboolean字段是否聚焦（已弃用，请使用 isFocusWithin）。
isFocusWithinboolean是否有任意子元素聚焦。
isFocusVisibleboolean是否为可见焦点（键盘导航）。
valuenumber | undefined当前值。
minValuenumber | undefined允许的最小值。
maxValuenumber | undefined允许的最大值。
stepnumber增减步进值。

相关案例

See upstream NumberField showcases. Product showcases are not part of the local component runtime.

相关组件

Label 标签

渲染与表单控件关联的无障碍标签。

Description 描述

为表单字段及其他组件提供补充说明文本

FieldError 字段错误

展示表单字段校验错误消息