外观
Textarea 文本域
约 1299 字大约 4 分钟
2025-10-31
Textarea 文本域组件是用于用户输入多行文本信息的表单控件,支持多种样式和交互方式。该组件具有高度的可定制性,可以满足各种文本输入场景的需求,包括内容编辑、评论反馈、信息补充等。通过丰富的属性配置和事件支持,可以轻松实现美观且功能完善的文本输入界面。
基本使用
通过placeholder设置文本域为空时的占位符。
<un-textarea v-model="value1" placeholder="请输入内容"></un-textarea>字数统计
设置count属性实现字数统计。
<un-textarea v-model="value2" placeholder="请输入内容" count></un-textarea>自动增高
设置autoHeight属性实现自动增高。
<un-textarea v-model="value3" placeholder="请输入内容" autoHeight></un-textarea>禁用状态
设置disabled属性实现进行禁用,您也可以动态设置是否禁用。
<un-textarea v-model="value4" placeholder="文本域已被禁用" disabled count></un-textarea>下划线模式
设置border="bottom"属性单独设置底部下划线。
<un-textarea v-model="value5" placeholder="请输入内容" border="bottom"></un-textarea>自定义样式
通过设置backgroundColor和border属性,可以自定义文本域的样式。
<un-textarea v-model="value6" placeholder="请输入内容" backgroundColor="#f5f5f5" border="none"></un-textarea>格式化处理
如有需要,可以通过formatter参数编写自定义格式化规则。
<template>
<un-textarea v-model="value" :formatter="formatter" ref="textarea"></un-textarea>
</template>
<script setup lang="uts">
import { ref } from 'vue'
const value = ref<string>('')
const textarea = ref<UniTextareaElement | null>(null)
const formatter = (value: string): string => {
return value.replace(/[^0-9]/ig, "")
}
</script>API
Props 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model / modelValue | 输入框的内容 | string | - |
| placeholder | 输入框为空时占位符 | string | - |
| height | 输入框高度 | string | number | 70 |
| confirmType | 设置键盘右下角按钮的文字,仅微信小程序,App-vue和H5有效 | string | done |
| disabled | 是否禁用 | boolean | false |
| disabledColor | 禁用状态时的背景色 | string | - |
| count | 是否显示统计字数 | boolean | false |
| focus | 是否自动获取焦点,nvue不支持,H5取决于浏览器的实现 | boolean | false |
| autoHeight | 是否自动增加高度 | boolean | false |
| ignoreCompositionEvent | 是否忽略组件内对文本合成系统事件的处理。为 false 时将触发 compositionstart、compositionend、compositionupdate 事件,且在文本合成期间会触发 input 事件 | boolean | true |
| fixed | 如果textarea是在一个position:fixed的区域,需要显示指定属性fixed为true | boolean | false |
| cursorSpacing | 指定光标与键盘的距离 | number | 0 |
| cursor | 指定focus时的光标位置 | number | string | - |
| showConfirmBar | 是否显示键盘上方带有"完成"按钮那一栏 | boolean | true |
| selectionStart | 光标起始位置,自动聚焦时有效,需与selection-end搭配使用 | number | -1 |
| selectionEnd | 光标结束位置,自动聚焦时有效,需与selection-start搭配使用 | number | -1 |
| adjustPosition | 键盘弹起时,是否自动上推页面 | boolean | true |
| disableDefaultPadding | 是否去掉 iOS 下的默认内边距,只微信小程序有效 | boolean | false |
| holdKeyboard | focus时,点击页面的时候不收起键盘,只微信小程序有效 | boolean | false |
| maxlength | 最大输入长度,设置为 -1 的时候不限制最大长度 | string | number | 140 |
| border | 边框类型 | Enum | surround |
| placeholderClass | 指定placeholder的样式类,注意页面或组件的style中写了scoped时,需要在类名前写/deep/ | string | - |
| placeholderStyle | 指定placeholder的样式,字符串/对象形式,如"color: red;" | string | object | - |
| formatter | 输入过滤或格式化函数 | Function | null |
| customStyle | 自定义输入框样式,对象或字符串 | string | object | - |
| round | 设置圆角值 | string | 4px |
| borderColor | 边框颜色 | string | #e5e5e5 |
| backgroundColor | 背景颜色 | string | #ffffff |
Events 事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| focus | 输入框聚焦时触发 | Function |
| blur | 输入框失去焦点时触发 | Function |
| linechange | 输入框行数变化时调用 | Function |
| input | 当键盘输入时,触发 input 事件 | Function |
| confirm | 点击完成时,触发 confirm 事件 | Function |
| keyboardheightchange | 键盘高度发生变化的时候触发此事件 | Function |
Scss 变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-textarea-padding | 6px | 文本域内边距 |
| $un-textarea-border-radius | $radius-base | 文本域圆角 |
| $un-textarea-border | 1px solid $border-color | 文本域边框样式 |
| $un-textarea-hairline-margin | 0.1px | 细边框外边距 |
| $un-textarea-disabled-bg-color | $bg-color-disabled | 禁用状态背景颜色 |
| $un-textarea-placeholder-font-size | $text-base | 占位符字体大小 |
| $un-textarea-placeholder-color | $text-color-placeholder | 占位符颜色 |
| $un-textarea-placeholder-line-height | $line-base | 占位符行高 |
| $un-textarea-text-color | $text-color | 文本颜色 |
| $un-textarea-text-font-size | $text-base | 文本字体大小 |
| $un-textarea-text-min-height | 26px | 文本最小高度 |
| $un-textarea-count-font-size | $text-sm | 字数统计字体大小 |
| $un-textarea-count-color | $text-color-muted | 字数统计颜色 |
| $un-textarea-count-padding | 1px 4px | 字数统计内边距 |
| $un-textarea-count-right | 5px | 字数统计右侧距离 |
| $un-textarea-count-bottom | 2px | 字数统计底部距离 |
提示
组件内部默认使用 scss 变量,如需修改,请查看 scss 变量使用 文档
