> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# HeadlessInputNumber

无样式组件`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

提供数值输入的解析、格式化与约束逻辑，不绑定产品视觉。

## 何时使用

需要完全自定义数值输入外观，同时复用可靠的数值行为时使用 HeadlessInputNumber。

**推荐**

- 明确配置小数位与分隔符。
- 显示值与提交值保持可预测转换。

**避免**

- 不需要自定义视觉时优先使用 InputNumber。

## 代码演示


### 基础用法
```tsx preview
import { HeadlessInputNumber } from '@rockshin/tao-ui';
import { useState } from 'react';

function HeadlessInputNumberExample() {
  const [value, setValue] = useState('');

  return (
    <HeadlessInputNumber
      value={value}
      onChange={setValue}
      prefix="$"
      decimalPlaces={2}
      thousandsSeparator=","
      placeholder="Enter amount"
    />
  );
}

export default HeadlessInputNumberExample;
```

### 格式化与前后缀
```tsx preview
import { HeadlessInputNumber, Stack } from '@rockshin/tao-ui';

function HeadlessNumberFormats() {
  return (
    <Stack gap="md">
      <HeadlessInputNumber
        defaultValue="1234567.5"
        prefix="$"
        suffix="USD"
        decimalPlaces={2}
        thousandsSeparator=","
      />
      <HeadlessInputNumber
        defaultValue="0.275"
        isPercentage
        suffix="%"
        decimalPlaces={1}
      />
    </Stack>
  );
}

export default HeadlessNumberFormats;
```

### 本地化分隔符与范围
```tsx preview
import { HeadlessInputNumber, Stack } from '@rockshin/tao-ui';

function HeadlessNumberConstraints() {
  return (
    <Stack gap="md">
      <HeadlessInputNumber
        defaultValue="1234.5"
        thousandsSeparator="."
        decimalSeparator=","
        decimalPlaces={2}
      />
      <HeadlessInputNumber
        defaultValue="50"
        min={0}
        max={100}
        suffix=" units"
      />
    </Stack>
  );
}

export default HeadlessNumberConstraints;
```

### 千位分隔
配置千位与小数分隔符，同时观察显示内容和实际输出值。
```tsx preview
import { useState } from 'react';

import { HeadlessInputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function HeadlessInputNumberWithThousandSeparator() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    placeholder: 'Try 1234567',
    decimalPlaces: 2,
    thousandsSeparator: ',',
    decimalSeparator: '.',
  };
  return <ControlledWrapper {...args} />;
}
```

### 前后缀格式
为无样式输入配置单位或货币标识，组件仍负责数值处理。
```tsx preview
import { useState } from 'react';

import { HeadlessInputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function HeadlessInputNumberWithPrefixSuffix() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    prefix: '$',
    suffix: 'USD',
    decimalPlaces: 2,
  };
  return <ControlledWrapper {...args} />;
}
```

### 百分比数值
使用百分号和小数精度；业务层自行定义百分比换算规则。
```tsx preview
import { useState } from 'react';

import { HeadlessInputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function HeadlessInputNumberPercentage() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    isPercentage: true,
    decimalPlaces: 2,
    suffix: '%',
    placeholder: 'Type 50 → actual is 0.5',
  };
  return <ControlledWrapper {...args} />;
}
```

### 允许负数
启用负数输入，比较输入中的中间态与完整数值。
```tsx preview
import { useState } from 'react';

import { HeadlessInputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function HeadlessInputNumberAllowNegative() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    allowNegative: true,
    placeholder: 'Type -123.45',
  };
  return <ControlledWrapper {...args} />;
}
```

### 范围限制
通过上下限控制可接受值，观察失焦时的处理。
```tsx preview
import { useState } from 'react';

import { HeadlessInputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function HeadlessInputNumberClampedRange() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    min: 0,
    max: 100,
    decimalPlaces: 0,
    placeholder: 'Type 999, blur to clamp to 100',
  };
  return <ControlledWrapper {...args} />;
}
```

### 失焦补齐小数
输入完成后按指定精度补齐小数位。
```tsx preview
import { useState } from 'react';

import { HeadlessInputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function HeadlessInputNumberPadOnBlurAlways() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    padDecimalsOnBlur: 'always',
    decimalPlaces: 2,
    placeholder: 'Type 5, blur to see 5.00',
  };
  return <ControlledWrapper {...args} />;
}
```

### 本地化分隔符
将点号作为千位分隔符、逗号作为小数分隔符。
```tsx preview
import { useState } from 'react';

import { HeadlessInputNumber } from '@rockshin/tao-ui';

function ControlledWrapper(
  props: React.ComponentProps<typeof HeadlessInputNumber>,
) {
  const [value, setValue] = useState((props.value as string | undefined) ?? '');
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 12,
        minWidth: 0,
        width: '100%',
        maxWidth: 320,
      }}
    >
      <HeadlessInputNumber
        {...props}
        value={value}
        onChange={(v) => {
          setValue(v);
          props.onChange?.(v);
        }}
      />
      <code
        style={{
          background: 'var(--tao-color-bg-container)',
          padding: 8,
          borderRadius: 4,
        }}
      >
        actual value: {JSON.stringify(value)}
      </code>
    </div>
  );
}

export default function HeadlessInputNumberEuropeanLocale() {
  const args: React.ComponentProps<typeof HeadlessInputNumber> = {
    decimalSeparator: ',',
    thousandsSeparator: '.',
    decimalPlaces: 2,
    placeholder: '1.234,56',
  };
  return <ControlledWrapper {...args} />;
}
```

## 地区格式

地区分组、小数符号和数字字符继承 `TaoProvider.locale.numberLocale`，也可用组件 `locale="fr-FR"` 覆盖。显式分隔符优先；数字输入在本地化显示的同时保留规范 ASCII 字符串及精度。

## API


### [#](#headlessinputnumber)HeadlessInputNumber



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| className | 节点类名 | `string | undefined` | `-` |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |



### [#](#numberinput)NumberInput



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| className | 节点类名 | `string | undefined` | `-` |
| locale | BCP 47 locale. Defaults to the provider's number locale. | `string | undefined` | `-` |

