ExUI

Appearance

Input 输入框 ​

通过鼠标或键盘输入字符。

基础用法 ​

基础的输入框用法。

vue
<template>
  <ex-input v-model="input" placeholder="请输入内容" />
</template>

<script setup>
import { ref } from 'vue'

const input = ref('')
</script>

不同尺寸 ​

提供三种尺寸：small、medium（默认）、large。

vue
<template>
  <ex-input v-model="input" size="small" placeholder="小尺寸" />
  <ex-input v-model="input" size="medium" placeholder="中等尺寸" />
  <ex-input v-model="input" size="large" placeholder="大尺寸" />
</template>

赛博朋克风格变体 ​

提供三种赛博朋克风格变体：neon（霓虹）、ghost（幽灵）、filled（填充）。

vue
<template>
  <ex-input v-model="input" variant="neon" placeholder="霓虹变体" />
  <ex-input v-model="input" variant="ghost" placeholder="幽灵变体" />
  <ex-input v-model="input" variant="filled" placeholder="填充变体" />
</template>

状态 ​

输入框的不同状态：成功、警告、错误。

vue
<template>
  <ex-input v-model="input" status="success" placeholder="成功状态" />
  <ex-input v-model="input" status="warning" placeholder="警告状态" />
  <ex-input v-model="input" status="error" placeholder="错误状态" />
</template>

禁用和只读 ​

vue
<template>
  <ex-input v-model="input" disabled placeholder="禁用状态" />
  <ex-input v-model="input" readonly placeholder="只读状态" />
</template>

可清空 ​

使用 clearable 属性即可得到一个可清空的输入框。

icon
vue
<template>
  <ex-input v-model="input" clearable placeholder="可清空的输入框" />
</template>

密码输入 ​

使用 show-password 属性即可得到一个可切换显示隐藏的密码框。

icon
vue
<template>
  <ex-input 
    v-model="password" 
    type="password" 
    show-password 
    placeholder="请输入密码" 
  />
</template>

带图标 ​

可以通过 prefix 和 suffix 插槽来在输入框中添加图标。

vue
<template>
  <ex-input v-model="input" placeholder="搜索">
    <template #prefix>
      <ex-icon name="ri:search-line" />
    </template>
  </ex-input>
  
  <ex-input v-model="input" placeholder="用户名">
    <template #suffix>
      <ex-icon name="ri:user-line" />
    </template>
  </ex-input>
</template>

前置/后置内容 ​

可通过 prepend 和 append 属性或插槽来在输入框前后添加内容。

https://
.com
vue
<template>
  <ex-input v-model="input" prepend="https://" placeholder="网址" />
  <ex-input v-model="input" append=".com" placeholder="域名" />
</template>

字数统计 ​

使用 show-word-limit 和 maxlength 属性，可以显示字数统计。

0/20
vue
<template>
  <ex-input 
    v-model="input" 
    show-word-limit 
    :maxlength="20" 
    placeholder="最多输入20个字符" 
  />
</template>

带标签 ​

使用 label 属性可以为输入框添加标签，required 属性显示必填标记。

vue
<template>
  <ex-input 
    v-model="input" 
    label="用户名" 
    required 
    placeholder="请输入用户名" 
  />
</template>

帮助文本和错误信息 ​

使用 help-text 显示帮助信息，使用 error-message 配合 status="error" 显示错误信息。

vue
<template>
  <ex-input 
    v-model="input" 
    help-text="请输入6-20位字符" 
    placeholder="用户名" 
  />
  
  <ex-input 
    v-model="input" 
    status="error" 
    error-message="用户名不能为空" 
    placeholder="用户名" 
  />
</template>

文本域 ​

用于输入多行文本信息，通过将 type 属性的值指定为 textarea。

vue
<template>
  <ex-input 
    v-model="textarea" 
    type="textarea" 
    :rows="4" 
    placeholder="请输入多行文本" 
  />
</template>

自动调整大小 ​

设置 autosize 属性可以使文本域自动调整高度。

vue
<template>
  <ex-input 
    v-model="textarea" 
    type="textarea" 
    :autosize="{ minRows: 2, maxRows: 6 }" 
    placeholder="自动调整高度" 
  />
</template>

输入格式化 ​

使用 formatter 和 parser 属性可以格式化输入内容。项目提供了常用的格式化工具函数。

vue
<template>
  <ex-input 
    v-model="amount" 
    placeholder="输入金额" 
    :formatter="formatCurrency"
    :parser="parseCurrency"
  />
  
  <ex-input 
    v-model="phone" 
    placeholder="输入手机号" 
    :formatter="formatPhone"
    :parser="parsePhone"
  />
  
  <ex-input 
    v-model="number" 
    placeholder="输入数字（千分位）" 
    :formatter="formatThousands"
    :parser="parseThousands"
  />
</template>

<script setup>
import { ref } from 'vue'
import { formatCurrency, parseCurrency, formatPhone, parsePhone, formatThousands, parseThousands } from '../../src/utils/formatters'

const amount = ref('')
const phone = ref('')
const number = ref('')
</script>

表单验证 ​

使用 rules 属性可以添加验证规则，支持手动调用 validate 方法进行验证。

vue
<template>
  <ex-input 
    ref="inputRef"
    v-model="email" 
    label="邮箱"
    placeholder="请输入邮箱"
    :rules="emailRules"
    @validation-error="handleValidationError"
  />
  
  <ex-button @click="handleSubmit">提交</ex-button>
</template>

<script setup>
import { ref } from 'vue'

const inputRef = ref()
const email = ref('')

const emailRules = [
  (value) => !!value || '邮箱不能为空',
  (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) || '邮箱格式不正确'
]

const handleValidationError = (error) => {
  console.log('验证失败:', error)
}

const handleSubmit = () => {
  if (inputRef.value.validate()) {
    console.log('验证通过，提交表单')
  }
}
</script>

API ​

Props ​

参数说明类型可选值默认值
model-value / v-model绑定值string / number——
type输入框类型stringtext / password / email / number / tel / url / search / textareatext
size输入框尺寸stringsmall / medium / largemedium
variant输入框变体stringneon / ghost / filledneon
status输入框状态stringdefault / success / warning / errordefault
placeholder占位符文本string——
disabled是否禁用boolean—false
readonly是否只读boolean—false
clearable是否显示清除按钮（有内容时显示）boolean—false
show-password是否显示密码切换按钮boolean—false
formatter格式化显示值(value: string) => string——
parser解析实际值(value: string) => string——
maxlength最大长度number——
minlength最小长度number——
show-word-limit是否显示字数统计boolean—false
prepend前置内容string——
append后置内容string——
autofocus是否自动聚焦boolean—false
autocomplete自动完成string—off
rules验证规则Array——
error-message错误信息string——
help-text帮助文本string——
label标签文本string——
required是否必填boolean—false
rows文本域行数number—3
autosize是否自适应高度boolean / object—false
custom-class自定义类名string——
custom-style自定义样式object——

Events ​

事件名说明回调参数
update:model-value值变化时触发(value: string | number)
input输入时触发(value: string | number, event: Event)
change值改变时触发(value: string | number, event: Event)
focus获得焦点时触发(event: FocusEvent)
blur失去焦点时触发(event: FocusEvent)
clear点击清除按钮时触发—
keydown按键按下时触发(event: KeyboardEvent)
keyup按键抬起时触发(event: KeyboardEvent)
enter按下回车键时触发(event: KeyboardEvent)
validation-error验证失败时触发(error: string)

Slots ​

插槽名说明
prefix前缀内容
suffix后缀内容
prepend前置内容
append后置内容
label标签内容
help帮助文本
error错误信息

Exposes ​

方法名说明参数返回值
focus使输入框获得焦点——
blur使输入框失去焦点——
select选中输入框内容——
clear清空输入框内容——
validate手动触发验证—boolean
getInputElement获取输入框元素—HTMLInputElement | HTMLTextAreaElement | null

最佳实践 ​

输入法支持 ​

组件已内置输入法支持，在使用中文、日文等输入法时，会自动暂停验证和格式化，直到输入法完成输入。

移动端优化 ​

  • 自动调整字体大小，防止 iOS 自动缩放
  • 扩大触摸区域，清除按钮和密码切换按钮在移动端有更大的触摸区域（44x44px）
  • 优化内边距，提升触摸体验

性能优化 ​

  • 文本域高度调整使用防抖和 RAF 优化
  • 高端设备的特效动画仅在悬停或聚焦时激活
  • 支持 prefers-reduced-motion 媒体查询，尊重用户的动画偏好

无障碍 ​

  • 完整的 ARIA 属性支持
  • 键盘导航友好
  • 高对比度模式支持
  • 屏幕阅读器友好