InputNumber 数字输入框
只能输入数字的输入框,带加减按钮。用来填数量、价格、百分比这类数值,可以限制范围、步长和小数位数。
引入
import { NsInputNumber } from '@ns/ui'
基础用法
用 v-model 绑定一个数字。点两侧的加减按钮、聚焦后按上下键都可以加减一步;按住按钮超过 0.3 秒会连续加减。直接输入时,按回车或输入框失焦才提交,打字过程中不改绑定值。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber } from '@ns/ui'
const count = ref<number | undefined>(1)
</script>
<template>
<NsInputNumber v-model="count" style="width: 200px" />
<p style="margin-top: 12px">绑定值:{{ count }}</p>
</template>
范围
min、max 限制取值范围。到达边界时对应的按钮变灰;输入超出范围的数字,提交时会被截到边界上。下面的范围是 1 到 10,点到 10 时加号变灰,输入 100 回车会变成 10。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber } from '@ns/ui'
const count = ref<number | undefined>(9)
</script>
<template>
<NsInputNumber v-model="count" :min="1" :max="10" style="width: 200px" />
<p style="margin-top: 12px">绑定值:{{ count }}(范围 1 到 10)</p>
</template>
步长
step 是每次加减的量,可以是小数。加减时按“当前值和步长中较长的小数位数”取整,连点三次 0.1 得到的是 0.3,不会出现 0.30000000000000004。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber, NsSpace } from '@ns/ui'
const count = ref<number | undefined>(0)
const ratio = ref<number | undefined>(0)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">step = 5</span>
<NsInputNumber v-model="count" :step="5" style="width: 200px" />
<span>{{ count }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">step = 0.1</span>
<NsInputNumber v-model="ratio" :step="0.1" style="width: 200px" />
<span>{{ ratio }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 80px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
精度
precision 指定保留几位小数:显示时补齐位数(1.5 显示成 1.50),提交和加减的结果也四舍五入到这个位数。precision 为 0 时只能是整数,输入 2.6 回车会变成 3。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber, NsSpace } from '@ns/ui'
const integer = ref<number | undefined>(2)
const price = ref<number | undefined>(1.5)
const rate = ref<number | undefined>(0.125)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">precision = 0</span>
<NsInputNumber v-model="integer" :precision="0" style="width: 200px" />
<span>绑定值:{{ integer }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">precision = 2</span>
<NsInputNumber v-model="price" :precision="2" :step="0.1" style="width: 200px" />
<span>绑定值:{{ price }}</span>
</NsSpace>
<NsSpace wrap>
<span class="row-label">precision = 3</span>
<NsInputNumber v-model="rate" :precision="3" :step="0.005" style="width: 200px" />
<span>绑定值:{{ rate }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 104px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
空值
绑定值可以是 undefined,这时显示 placeholder。删光输入框里的内容再回车或失焦,值会变回 undefined。空值时点加减或按上下键,从 0 起算一步,再限制到 [min, max] 内,比如 min 是 3 时点加号得到 3。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInputNumber, NsSpace } from '@ns/ui'
const count = ref<number>()
</script>
<template>
<NsSpace wrap>
<NsInputNumber v-model="count" :min="3" placeholder="请输入数量" style="width: 200px" />
<NsButton @click="count = undefined">清空</NsButton>
</NsSpace>
<p style="margin-top: 12px">绑定值:{{ count === undefined ? 'undefined' : count }}</p>
</template>
尺寸
size 可选 large、default、small,高度分别是 40、32、24px,字号 16、14、12px,圆角 8、6、4px,和同尺寸的 NsInput、NsButton 一致。两侧的加减按钮是正方形,宽 40、32、24px,图标 18、16、14px;controls-position="right" 时右侧按钮宽 30、24、18px,上下两个按钮各占一半高,箭头 14、12、10px。放在 NsForm 里且没传 size 时,跟随表单项或表单的尺寸。
下面每一行是一种尺寸:按钮在两侧、按钮在右侧,最后放一个同尺寸的按钮对比高度。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInputNumber, NsSpace } from '@ns/ui'
const count = ref<number | undefined>(1)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsInputNumber v-model="count" size="large" style="width: 180px" />
<NsInputNumber v-model="count" size="large" controls-position="right" style="width: 180px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsInputNumber v-model="count" style="width: 180px" />
<NsInputNumber v-model="count" controls-position="right" style="width: 180px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsInputNumber v-model="count" size="small" style="width: 180px" />
<NsInputNumber v-model="count" size="small" controls-position="right" style="width: 180px" />
<NsButton size="small">按钮</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
按钮位置
controls-position 可选 ''(默认,减号在左、加号在右)和 'right'(两个按钮上下叠放在右侧);:controls="false" 时不显示按钮,只能输入或用上下键。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber, NsSpace } from '@ns/ui'
const count = ref<number | undefined>(1)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">两侧('',默认)</span>
<NsInputNumber v-model="count" style="width: 200px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">右侧(right)</span>
<NsInputNumber v-model="count" controls-position="right" style="width: 200px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">不显示(controls 为 false)</span>
<NsInputNumber v-model="count" :controls="false" style="width: 200px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 184px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用和只读
disabled 禁用后不能输入、不能加减;readonly 只读时可以聚焦、复制,但不能输入和加减,加减按钮也变灰。在禁用的 NsForm 里也会被禁用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber, NsSpace } from '@ns/ui'
const count = ref<number | undefined>(1)
const empty = ref<number>()
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsInputNumber v-model="count" disabled style="width: 180px" />
<NsInputNumber v-model="count" controls-position="right" disabled style="width: 180px" />
<NsInputNumber v-model="empty" placeholder="占位文字" disabled style="width: 180px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsInputNumber v-model="count" readonly style="width: 180px" />
<NsInputNumber v-model="count" controls-position="right" readonly style="width: 180px" />
<NsInputNumber v-model="empty" placeholder="占位文字" readonly style="width: 180px" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
事件
change 和 update:modelValue 同时触发:点加减按钮、按上下键、长按连续加减时每变一次触发一次;直接输入时,回车或失焦提交、值有变化才触发。获得、失去焦点触发 focus、blur。
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber } from '@ns/ui'
const count = ref<number | undefined>(1)
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (value: number | undefined) => log(`change:${value}`)
</script>
<template>
<NsInputNumber
v-model="count"
style="width: 200px"
@change="onChange"
@focus="log('focus')"
@blur="log('blur')"
/>
<p style="margin-top: 12px">最近的事件(新的在前):{{ logs.join(',') || '还没有' }}</p>
</template>
校验状态
数字输入框没有单独的状态属性,出错的样子由所在的 NsFormItem 决定:校验不通过,或者给表单项传了 error 时,边框变成危险色,下面显示错误信息,内部的 <input> 带上 aria-invalid。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsForm, NsFormItem, NsInputNumber, NsSwitch } from '@ns/ui'
const showError = ref(true)
const model = reactive<{ count?: number; price?: number }>({ count: 0, price: undefined })
</script>
<template>
<NsSwitch v-model="showError" active-text="显示错误" />
<NsForm :model="model" label-width="80px" style="margin-top: 16px" @submit.prevent>
<NsFormItem label="数量" :error="showError ? '数量至少是 1' : ''">
<NsInputNumber v-model="model.count" style="width: 200px" />
</NsFormItem>
<NsFormItem label="单价" :error="showError ? '请填写单价' : ''">
<NsInputNumber
v-model="model.price"
controls-position="right"
:precision="2"
placeholder="0.00"
style="width: 200px"
/>
</NsFormItem>
</NsForm>
</template>
调用方法
通过 ref 调用 focus()、blur(),或者用 inputRef 直接拿到内部的 <input> 元素。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInputNumber, NsSpace } from '@ns/ui'
const numberRef = ref<InstanceType<typeof NsInputNumber>>()
const count = ref<number | undefined>(128)
const focused = ref(false)
const selectAll = () => {
numberRef.value?.inputRef?.select()
}
</script>
<template>
<NsInputNumber
ref="numberRef"
v-model="count"
style="width: 200px"
@focus="focused = true"
@blur="focused = false"
/>
<div style="margin-top: 12px">
<NsSpace wrap>
<NsButton @click="numberRef?.focus()">聚焦</NsButton>
<NsButton @click="numberRef?.blur()">失焦</NsButton>
<NsButton @click="selectAll">选中数字(inputRef)</NsButton>
</NsSpace>
</div>
<p style="margin-top: 12px">输入框{{ focused ? '已聚焦' : '没有聚焦' }}</p>
</template>
键盘操作
聚焦输入框后,按 ↑ 加一步,按 ↓ 减一步。加减按钮不在 Tab 顺序里(tabindex="-1"),键盘用户用上下键操作。输入框的 role 是 spinbutton,并带有 aria-valuenow、aria-valuemin、aria-valuemax(没设 min、max 时不输出)。
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,失焦触发 blur 规则;表单项的 label 会通过 for 关联到输入框。规则里的 min、max 对数字按数值比较。不需要校验时设 :validate-event="false"。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsInputNumber } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive<{ count?: number }>({ count: undefined })
const rules: Record<string, FormRule[]> = {
count: [
{ required: true, message: '请填写数量', trigger: 'change' },
{ min: 1, max: 99, message: '数量在 1 到 99 之间', trigger: 'change' }
]
}
</script>
<template>
<NsForm :model="model" :rules="rules" @submit.prevent>
<NsFormItem label="数量" prop="count">
<NsInputNumber v-model="model.count" />
</NsFormItem>
</NsForm>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | number | undefined | 绑定值,支持 v-model。空值是 undefined |
| min | number | -Infinity | 最小值 |
| max | number | Infinity | 最大值 |
| step | number | 1 | 每次加减的步长 |
| precision | number | - | 保留几位小数。不传时不格式化 |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读 |
| controls | boolean | true | 是否显示加减按钮 |
| controlsPosition | '' | 'right' | '' | 加减按钮的位置:'' 是左右两侧,'right' 是都放在右侧 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不传时跟随表单,不在表单里时是 'default' |
| placeholder | string | - | 占位文字 |
| validateEvent | boolean | true | 值变化和失焦时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: number | undefined) | 提交了新值时触发:按回车、内容有变化时失焦、点加减按钮、按上下键、长按连续加减。值没变时不触发 |
| change | (value: number | undefined) | 和 update:modelValue 同时触发,时机相同 |
| focus | (event: FocusEvent) | 获得焦点时触发 |
| blur | (event: FocusEvent) | 失去焦点时触发 |
方法
| 名称 | 类型 | 说明 |
|---|---|---|
| focus | () => void | 让输入框获得焦点 |
| blur | () => void | 让输入框失去焦点 |
| inputRef | HTMLInputElement | 内部的 input 元素 |
类型
import type { InputNumberProps, InputNumberEmits, InputNumberSize } from '@ns/ui'
type InputNumberSize = 'large' | 'default' | 'small'
interface InputNumberProps {
modelValue?: number
min?: number
max?: number
step?: number
precision?: number
disabled?: boolean
readonly?: boolean
controls?: boolean
controlsPosition?: '' | 'right'
size?: InputNumberSize
placeholder?: string
validateEvent?: boolean
}
interface InputNumberEmits {
'update:modelValue': [value: number | undefined]
change: [value: number | undefined]
focus: [event: FocusEvent]
blur: [event: FocusEvent]
}
注意事项
- 只接受普通的十进制写法,比如
12、-3.5、.5、1.;0x10、1e3、Infinity、abc这类内容提交时会恢复成原来的值,不发事件。 - 打字过程中不改绑定值,回车或失焦时才提交;只聚焦再失焦、内容没变时不发任何事件。
- 父组件传入超出
[min, max]的值(比如max是 10 时传 100),会原样显示,不会自动纠正,也不发事件;这时加号是灰的,点减号会直接变成 10。需要严格限制时,在父组件里自己处理。 - 设了
precision时,回车提交后输入框里的内容会按位数格式化(输入1.5显示1.50),绑定值仍是数字1.5。 - 放在只有一个输入框的
NsForm里时,按回车会触发原生表单提交并刷新页面,给NsForm加@submit.prevent。 - 组件上写的
class、style留在外层容器上,其余属性和监听都透传到内部的<input>:name、id、autofocus、tabindex、aria-label、data-*,以及@keydown、@paste等组件没有声明的事件,和NsInput一致。 - 组件没有插槽。
优化点
- [x] 支持键盘上下键增减
- [ ] 支持拖拽改变数值
- [ ] 支持自定义格式化显示(
formatter、parser)