HeadlessInputNumber#
无样式组件
@rockshin/tao-ui提供数值输入的解析、格式化与约束逻辑,不绑定产品视觉。
#何时使用
需要完全自定义数值输入外观,同时复用可靠的数值行为时使用 HeadlessInputNumber。
推荐
- 明确配置小数位与分隔符。
- 显示值与提交值保持可预测转换。
避免
- 不需要自定义视觉时优先使用 InputNumber。
#代码演示
#基础用法
$
TSX
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;#格式化与前后缀
$USD%
TSX
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;#本地化分隔符与范围
units
TSX
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;#千位分隔
配置千位与小数分隔符,同时观察显示内容和实际输出值。
actual value: ""TSX
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} />;
}#前后缀格式
为无样式输入配置单位或货币标识,组件仍负责数值处理。
$USD
actual value: ""TSX
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} />;
}#百分比数值
使用百分号和小数精度;业务层自行定义百分比换算规则。
%
actual value: ""TSX
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} />;
}#允许负数
启用负数输入,比较输入中的中间态与完整数值。
actual value: ""TSX
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} />;
}#范围限制
通过上下限控制可接受值,观察失焦时的处理。
actual value: ""TSX
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} />;
}#失焦补齐小数
输入完成后按指定精度补齐小数位。
actual value: ""TSX
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} />;
}#本地化分隔符
将点号作为千位分隔符、逗号作为小数分隔符。
actual value: ""TSX
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 字符串及精度。