NumberInput 数字输入框
用于录入数字的文本框，内置了长按加减按钮连续滚动的逻辑，并支持最大值、最小值、精度步长调整。
预览
步进点击时播放机械咔哒声（首次交互后生效）
安装
pnpm dlx brutx-vue@latest add number-input用法
<script setup>
import { ref } from 'vue'
import { NumberInput } from 'brutx-ui-vue'
const count = ref(5)
</script>
<template>
<NumberInput v-model="count" :min="0" :max="10" :step="1" />
</template>变体
NumberInput 提供两种按钮排版形态，通过 layout 属性配置：
| 布局属性 | 排版说明 |
|---|---|
split (默认) | 双侧分立式：减号按钮在输入框左侧，加号按钮在右侧，极具粗野对称感。 |
stacked | 右侧堆叠式：加减上下按钮成组排列在右边。 |
<template>
<!-- 分立式 -->
<NumberInput v-model="count" layout="split" />
<!-- 堆叠式 -->
<NumberInput v-model="count" layout="stacked" />
</template>边框样式变体
通过 variant 属性设置不同的边框样式，用于表单验证状态反馈：
| 变体 | 说明 |
|---|---|
default | 标准边框 |
error | 错误边框，聚焦时使用危险色阴影 |
success | 成功边框，聚焦时使用成功色阴影 |
<template>
<NumberInput v-model="count" variant="default" />
<NumberInput v-model="count" variant="error" />
<NumberInput v-model="count" variant="success" />
</template>API 参考
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
layout | "stacked" | "split" | undefined | "split" | 设置加减按钮相对输入框的布局方式。 |
详情声明类型"stacked" | "split" | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
variant | "default" | "success" | "error" | undefined | "default" | 设置默认、成功或错误边框状态。 |
详情声明类型"default" | "success" | "error" | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
errorMessage | string | undefined | undefined | 错误变体下显示并关联到输入控件的错误说明。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
placeholder | string | undefined | undefined | 输入值为空时显示的占位文本；未提供时使用当前语言的默认文案。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
class | string | undefined | undefined | 追加到数字输入组件容器的自定义 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
iconSize | IconSize | undefined | "md" | 设置加号和减号图标的尺寸。 |
详情声明类型IconSize | undefined 字面量
关联类型 IconSize 类型定义 — IconSizeexport type IconSize = NonNullable<VariantProps<typeof iconSizeVariants>['size']> 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
sound | boolean | undefined | false | 启用步进操作时由 Web Audio 合成的点击音效。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
defaultValue | number | undefined | — | 非受控模式下组件首次使用的数字值。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
modelValue可空 | number | null | undefined | — | 当前受控数值；null 表示空值，可通过 v-model 绑定。 |
详情声明类型number | null | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
min | number | undefined | — | 允许输入的最小数值，并限制向下调整的范围。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
max | number | undefined | — | 允许输入的最大数值，并限制向上调整的范围。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
step | number | undefined | — | 每次点击加减按钮时调整的数值幅度。 |
详情声明类型number | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
stepSnapping | boolean | undefined | — | 是否将输入值对齐到 step 的整数倍。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
focusOnChange | boolean | undefined | — | 值因步进操作变化后是否自动聚焦输入框。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
formatOptions | Intl.NumberFormatOptions | undefined | — | 传递给 Intl.NumberFormat 的格式选项，用于数值显示与本地化输入解析。 |
详情声明类型Intl.NumberFormatOptions | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
locale | string | undefined | — | 指定数字格式化和输入解析所用的区域设置。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
disabled | boolean | undefined | — | 禁用输入框和加减按钮。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
readonly | boolean | undefined | — | 禁止直接编辑数值，但不等同于禁用组件。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
disableWheelChange | boolean | undefined | — | 阻止鼠标滚轮改变当前数值。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
invertWheelChange | boolean | undefined | — | 反转鼠标滚轮方向与数值增减方向的对应关系。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
id | string | undefined | — | 传递给内部输入控件的 DOM id。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
asChild | boolean | undefined | — | 启用组合模式，将组件属性和行为合并到唯一子元素。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
as | AsTag | Component | undefined | — | 指定根元素渲染使用的标签或 Vue 组件。 |
详情声明类型AsTag | Component | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
name | string | undefined | — | 内部表单控件的字段名称，用于表单提交。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
required | boolean | undefined | — | 将内部输入控件标记为必填字段。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/number-input/NumberInput.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@update:modelValue | [val: number] | 用户输入或步进调整产生新数值时发出，用于更新 v-model。 |
详情声明类型[val: number] 来源packages/ui/src/components/number-input/NumberInput.vue | ||
可访问性
- 键盘操作：输入框支持 Tab 键聚焦，加减按钮支持 Enter/Space 键触发，支持方向键 Up/Down 微调数值
- ARIA 属性：加减按钮自动设置
aria-label（如"增加"/"减少"），输入框设置aria-valuemin、aria-valuemax、aria-valuenow属性 - 表单集成：支持
name、required、disabled、readonly等原生表单属性，与表单验证兼容 - 焦点管理：
focusOnChange属性控制值变化时是否自动聚焦，disabled状态下禁止所有交互 - 动效与音效降级：数值变化触发的 Drum Ticker 滚轮微动效在
prefers-reduced-motion下自动停用；sound音效遵循浏览器自动播放策略，未交互前不发声