更新记录

1.0.0（2026-01-28） 下载此版本

1.0

平台兼容性

uni-app(4.87)

CustomInput使用文档

1. 安装与引入

   // 在页面或组件中引入
   import CustomInput from '@/uni_modules/han-com/components/han-com/custom-input.vue'

2. 基础使用

   <template>
    <custom-input v-model="value" placeholder="请输入内容" />
   </template>
   
   <script setup>
   import { ref } from 'vue'
   const value = ref('')
   </script>

3. 带图标的输入框/自定义样式

   <custom-input
    v-model="username"
    left-icon="icon-youxiang"
    right-icon="icon-delete"
    placeholder="请输入用户名"
    :required="true"
   />
   <custom-input
    v-model="value"
    left-icon="icon-mima"
    placeholder="搜索内容"
    :background-color="'#ffffff'"
    :focus-background-color="'#f0f9ff'"
   />

4. Props 总览

   基础属性

   属性	类型	默认值	说明
   modelValue	String/Number	-	输入框值，使用 v-model
   type	String	'text'	输入类型：text, password, number, email, tel
   placeholder	String	'请输入'	占位文本
   leftIcon	String	-	左侧图标类名
   rightIcon	String	-	右侧图标类名
   clearable	Boolean	true	是否显示清除按钮
   disabled	Boolean	false	是否禁用
   backgroundColor	String	'#f8f8f8'	背景色
   focusBackgroundColor	String	'#e6f7ff'	聚焦背景色

   验证属性

   属性	类型	默认值	说明
   required	Boolean	false	是否必填
   email	Boolean	false	邮箱验证
   phone	Boolean	false	手机号验证
   password	Boolean	false	密码验证
   pattern	String	-	自定义正则
   minLength	Number	-	最小长度
   maxLength	Number	-	最大长度
   rules	Array	[ ]	自定义验证规则

   显示属性

   属性	类型	默认值	说明
   showError	Boolean	true	显示错误提示
   showHint	Boolean	false	显示提示信息
   showStatusIcon	Boolean	true	显示状态图标
   showSuccess	Boolean	true	显示成功状态

   验证时机

   属性	类型	默认值	说明
   validateOnChange	Boolean	true	输入时验证
   validateOnBlur	Boolean	true	失焦时验证
   immediateValidation	Boolean	false	立即验证
   debounceDelay	Number	300	防抖延迟(ms)/0为禁用

5. 事件总览

   事件名	参数	说明
   update:modelValue	value	值更新
   input	value	输入事件
   focus	event	聚焦事件
   blur	event	失焦事件
   confirm	event	确认事件
   left-icon-click	-	左侧图标点击
   clear	-	清除事件
   validate	{valid, message}	验证事件
   valid	-	验证通过
   invalid	message	验证失败

6. 方法总览（通过 ref 调用）

   方法名	参数	返回值	说明
   validate	-	{valid, message}	验证当前值
   resetValidation	-	-	重置验证状态
   triggerValidation	-	{valid, message}	触发验证
   getValidationStatus	-	Object	获取验证状态
   focus	-	- -	聚焦输入框
   blur	-	-	失焦输入框

7. 性能优化建议

   场景优化

   1.高频输入场景：设置 debounceDelay 为 300-500ms

   2.表单提交场景：使用 triggerValidation() 而非自动验证

   3.长列表场景：避免使用 immediateValidation

   4.只读场景：设置 disabled=true 减少事件监听

   配置建议

   <!-- 高频输入优化 -->
   <custom-input
    v-model="search"
    :validate-on-change="false"
    :debounce-delay="500"
   />
   
   <!-- 表单提交优化 -->
   <custom-input
    v-model="form.field"
    :validate-on-change="false"
    :validate-on-blur="true"
   />
   
   <!-- 性能敏感场景 -->
   <custom-input
    v-model="value"
    :show-status-icon="false"
    :show-success="false"
    :show-hint="false"
   />

8. 注意事项

   1.图标依赖：需要引入阿里图标库

   2.验证顺序：验证规则按定义顺序执行

   3.防抖时机：防抖只影响验证，不影响值更新

   4.响应式规则：自定义规则建议使用 computed