wot-ui-plus3.1.0

主题

赞助商
成为赞助商

Textarea 文本域 ​

14:29

组件概况 ​

组件概述 ​

文本域组件是用于多行文本输入的基础UI组件，提供了丰富的配置选项和交互功能。wd-textarea组件支持自动增高、字数限制、清空按钮、前缀图标、表单验证等特性，适用于各种需要多行文本输入的场景。

详细功能描述 ​

  • 支持双向数据绑定
  • 支持自动增高功能
  • 支持最大输入长度限制和字数统计
  • 支持清空按钮
  • 支持前缀图标
  • 支持左侧标签和自定义标签宽度
  • 支持禁用和只读状态
  • 支持密码输入模式
  • 支持错误状态
  • 支持必填标记
  • 支持表单验证集成
  • 支持自定义样式和类名
  • 支持多种键盘配置
  • 支持点击前缀图标事件

适用业务场景 ​

  • 表单中的多行文本输入
  • 评论输入框
  • 描述信息输入
  • 反馈内容输入
  • 任何需要多行文本输入的场景

完整API参考 ​

Props属性 ​

名称类型默认值必填描述
modelValuestring / number''否绑定值
placeholderstring请输入...否占位文本
placeholderStylestring-否指定placeholder的样式
placeholderClassstring''否指定placeholder的样式类
disabledbooleanfalse否禁用输入框
maxlengthnumber-1否最大输入长度，设置为-1表示不限制最大长度
autoFocusbooleanfalse否自动聚焦并拉起键盘
focusbooleanfalse否获取焦点
autoHeightbooleanfalse否是否自动增高输入框高度
fixedbooleanfalse否如果textarea处于position:fixed区域，需要设置此属性为true
cursorSpacingnumber0否指定光标与键盘的距离
cursornumber-1否指定focus时的光标位置
confirmType'send' / 'search' / 'next' / 'go' / 'done'done否设置键盘右下角按钮的文字
confirmHoldbooleanfalse否点击键盘右下角按钮时是否保持键盘不收起
showConfirmBarbooleantrue否是否显示键盘上方带有“完成”按钮那一栏
selectionStartnumber-1否光标起始位置，自动聚集时有效
selectionEndnumber-1否光标结束位置，自动聚集时有效
adjustPositionbooleantrue否键盘弹起时是否自动上推页面
disableDefaultPaddingbooleanfalse否是否去掉iOS下的默认内边距
holdKeyboardbooleanfalse否focus状态下点击页面时是否不收起键盘
showPasswordbooleanfalse否显示为密码框
clearablebooleanfalse否是否显示清空按钮
readonlybooleanfalse否输入框只读状态
prefixIconstring-否前置图标，icon组件中的图标类名
showWordLimitbooleanfalse否是否显示字数限制，需要同时设置maxlength
labelstring-否设置左侧标题
labelWidthstring''否设置左侧标题宽度
sizestring-否设置输入框大小
errorbooleanfalse否设置输入框错误状态（红色）
centerbooleanfalse否当存在label属性时，设置标题和输入框垂直居中
noBorderbooleanfalse否非cell类型下是否隐藏下划线
requiredbooleanfalse否cell类型下必填样式
propstring''否表单域model字段名，在使用表单校验功能的情况下，该属性是必填的
rulesFormItemRule[][]否表单验证规则
clearTrigger'focus' / 'always'always否显示清除图标的时机
focusWhenClearbooleantrue否是否在点击清除按钮时聚焦输入框
ignoreCompositionEventbooleantrue否是否忽略组件内对文本合成系统事件的处理
inputmode'none' / 'text' / 'tel' / 'url' / 'email' / 'numeric' / 'decimal' / 'search' / 'password'text否用户在编辑元素或其内容时可能输入的数据类型的提示
markerSide'before' / 'after'before否必填标记位置
customTextareaContainerClassstring''否自定义文本域容器class名称
customTextareaClassstring''否自定义文本域class名称
customLabelClassstring''否自定义标签class名称
customStylestring / object''否自定义样式
customClassstring''否自定义类名

Events事件 ​

事件名触发条件参数说明
update:modelValue输入值变化时触发string / number - 输入框的值
clear点击清空按钮时触发-
blur输入框失去焦点时触发{ value: string / number, cursor: number } - 输入框的值和光标位置
focus输入框获得焦点时触发event - 聚焦事件对象
input输入框内容变化时触发event - 输入事件对象
keyboardheightchange键盘高度变化时触发event - 键盘高度变化事件对象
confirm点击键盘右下角按钮时触发event - 确认事件对象
linechange输入框行数变化时触发event - 行变化事件对象
clickprefixicon点击前缀图标时触发-

Methods方法 ​

该组件没有对外暴露的方法。

Slots插槽 ​

插槽名作用域变量使用说明
prefix-自定义前缀内容
label-自定义标签内容

多场景使用示例代码 ​

1. 基础用法 ​

vue
<template>
  <wd-textarea v-model="content" placeholder="请输入内容"></wd-textarea>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 初始内容为空
const content = ref('')
</script>

2. 自动增高和字数限制 ​

vue
<template>
  <wd-textarea 
    v-model="content" 
    placeholder="请输入内容" 
    auto-height 
    :maxlength="200" 
    show-word-limit
  ></wd-textarea>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 初始内容为空
const content = ref('')
</script>

3. 带前缀图标和清空按钮 ​

vue
<template>
  <wd-textarea 
    v-model="content" 
    placeholder="请输入评论" 
    prefix-icon="comment" 
    clearable
    @clickprefixicon="handlePrefixClick"
    @clear="handleClear"
  ></wd-textarea>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 初始内容为空
const content = ref('')

// 点击前缀图标事件
const handlePrefixClick = () => {
  console.log('前缀图标被点击了')
}

// 清空事件
const handleClear = () => {
  console.log('内容被清空了')
}
</script>

4. 带标签和错误状态 ​

vue
<template>
  <wd-textarea 
    v-model="content" 
    placeholder="请输入详细描述" 
    label="详细描述" 
    label-width="120rpx"
    :error="hasError"
    @input="validateContent"
  ></wd-textarea>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'

// 初始内容为空
const content = ref('')
// 错误状态
const hasError = ref(false)

// 验证内容
const validateContent = () => {
  hasError.value = content.value.length < 10
}
</script>

5. 表单验证集成 ​

vue
<template>
  <wd-form ref="formRef" @submit="handleSubmit">
    <wd-textarea 
      v-model="form.content" 
      placeholder="请输入反馈内容" 
      label="反馈内容" 
      prop="content"
      :rules="[{ required: true, message: '请输入反馈内容' }, { min: 10, message: '反馈内容不能少于10个字符' }]"
    ></wd-textarea>
    
    <wd-button type="primary" @click="handleSubmit" style="margin-top: 40rpx;">提交</wd-button>
  </wd-form>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 表单引用
const formRef = ref()
// 表单数据
const form = ref({
  content: ''
})

// 提交表单
const handleSubmit = () => {
  formRef.value.validate().then(() => {
    console.log('表单验证通过，提交数据:', form.value)
    // 这里可以添加提交数据的逻辑
  }).catch(error => {
    console.log('表单验证失败:', error)
  })
}
</script>

样式定制指南 ​

customStyle 用法 ​

vue
<template>
  <wd-textarea 
    v-model="content" 
    placeholder="请输入自定义样式内容" 
    :custom-style="{ 
      backgroundColor: '#f5f7fa', 
      borderRadius: '8rpx', 
      padding: '20rpx',
      fontSize: '28rpx'
    }"
  ></wd-textarea>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 初始内容为空
const content = ref('')
</script>

customClass 用法 ​

vue
<template>
  <wd-textarea 
    v-model="content" 
    placeholder="请输入自定义类名内容" 
    custom-class="my-textarea"
  ></wd-textarea>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 初始内容为空
const content = ref('')
</script>

<style lang="scss">
.my-textarea {
  background-color: #f5f7fa;
  border-radius: 8rpx;
  padding: 20rpx;
  font-size: 28rpx;
  
  .wd-textarea__inner {
    min-height: 200rpx;
    line-height: 1.5;
    border: none;
    background: transparent;
  }
  
  .wd-textarea__placeholder {
    color: #909399;
  }
}
</style>

注意事项 ​

  1. 当设置了autoHeight属性时，style.height属性将不生效
  2. showWordLimit属性需要同时设置maxlength才会显示字数限制
  3. clearable属性在输入框不为空时显示清空按钮
  4. prefixIcon和label属性可以同时使用，创建带图标的标签
  5. error属性会将输入框边框显示为红色，用于表示错误状态
  6. required属性会在标签前显示必填标记（*）
  7. prop属性在使用表单验证功能时是必填的
  8. rules属性用于设置表单验证规则，支持多种验证类型
  9. inputmode属性在高版本webview和app-vue平台中可用，用于提示输入数据类型
  10. confirmType属性用于设置键盘右下角按钮的文字，不同值对应不同的按钮文本
  11. adjustPosition属性用于设置键盘弹起时是否自动上推页面，在某些情况下可能需要设置为false
  12. holdKeyboard属性在focus状态下点击页面时不收起键盘，适用于需要保持键盘打开的场景
  13. 组件支持与wd-form组件配合使用，实现表单验证功能
  14. 组件内部已经处理了输入值的格式化，确保输出格式正确

📖 Released under the MIT License

Copyright © 2025 Wot UI Plus