前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载wd-input是 wot-design-uni 组件库基于 Vue 3 TypeScript 的 uni-app 组件库中最基础、使用频率最高的表单输入组件它基于 uni-app 原生input封装统一了微信小程序、支付宝小程序、H5 与 App 端的行为差异。本文以官方文档 docs/component/input.md 为主线结合组件源码 wd-input.vue、类型定义 types.ts 与测试用例 wd-input.test.ts系统讲解它的全部用法状态控制、清空按钮、密码框、前后图标、字数限制、label/cell 布局以及与wd-form的联动校验读完即可在真实项目中直接落地使用。组件定位与版本说明wd-input用于收集用户文本输入支持v-model双向绑定并内置禁用、只读、清空、密码可见性切换、字数统计、错误提示、表单校验等开箱即用的能力。注意自0.2.0版本起Input组件的textarea文本域功能已迁移至 Textarea 组件且两者 API 保持一致。因此新版中wd-input专注于单行输入多行文本请使用wd-textarea。从 types.ts 可以看到组件 props 由三部分组成baseProps通用customStyle/customClass、大量 uni-app 原生input属性透传placeholder、focus、cursor-spacing、confirm-type等以及组件自定义的增强属性clearable、showPassword、label、rules等。基本用法v-model 双向绑定与 input 事件通过v-model双向绑定输入框的值通过placeholder设置占位提示文字wd-input typetext v-modelvalue placeholder请输入用户名 inputhandleInput /const value refstring() function handleInput(event) { console.log(event) }源码要点在 wd-input.vue 中handleInput会同时触发update:modelValue驱动v-model和input事件透传 uni-app 原生 detail包含value、cursor、keyCode等字段function handleInput({ detail }: any) { emit(update:modelValue, inputValue.value) emit(input, detail) }组件内部通过watch监听props.modelValue将外部值同步为内部inputValueisDef(newValue) ? String(newValue) : 并在初始化时通过getInitValue对超长值做一次截断格式化。另外placeholder不传时并非固定空字符串而是从国际化语言包读取默认文案。placeholderValue计算属性在未传入placeholder时回退到translate(placeholder)见 wd-input.vue对应语言包 zh-CN.ts 中input: { placeholder: 请输入... }这就是文档中默认值请输入...的来源。状态控制禁用与只读!-- 禁用不可输入样式置灰 -- wd-input v-modelvalue disabled / !-- 只读可聚焦但内容不可编辑 -- wd-input v-modelvalue readonly /两者的底层实现不同disabled直接透传到原生input的disabled属性:disableddisabled || readonly并给根节点追加is-disabled样式类源码见 wd-input.vue。readonly除了透传 disabled 属性外组件还会渲染一个覆盖整个输入区域的.wd-input__readonly-mask遮罩层见 wd-input.vue用于保证在部分平台上只读状态不被穿透点击。测试用例 wd-input.test.ts 分别断言了is-disabled类名、input 的disabled属性和.wd-input__readonly-mask的存在。清空按钮clearable 与触发时机控制设置clearable属性输入框有内容时展示一键清空按钮wd-input v-modelvalue clearable inputhandleInput /默认清空按钮在输入框不为空时即展示clearTrigger默认always。如需聚焦且有值时才展示设置clear-triggerfocuswd-input v-modelvalue clear-triggerfocus clearable inputhandleInput /点击清除按钮默认会自动聚焦回输入框若希望点击清除后不聚焦例如键盘已弹出、清空后保持原状态设置:focus-when-clearfalsewd-input typetext :focus-when-clearfalse v-modelvalue clearable /源码剖析清空与失焦的竞态处理清空按钮的显隐由showClear计算属性驱动见 wd-input.vueconst showClear computed(() { const { disabled, readonly, clearable, clearTrigger } props if (clearable !readonly !disabled inputValue.value (clearTrigger always || (props.clearTrigger focus focusing.value))) { return true } else { return false } })即必须满足可清空 非只读 非禁用 有值再叠加触发时机条件。对应测试 wd-input.test.ts 验证了两种模式。handleClear与handleBlur之间有一段精心设计的竞态处理wd-input.vue点击清空时若focusWhenClear为 true先置clearing标志、取消聚焦await pause()微任务后重新聚焦而handleBlur会await pause(150)等待 150ms 后再判断若检测到clearing标志则跳过 blur 事件发射避免清空导致失焦误触发 blur。平台兼容提示支付宝小程序暂不支持clear-trigger属性且某种情况下清空按钮无法点击该问题与 ant-design-mini 的已知 issue 同源。因此在支付宝端做表单设计时建议保持默认always触发或对清空交互做降级处理。密码输入框show-password设置show-password属性输入框以密文展示并在右侧提供眼睛图标切换明文/密文wd-input v-modelvalue clearable show-password inputhandleInput /实现原理组件通过:passwordshowPassword !isPwdVisible将密码态透传给原生 inputwd-input.vue点击右侧图标时调用togglePwdVisible反转isPwdVisible状态wd-input.vue图标在eye-close密文与view明文之间切换。测试用例 wd-input.test.ts 通过断言 input 的password属性在true与false间切换来验证该行为。注意show-password与type并不互斥它通过独立布尔开关控制密文显示即使typetext也能生效示例页面 src/subPages/input/Index.vue 中的密码框 demo 即为typetext show-password。前后 icon 与插槽内置图标设置前置 icon 使用prefix-icon后置 icon 使用suffix-icon值取 Icon 组件 章节中提供的图标类名wd-input v-modelvalue prefix-icondong suffix-iconlist inputhandleInput /自定义插槽如果没有你需要的图标使用prefix、suffix插槽进行自定义插入wd-input v-modelvalue template #prefix view stylepadding: 0 10px;前缀内容/view /template template #suffix wd-button sizesmall获取验证码/wd-button /template /wd-input图标点击会分别触发clickprefixicon、clicksuffixicon事件见 wd-input.vue可用来实现点击搜索图标发起搜索、点击清除前缀等交互。插槽优先级高于图标属性——当同时提供prefixIcon与prefix插槽时插槽内容会覆盖图标渲染模板中v-ifprefixIcon !$slots.prefix的判断逻辑。完整的前置/后置渲染逻辑同时存在于两种布局中有 label 时 icon 渲染在 label 区域wd-input.vue无 label 时渲染在输入值区域wd-input.vue。字数限制与字数统计设置maxlength限制最大输入长度若需显示已输入/上限的字数统计同时设置show-word-limitwd-input v-modelvalue :maxlength20 show-word-limit inputhandleInput /实现细节maxlength直接透传原生 inputwd-input.vue默认值在支付宝小程序为无默认值其余平台默认为-1不限制条件编译代码见 types.ts。showWordCount计算属性要求未禁用、未只读、maxlength 已定义且大于 -1、showWordLimit 为 true才展示计数wd-input.vue。组件在初始化与外部值变化时还会通过formatValue对超过maxlength的值主动截断value.toString().slice(0, maxlength)保证即使外部塞入超长字符串也不会溢出wd-input.vue。当当前字数超过maxlength时计数数字会追加is-error样式类变为红色wd-input.vue。对应测试 wd-input.test.ts 验证了超长值截断与.wd-input__count的渲染。label 标题与 cell 组合布局设置label属性在左侧展示标题可与 CellGroup 组件 组合使用形成cell展示类型表单列表风格wd-input typetext label基本用法 v-modelvalue placeholder请输入... /配合wd-cell-group使用每个输入项会自动获得分组边框wd-cell-group border wd-input typetext label用户名 v-modelusername placeholder请输入用户名 / wd-input typetext label手机号 v-modelphone placeholder请输入手机号 / /wd-cell-group相关属性说明属性说明默认值label-width设置左侧标题宽度33%center设置标题和输入框垂直居中默认为顶部居中falserequiredcell 类型下展示必填星号样式falsemarker-side必填标记星号的位置可选before/afterbeforeno-border非 cell 类型下隐藏底部下划线false!-- 设置标题宽度 -- wd-input typetext label基本用法 v-modelvalue label-width100px / !-- 标题与输入框垂直居中 -- wd-input typetext label基本用法 v-modelvalue center / !-- 必填样式星号默认在标题前 -- wd-input v-modelvalue placeholder请输入... label必填 required/wd-input !-- 必填星号放在标题后1.12.0 -- wd-input v-modelvalue placeholder请输入... label必填 required marker-sideafter /源码佐证labelWidth通过labelStyle计算属性同时设置min-width与max-widthwd-input.vuecenter给根节点追加is-center类配合 index.scss 中align-items: center实现垂直居中。测试 wd-input.test.ts 验证了label-width: 100px会同时写入 min-width/max-width。no-border的用途在示例页面 src/subPages/input/Index.vue 中有典型展示——去除下划线后输入框可以作为行内元素嵌入到金额 单位等自定义排版中。错误状态与表单错误提示设置error属性输入框内的文字显示为红色错误样式wd-input typetext v-modelvalue placeholder请输入用户名 error /两种错误来源手动控制error属性为 true 时根节点追加is-error类index.scss 中.is-error .wd-input__inner将文字颜色改为$input-error-color。表单联动当配合wd-form且设置了prop时errorMessage计算属性会从 form 的errorMessages中按prop字段名读取错误文案并渲染到.wd-input__error-message区域wd-input.vue。输入框大小size通过size属性修改输入框大小将size设置为large时字号为 16pxwd-input typetext label基本用法 sizelarge v-modelvalue placeholder请输入... /size类型定义见 types.tsInputSize large根节点追加is-large类index.scss 中large形态同步放大了内边距、字号$input-fs-large、图标与计数尺寸。原生属性透传与键盘控制wd-input将 uni-app 原生input的常用属性几乎全部透传方便在特定场景下精细控制属性说明默认值type类型text/number/digit/idcard/safe-password/nickname/teltextconfirm-type键盘右下角按钮文字done/go/next/search/send仅typetext时生效doneconfirm-hold点击键盘右下角按钮时是否保持键盘不收起falsefocus原生属性获取焦点falsecursor-spacing光标与键盘的距离取 input 距底部距离与指定值的最小值0cursorfocus 时的光标位置-1selection-start/selection-end自动聚焦时的光标选中起止位置需搭配使用-1/-1adjust-position键盘弹起时是否自动上推页面truealways-embed微信小程序原生属性强制 input 处于同层状态默认 focus 时切非同层仅 iOS 生效falseplaceholder-style指定 placeholder 样式目前仅支持color、font-size、font-weight-placeholder-class指定 placeholder 的样式类-inputmode提示用户可能输入的数据类型uni-app 3.6.16 新增textenable-native支付宝小程序enable-nativefalse可避免弹出键盘后内容上移1.14.0trueignore-composition-event是否忽略组件内对文本合成系统事件的处理为false时将触发 composition 系列事件1.3.11true示例搜索框场景下让键盘右下角显示搜索按钮并监听确认事件wd-input typetext v-modelkeyword confirm-typesearch placeholder搜索商品 confirmhandleSearch /function handleSearch({ value }) { // value 为当前输入框的值 console.log(搜索, value) }InputMode 可选值说明inputmode是 HTML 规范后期更新的内容各家小程序还未支持此属性。在符合条件的高版本 webview 里uni-app 的 web 和 app-vue 平台中可使用本属性。新增于 uni-app 3.6.16。值说明none无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用text使用用户本地区域设置的标准文本输入键盘decimal小数输入键盘包含数字和分隔符通常是.或,设备可能也可能不显示减号键numeric数字输入键盘只需要 0 到 9 的数字设备可能也可能不显示减号键tel电话输入键盘包含 0 到 9 的数字、星号*和井号#键表单输入里的电话输入通常应使用input typetelsearch为搜索输入优化的虚拟键盘返回键可能被重新标记为搜索email为邮件地址输入优化的虚拟键盘通常包含符号和其他优化表单里的邮件地址输入应使用input typeemailurl为网址输入优化的虚拟键盘/键更明显、支持历史记录访问等表单里的网址输入通常应使用input typeurl类型定义与默认值见 types.ts测试 wd-input.test.ts 覆盖了全部 8 个可选值的透传。与 wd-form 集成表单校验prop ruleswd-input深度集成了wd-form表单校验能力这是它区别于裸原生 input 的核心价值之一。使用方式如下wd-form refform :modelmodel :rulesrules wd-input v-modelmodel.username label用户名 propusername placeholder请输入用户名 / wd-button clickhandleSubmit提交/wd-button /wd-formconst model reactive({ username: }) const rules: FormRules { username: [ { required: true, message: 请输入用户名 }, { pattern: /^[a-zA-Z0-9_]{4,16}$/, message: 用户名需为 4-16 位字母、数字或下划线 } ] } async function handleSubmit() { const { valid, errors } await form.value.validate() if (valid) { // 提交表单 } }关键属性属性说明prop表单域model字段名在使用表单校验功能时必填rules表单验证规则结合wd-form组件使用类型为FormItemRule[]默认[]FormItemRule 规则说明键名说明类型required是否为必选字段booleanmessage错误提示文案stringvalidator通过函数进行校验可以返回一个Promise来进行异步校验(value, rule) boolean \| Promisepattern通过正则表达式进行校验正则无法匹配表示校验不通过RegExp类型定义见 wd-form/types.ts。异步校验示例校验用户名是否被占用const rules: FormRules { username: [ { validator: (value) { return new Promise((resolve) { setTimeout(() { // resolve(false) 表示校验不通过展示 message resolve(value ! admin) }, 500) }) }, message: 该用户名已被占用 } ] }校验与错误展示的底层链路wd-input通过useParent(FORM_KEY)注入父级表单上下文wd-input.vue其isRequired计算属性会合并三种必填来源自身required属性、自身rules中的required规则、以及父级 form 的rules中对应prop的必填规则wd-input.vue。实际校验发生在 wd-form.vue 的validate方法中按prop取 model 值依次执行required判空、pattern正则匹配、validator函数支持同步返回值与Promise异步结果收集{ prop, message }错误列表后写入errorMessages响应式对象wd-input的errorMessage计算属性随之更新并渲染错误文案。更多用法可参考 Form 表单文档。事件总览事件名称说明参数最低版本input监听输入框 input 事件{ value, cursor, keyCode }-focus监听输入框 focus 事件{ value, height }height 为键盘高度-blur监听输入框 blur 事件{ value }-clear监听输入框清空按钮事件--confirm点击键盘完成按钮时触发{ value }-keyboardheightchange键盘高度发生变化时触发{ height, duration }-clickprefixicon点击前置图标时触发--clicksuffixicon点击后置图标时触发--测试用例 wd-input.test.ts 逐一验证了input、focus、blur、clear、confirm、keyboardheightchange、clickprefixicon、clicksuffixicon事件的发射逻辑。插槽与外部样式类插槽Slotname说明最低版本label左侧标题插槽可自定义标题内容-prefix前置插槽位于输入框左侧-suffix后置插槽位于输入框右侧-外部样式类类名说明最低版本custom-class根节点样式-custom-input-classinput 外部自定义样式-custom-label-classlabel 外部自定义样式-示例通过外部样式类调整输入框文字样式custom-input-class在 wd-input.vue 中被合并进原生 input 的 class 列表可直接覆盖其字体、颜色等wd-input v-modelvalue custom-input-classmy-input / style .my-input { font-size: 14px; color: #4d80f0; } /style综合实战示例将上述能力组合完成一个带图标、清空、字数统计、必填校验的手机号输入项wd-form refform :modelformData :rulesrules wd-cell-group border wd-input v-modelformData.phone propphone typetel label手机号 placeholder请输入 11 位手机号 prefix-icondong clearable show-word-limit :maxlength11 required confirmhandleConfirm / /wd-cell-group wd-button typeprimary clicksubmit提交/wd-button /wd-formimport { reactive, ref } from vue import type { FormInstance, FormRules } from /uni_modules/wot-design-uni/components/wd-form/types const form refFormInstance() const formData reactive({ phone: }) const rules: FormRules { phone: [ { required: true, message: 请输入手机号 }, { pattern: /^1[3-9]\d{9}$/, message: 手机号格式不正确 } ] } async function submit() { const { valid } await form.value!.validate() if (valid) { console.log(提交数据, formData) } }小结wd-input在原生 input 之上补齐了三类能力交互增强清空按钮、密码可见切换、前后图标、字数统计、布局形态label/cell/必填/居中/大小/无边框与表单体系prop 关联、rules 校验、错误文案注入同时保留了完整的原生属性透传与键盘控制能力是 wot-design-uni 表单场景配合 Form、CellGroup的基础输入单元。实际开发中建议多行文本优先使用 Textarea支付宝端注意clear-trigger与enable-native的平台差异涉及校验时务必为每个输入项设置prop并定义rules。赞分享前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载相关推荐cube-ui Input 输入框组件完全指南从 v-model 双向绑定到密码眼睛的移动端实践cube ui Input 输入框组件完全指南从 v model 双向绑定到密码眼睛的移动端实践 cube ui 是滴滴开源的移动端 Vue 组件库Vue前端UI组件移动开发Angular 输入属性完全指南从 signal-based input 到 model 双向绑定Angular 输入属性完全指南从 signal based input 到 model 双向绑定 本文以 Angular 官方文档 Accepting da前端Web框架cube-ui Input 输入框组件完整指南v-model 双向绑定、清空按钮与密码眼睛实战解析cube ui Input 输入框组件完整指南v model 双向绑定、清空按钮与密码眼睛实战解析 导读 本文基于 cube ui 官方中文文档 input.前端UI组件移动开发上一篇跨平台桌面待办工具My-TODOs如何用极简设计告别任务焦虑下一篇LogExpert终极指南三步搞定Windows日志分析难题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考