数字输入框

数字输入框允许用户输入数字，并通过步进按钮增减数值。

View code

Age

功能特性

完整的键盘导航支持。
支持受控与非受控模式。
支持按钮长按和滚轮事件。
支持不同区域设置的数值系统。
可自定义格式化。

安装

安装数字包。

$ npm add @internationalized/number

通过命令行安装组件。

$ npm add reka-ui

结构

导入所有部件并进行组合。

vue

<script setup>
import { NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput, NumberFieldRoot } from 'reka-ui'
</script>

<template>
  <NumberFieldRoot>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldRoot>
</template>

API 参考

Root

包含数字输入框的所有部件。在 form 中使用时还会渲染 input 元素以确保事件正确传播。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`defaultValue`		`number`
`disabled`		`boolean` When `true`, prevents the user from interacting with the Number Field.
`disableWheelChange`		`boolean` When `true`, prevents the value from changing on wheel scroll.
`formatOptions`		`NumberFormatOptions` Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.
`id`		`string` Id of the element
`invertWheelChange`		`boolean` When `true`, inverts the direction of the wheel change.
`locale`		`string` The locale to use for formatting dates
`max`		`number` The largest value allowed for the input.
`min`		`number` The smallest value allowed for the input.
`modelValue`		`number \| null`
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`readonly`		`boolean` When `true`, the Number Field is read-only.
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`step`	`1`	`number` The amount that the input value changes with each increment or decrement "tick".
`stepSnapping`	`true`	`boolean` When `false`, prevents the value from snapping to the nearest increment of the step value

Emit	Payload
`update:modelValue`	`[val: number]` Event handler called when the value changes.

Slots (default)	Payload
`modelValue`	`number \| undefined`
`textValue`	`string`

Data Attribute	Value
`[data-disabled]`	禁用时出现

Input

输入框

根据值和格式选项渲染文本值的输入组件。

Prop	Default	Type
`as`	`'input'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-disabled]`	禁用时出现

Increment

用于增加值的按钮。

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`disabled`		`boolean`

Data Attribute	Value
`[data-pressed]`	按下时出现
`[data-disabled]`	禁用时出现

Decrement

用于减少值的按钮。

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`disabled`		`boolean`

Data Attribute	Value
`[data-pressed]`	按下时出现
`[data-disabled]`	禁用时出现

示例

小数

支持 Intl.NumberFormat 的所有选项，包括最小和最大小数位数、符号显示、分组分隔符等配置。

vue

<template>
  <NumberFieldRoot
    :default-value="5"
    :format-options="{
      signDisplay: 'exceptZero',
      minimumFractionDigits: 1,
    }"
  >
    …
  </NumberFieldRoot>
</template>

百分比

可将 formatOptions.style 设置为 percent 以将值视为百分比。此模式下需手动将步长设为 0.01 以允许合适的步进幅度。

vue

<template>
  <NumberFieldRoot
    :default-value="0.05"
    :step="0.01"
    :format-options="{
      style: 'percent',
    }"
  >
    …
  </NumberFieldRoot>
</template>

货币

可将 formatOptions.style 设置为 currency 以将值视为货币值。同时必须传入 currency 选项以设置货币代码（如 USD）。

若需允许用户更改货币，应在数字输入框旁添加独立的下拉菜单。数字输入框本身不会根据用户输入确定货币类型。

vue

<template>
  <NumberFieldRoot
    :default-value="5"
    :format-options="{
      style: 'currency',
      currency: 'EUR',
      currencyDisplay: 'code',
      currencySign: 'accounting',
    }"
  >
    …
  </NumberFieldRoot>
</template>

无障碍支持

遵循 Spinbutton WAI-ARIA 设计模式。

键盘交互

Key	Description
`↑`	增加数值
`↓`	减少数值
`Page Up`	以10倍幅度增加数值
`Page Down`	以10倍幅度减少数值
`Home`	将值设为最小值（若提供 `min` 参数）
`End`	将值设为最大值（若提供 `max` 参数）

数字输入框 ​

功能特性 ​

安装 ​

结构 ​

API 参考 ​

Root ​

Input ​

Increment ​

Decrement ​

示例 ​

小数 ​

百分比 ​

货币 ​

无障碍支持 ​

键盘交互 ​