Element Plus Input Number 组件完全指南范围约束、步进、精度与格式化实战【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusElement Plus 的ElInputNumber数字输入框是一个在保留原生输入体验的同时内置范围约束、步进调节、精度控制能力的核心表单组件。本文以 input-number 官方文档 为骨架结合仓库内源码props 定义、组件实现与全部官方示例docs/examples/input-number系统讲解其每一个属性、插槽、事件与暴露方法并深入到v-model值校验、越界钳制、科学计数法过滤等底层实现帮助你写出可复制、可运行且行为可控的数字输入方案。基础用法一行代码接入v-modelel-input-number的最简用法与原生 input 类似将一个响应式变量绑定到v-model上即可。官方基础示例basic.vue如下template el-input-number v-modelnum :min1 :max10 changehandleChange / /template script langts setup import { ref } from vue const num ref(1) const handleChange (value: number | undefined) { console.log(value) } /script该示例同时演示了min最小值与max最大值的用法。需要特别留意官方文档给出的提示当向输入框输入非法字符串时组件会以NaN作为出错结果向上层父组件抛出。从源码看这一行为的根因在 input-number.vue 的handleInput中输入内容会经过Number.parseFloat(value)解析当解析失败结果为NaN时newVal被置为null而一旦输入为合法数字解析结果会写入model-value。因此输入非法字符串与清空输入两种状态最终都以null向上传递而不是把无法解析的文本回写到v-model。禁用与只读disabled属性接收boolean为true时整个组件包括两侧步进按钮与输入框不可交互。官方禁用示例disabled.vuetemplate el-input-number v-modelnum :disabledtrue / /template script langts setup import { ref } from vue const num ref(1) /script文档特别说明了一个易被忽略的默认行为即使你不设置min/max组件默认也会将值限制在Number.MIN_SAFE_INTEGER到Number.MAX_SAFE_INTEGER之间JavaScript 安全整数范围。这一点在 input-number.ts 的 props 默认值中可以得到印证max: { type: Number, default: Number.MAX_SAFE_INTEGER, }, min: { type: Number, default: Number.MIN_SAFE_INTEGER, },官方文档也在With prefix and suffix一节的 tip 中强调出于精度考虑输入数字被限制在安全整数范围内。如果你需要更大的数值请考虑使用其他数据类型或自行处理精度。另外readonly2.2.16 起属性与原生 input 的readonly语义一致——可聚焦、可复制但内容不可编辑。步进step与严格步进step-strictlystep自定义增量step属性用于定义点击加减按钮时的增量默认值为1。官方示例steps.vuetemplate el-input-number v-modelnum :step2 / /template script langts setup import { ref } from vue const num ref(5) /script将step设为2后每次点击按钮值按2递增或递减示例初始值为5因此依次得到7、9……。step-strictly输入值必须是 step 的整数倍step-strictly接收boolean为true时输入值只能是 step 的整数倍。官方示例step-strictly.vuetemplate el-input-number v-modelnum :step2 step-strictly / /template script langts setup import { ref } from vue const num ref(2) /script从源码input-number.vue 的verifyValue看严格步进的实现是Math.round(值 / step) * step即把用户输入就近取整到最近的 step 倍数上。例如step2时输入5会被修正为4或6就近舍入随后如果修正值与传入值不一致组件会触发一次update:model-value把修正后的值写回。精度precision小数位控制与陷阱precision属性用于设定输入值保留的小数位数。官方示例precision.vuetemplate el-input-number v-modelnum :precision2 :step0.1 :max10 / /template script langts setup import { ref } from vue const num ref(1) /script官方文档对此有两个必须牢记的约束precision的值必须是非负整数且不能小于step的小数位数。这两个约束在源码中都有硬性校验input-number.ts 通过validator校验precision 0且必须为整数val Number.parseInt(val)input-number.vue 会在step的小数位数大于precision时抛出错误 precision should not be less than the decimal places of step。组件内部的精度修正是通过Number(...).toFixed(precision)完成的对应toPrecision工具函数这能有效规避浮点运算如0.1 0.2带来的显示误差。尺寸sizelarge / default / small使用size属性可以设置组件的额外尺寸取值large、default、small。官方示例size.vuetemplate div classflex flex-wrap items-center gap-4 el-input-number v-modelnum1 sizelarge / el-input-number v-modelnum2 / el-input-number v-modelnum3 sizesmall / /div /template script langts setup import { ref } from vue const num1 ref(1) const num2 ref(2) const num3 ref(3) /script与 Element Plus 其他表单组件一致size复用全局useSizeProp定义见 input-number.ts因此也支持通过ConfigProvider或 Form 的size统一继承实现整表尺寸一致。控制按钮位置controls-positioncontrols-position决定加减控制按钮的位置可选值为默认按钮分列输入框两侧与right按钮合并到右侧。官方示例controlled.vue展示了三种尺寸下controls-positionright的效果template div classflex flex-wrap items-center gap-4 el-input-number v-modelnum :min1 :max10 controls-positionright sizelarge changehandleChange / el-input-number v-modelnum :min1 :max10 controls-positionright changehandleChange / el-input-number v-modelnum :min1 :max10 sizesmall controls-positionright changehandleChange / /div /template script langts setup import { ref } from vue const num ref(1) const handleChange (value: number | undefined) { console.log(value) } /script在 input-number.ts 中该属性被限制为[, right]两个合法值当传入非法值时会被 Vue 的 props 校验拦截。配套的controls属性默认true则用于整体开关设为false时两侧按钮完全隐藏组件退化为一个纯数字输入框。自定义增减图标2.6.3从 2.6.3 起可以通过decrease-icon与increase-icon两个具名插槽替换默认的减号/加号图标。官方示例custom.vue在默认布局与右侧布局下分别做了演示template el-space directionvertical el-space el-input-number v-modelnum / el-input-number v-modelnum template #decrease-icon el-icon ArrowDown / /el-icon /template template #increase-icon el-icon ArrowUp / /el-icon /template /el-input-number /el-space el-space el-input-number v-modelnum controls-positionright / el-input-number v-modelnum controls-positionright template #decrease-icon el-icon Minus / /el-icon /template template #increase-icon el-icon Plus / /el-icon /template /el-input-number /el-space /el-space /template script langts setup import { ref } from vue import { ArrowDown, ArrowUp, Minus, Plus } from element-plus/icons-vue const num ref(1) /script注意示例中使用的ArrowDown、ArrowUp、Minus、Plus等图标需要从element-plus/icons-vue单独引入配合el-icon包裹渲染。前缀与后缀2.8.4从 2.8.4 起组件提供prefix与suffix两个具名插槽用于在输入框内外侧插入附加内容。官方示例with-prefix-suffix.vue展示了货币场景的典型用法template el-space el-input-number v-modelnum :min1 :max10 template #prefix span/span /template /el-input-number el-input-number v-modelnum :min1 :max10 template #suffix spanRMB/span /template /el-input-number /el-space /template script langts setup import { ref } from vue const num ref(1) /script这一能力让组件可以直接用于金额、百分比、单位换算等场景无需再在外层包一层自定义 DOM 来模拟单位展示。格式化与解析formatter / parser2.14.0从 2.14.0 起formatter与parser让数字的展示形态与实际值可以解耦。官方示例formatter.vue给出了经典的千分位金额格式化写法template el-input-number v-modelinput :formatter(value) $ ${value}.replace(/\B(?(\d{3})(?!\d))/g, ,) :parser(value) value.replace(/\$\s?|(,*)/g, ) / /template script langts setup import { ref } from vue const input ref(10000) /script理解这套机制的关键点官方文档明确说明formatter负责展示——把内部数值如10000格式化为带$与千分位逗号的字符串$ 10,000parser负责解析——把用户编辑后的格式化字符串还原为纯数字字符串去掉$、空格与逗号当设置了formatter后内部 input 的type会切换为text以允许输入非数字字符否则原生 number 输入框无法容纳$、,等字符内部使用Number.parseFloat处理解析结果解析成功时解析后的数字写入model-value解析得到NaN时model-value被置为null。在 input-number.vue 的handleInputChange中可以看到这一分支处理当formatter存在且Number.parseFloat结果为NaN时例如输入框被清空或只剩符号也会走setCurrentValue把null写入模型保证v-model始终是可控的数据类型。清空行为与 value-on-clear2.2.0value-on-clear控制清空输入框后应当写入的值可选值取值行为null默认清空后模型值为nullmin清空后回填为最小值max清空后回填为最大值number清空后回填为指定的数字对应源码位于 input-number.ts通过validator保证取值只能是null、合法数字或min/max二者之一而 input-number.vue 的verifyValue中实现了回填逻辑valueOnClear null时返回null否则按{ min, max }[valueOnClear]或传入数字进行回填。典型场景是数量输入不允许为空清空后自动回到min如购物车数量。表单联动与输入控制validate-event控制表单校验validate-event默认true决定值变化时是否触发所在 Form 的校验。当你在 Form 中需要输入过程中暂不校验、失焦再校验时可将其设为false。从源码input-number.vue可以看到每次值变更后若validateEvent为真会调用formItem?.validate?.(change)触发对应表单项的change类型校验。align 与 disabled-scientific2.10.5align内部输入文字的对齐方式可选left | center | right默认center便于在特定布局如表格、统计面板中统一数字对齐disabled-scientific禁止输入科学计数法如e/E。默认false时浏览器原生 number 输入允许输入1e5这类指数形式在需要严格十进制的场景如金额、序列号建议开启源码中以独立布尔 prop 形式存在见 input-number.ts。inputmode2.10.3inputmode透传到原生 input用于移动端虚拟键盘类型提示如decimal、numeric类型为HTMLAttributes[inputmode]可显著改善移动端数字输入体验。原生属性透传name / placeholder / id / tabindex / aria-label这些属性与原生 input 语义一致直接透传给内部输入元素name表单提交字段名placeholder占位文本id原生 idtabindex2.14.0键盘 Tab 焦点顺序默认0aria-label2.7.2无障碍屏幕阅读器标签较早版本使用label已标记为 deprecated注意迁移。事件与组件暴露方法change / blur / focus 事件事件说明回调参数change值发生变化时触发(currentValue: number \| undefined, oldValue: number \| undefined) voidblur输入框失焦时触发(event: FocusEvent) voidfocus输入框聚焦时触发(event: FocusEvent) void从 input-number.ts 的 emits 定义可见change事件的触发条件由prev ! cur守卫即只有真实发生变化才触发同时在组件内部change与update:model-value是分离的——每次值写入模型都会派发update:model-value而change仅在旧值与新值不一致时派发见 input-number.vue。blur、focus事件则透传原生FocusEvent便于做埋点或联动校验。组件实例暴露focus / blur通过模板 ref 获取组件实例后可以调用暴露方法说明focus()让内部输入框获得焦点blur()让内部输入框失去焦点template el-input-number refnumberRef v-modelnum / /template script langts setup import { ref } from vue import type { InputNumberInstance } from element-plus const numberRef refInputNumberInstance() const num ref(1) // 调用示例页面初始化后自动聚焦 numberRef.value?.focus() /script源码中 focus / blur 的实现是代理到内部input元素的同名方法行为与原生输入框一致。完整 API 速查Attributes属性名称说明类型默认值model-value / v-model绑定值number / null—min允许的最小值numberNumber.MIN_SAFE_INTEGERmax允许的最大值numberNumber.MAX_SAFE_INTEGERstep增量步长number1step-strictly输入值是否只能是 step 的整数倍booleanfalseprecision输入值保留的小数精度number—size组件尺寸large \| default \| smalldefaultreadonly (2.2.16)同原生 input 的 readonlybooleanfalsedisabled是否禁用booleanfalsecontrols是否显示控制按钮booleantruecontrols-position控制按钮位置 \| right—name同原生 input 的 namestring—aria-label (a11y) (2.7.2)同原生 input 的 aria-labelstring—placeholder同原生 input 的 placeholderstring—id同原生 input 的 idstring—value-on-clear (2.2.0)清空输入框后应写入的值number / null /min \| max—validate-event是否触发表单校验booleantruelabel (a11y, deprecated)同原生 input 的 aria-labelstring—inputmode (2.10.3)同原生 input 的 inputmodestring—align (2.10.5)内部输入文本对齐方式left \| center \| rightcenterdisabled-scientific (2.10.5)禁用科学计数法输入如 ebooleanfalsetabindex (2.14.0)同原生 input 的 tabindexstring / number0formatter (2.14.0)输入框内展示值的格式化函数(value: string) string—parser (2.14.0)从格式化输入中提取值的解析函数(value: string) string—Slots插槽名称说明decrease-icon (2.6.3)自定义减号按钮图标increase-icon (2.6.3)自定义加号按钮图标prefix (2.8.4)输入框前缀内容suffix (2.8.4)输入框后缀内容Events事件名称说明类型change值变化时触发(currentValue: number \| undefined, oldValue: number \| undefined) voidblur输入框失焦时触发(event: FocusEvent) voidfocus输入框聚焦时触发(event: FocusEvent) voidExposes暴露方法名称说明类型focus让输入组件获得焦点() voidblur让输入组件失去焦点() void常见组合场景建议购物车数量min1value-on-clearmin保证数量永远不会被清空为非法值金额录入:precision2:step0.1disabled-scientific配合prefix/suffix展示货币符号与单位大额数字展示formatterparser实现千分位显示同时保持v-model为纯数字表单校验联动需要即时校验时保持validate-event默认值需要延后校验时置为false。小结ElInputNumber通过一套紧凑而完整的 props 体系把范围钳制、步进、精度、格式化、无障碍、表单联动等能力内置在一个组件中默认的MIN/MAX_SAFE_INTEGER边界、step-strictly的就近取整、precision的toFixed修正、value-on-clear的清空回填以及formatter/parser的展示与值解耦都可在 input-number.ts 与 input-number.vue 中找到直接实现依据。配合官方文档docs/en-US/component/input-number.md与全套示例docs/examples/input-number你可以快速将这些能力落地到真实业务中。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考