Textarea 文本域
多行文本输入框,用来输入备注、描述、反馈这类较长的内容。支持字数统计、自适应高度和拖动缩放,放在 NsForm 里时会跟随表单的禁用、尺寸并触发校验。单行文本用 NsInput。
引入
import { NsTextarea } from '@ns/ui'
基础用法
用 v-model 绑定一个字符串,placeholder 是没有内容时显示的占位文字。默认显示 2 行,可以纵向拖动右下角调整高度。
<script setup lang="ts">
import { ref } from 'vue'
import { NsTextarea } from '@ns/ui'
const value = ref('')
</script>
<template>
<NsTextarea v-model="value" placeholder="请输入内容" />
<p style="margin-top: 12px">已输入 {{ value.length }} 个字</p>
</template>
行数
rows 指定显示几行,对应原生 textarea 的 rows,默认 2 行。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTextarea } from '@ns/ui'
const one = ref('')
const two = ref('')
const five = ref('')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTextarea v-model="one" :rows="1" placeholder="rows = 1" />
<NsTextarea v-model="two" placeholder="rows = 2(默认)" />
<NsTextarea v-model="five" :rows="5" placeholder="rows = 5" />
</NsSpace>
</template>
字数统计
同时设置 maxlength 和 show-word-limit,右下角显示“已输入/上限”。只设 maxlength 时只限制长度,不显示统计;只设 show-word-limit 不起作用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTextarea } from '@ns/ui'
const limitOnly = ref('')
const withCount = ref('')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTextarea v-model="limitOnly" :maxlength="30" placeholder="最多 30 个字,不显示统计" />
<NsTextarea v-model="withCount" :maxlength="100" show-word-limit placeholder="最多 100 个字" />
</NsSpace>
</template>
不同尺寸
size 可选 large、default、small,字号 16、14、12px,圆角 8、6、4px,左右内边距 16、12、8px,和同尺寸的 NsInput 一致。行高是字号的 1.5 倍,上下内边距按 NsInput 的高度算好:rows 为 1 时三档的高度正好是 40、32、24px,和同尺寸的 NsInput 一样高,多一行加一行的行高(24、21、18px)。字数统计的字号是 14、14、12px。不写 size 时跟随所在的 NsFormItem、NsForm、NsConfigProvider,都没有时是 default。
前三行是一行高的文本域、同尺寸的输入框和按钮,高度一样;最后一行是三种尺寸带字数统计的样子。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInput, NsSpace, NsTextarea } from '@ns/ui'
const value = ref('一行高的文本域')
const input = ref('输入框')
const note = ref('带字数统计')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsTextarea v-model="value" size="large" :rows="1" style="width: 200px" />
<NsInput v-model="input" size="large" style="width: 160px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsTextarea v-model="value" :rows="1" style="width: 200px" />
<NsInput v-model="input" style="width: 160px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsTextarea v-model="value" size="small" :rows="1" style="width: 200px" />
<NsInput v-model="input" size="small" style="width: 160px" />
<NsButton size="small">按钮</NsButton>
</NsSpace>
<NsSpace wrap align="start">
<span class="row-label">字数统计</span>
<NsTextarea
v-model="note"
size="large"
:rows="3"
:maxlength="100"
show-word-limit
style="width: 200px"
/>
<NsTextarea v-model="note" :rows="3" :maxlength="100" show-word-limit style="width: 200px" />
<NsTextarea
v-model="note"
size="small"
:rows="3"
:maxlength="100"
show-word-limit
style="width: 200px"
/>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
自适应高度
autosize 为 true 时,高度跟着内容增减。传 { minRows, maxRows } 可以限制行数范围,超过 maxRows 后出现滚动条。挂载时会按初始内容算好高度,之后改 autosize 也会重新计算;关掉 autosize 时恢复成 rows 的高度。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTextarea } from '@ns/ui'
const value = ref('')
const limited = ref('')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTextarea v-model="value" autosize placeholder="autosize:最少 rows 行,不封顶" />
<NsTextarea
v-model="limited"
:autosize="{ minRows: 2, maxRows: 6 }"
placeholder="autosize 为 { minRows: 2, maxRows: 6 }:超过 6 行出现滚动条"
/>
</NsSpace>
</template>
勾选后开启自适应高度,取消后恢复成 rows 的高度:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsTextarea } from '@ns/ui'
const autosize = ref(true)
const value = ref('第一行\n第二行\n第三行\n第四行')
</script>
<template>
<NsCheckbox v-model="autosize">自适应高度</NsCheckbox>
<NsTextarea v-model="value" :autosize="autosize" style="margin-top: 12px" />
</template>
缩放控制
resize 控制能往哪个方向拖动右下角:vertical(默认,只能拖高)、horizontal(只能拖宽)、both(都可以)、none(不能拖动)。开了 autosize 时固定为 none。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTextarea } from '@ns/ui'
const value = ref('')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTextarea v-model="value" placeholder="vertical(默认):只能拖高" />
<NsTextarea v-model="value" resize="horizontal" placeholder="horizontal:只能拖宽" />
<NsTextarea v-model="value" resize="both" placeholder="both:宽高都能拖" />
<NsTextarea v-model="value" resize="none" placeholder="none:不能拖动" />
</NsSpace>
</template>
禁用和只读
disabled 禁用后不能编辑,也不能聚焦;readonly 只读时可以聚焦、选中和复制文字,但不能修改。在禁用的 NsForm 里也会被禁用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsTextarea } from '@ns/ui'
const value = ref('这段文字可以选中、复制,但不能修改')
const empty = ref('')
</script>
<template>
<NsSpace direction="vertical" fill>
<NsTextarea v-model="value" disabled />
<NsTextarea v-model="empty" placeholder="禁用时的占位文字" disabled />
<NsTextarea v-model="value" readonly :maxlength="50" show-word-limit />
</NsSpace>
</template>
事件
输入时触发 input(和 update:modelValue 同时),内容有变化后失焦触发 change,获得、失去焦点触发 focus、blur。在下面输入几个字再点外面,看看事件的顺序:
<script setup lang="ts">
import { ref } from 'vue'
import { NsTextarea } from '@ns/ui'
const value = ref('')
const logs = ref<string[]>([])
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onInput = (val: string) => log(`input:${val.length} 个字`)
const onChange = (val: string) => log(`change:${val.length} 个字`)
</script>
<template>
<NsTextarea
v-model="value"
placeholder="输入几个字试试"
@input="onInput"
@change="onChange"
@focus="log('focus')"
@blur="log('blur')"
/>
<p style="margin-top: 12px">最近的事件(新的在前):{{ logs.join(',') || '还没有' }}</p>
</template>
校验状态
文本域没有单独的状态属性,出错的样子由所在的 NsFormItem 决定:校验不通过,或者给表单项传了 error 时,文本域的边框变成危险色,下面显示错误信息,内部的 <textarea> 带上 aria-invalid。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsForm, NsFormItem, NsSwitch, NsTextarea } from '@ns/ui'
const showError = ref(true)
const model = reactive({ remark: '太短', reason: '' })
</script>
<template>
<NsSwitch v-model="showError" active-text="显示错误" />
<NsForm :model="model" label-width="80px" style="margin-top: 16px" @submit.prevent>
<NsFormItem label="备注" :error="showError ? '至少写 10 个字' : ''">
<NsTextarea v-model="model.remark" :maxlength="100" show-word-limit />
</NsFormItem>
<NsFormItem label="原因" :error="showError ? '请填写退款原因' : ''" size="small">
<NsTextarea v-model="model.reason" placeholder="小尺寸" />
</NsFormItem>
</NsForm>
</template>
调用方法
通过 ref 调用 focus()、blur(),或者用 textareaRef 直接拿到内部的 <textarea> 元素,例如设置光标位置。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsTextarea } from '@ns/ui'
const textarea = ref<InstanceType<typeof NsTextarea>>()
const value = ref('一段已有的文字')
const focused = ref(false)
const focusEnd = () => {
const el = textarea.value?.textareaRef
if (!el) return
el.focus()
el.setSelectionRange(el.value.length, el.value.length)
}
</script>
<template>
<NsTextarea ref="textarea" v-model="value" @focus="focused = true" @blur="focused = false" />
<div style="margin-top: 12px">
<NsSpace wrap>
<NsButton @click="textarea?.focus()">聚焦</NsButton>
<NsButton @click="textarea?.blur()">失焦</NsButton>
<NsButton @click="focusEnd">聚焦到末尾(textareaRef)</NsButton>
</NsSpace>
</div>
<p style="margin-top: 12px">文本域{{ focused ? '已聚焦' : '没有聚焦' }}</p>
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,失焦触发 blur 规则;表单项的 label 会通过 for 关联到文本框,校验出错时文本框带上 aria-invalid 和指向错误提示的 aria-describedby。不需要校验时设 :validate-event="false"。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsTextarea } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const model = reactive({ feedback: '' })
const rules: Record<string, FormRule[]> = {
feedback: [
{ required: true, message: '请填写反馈内容', trigger: 'blur' },
{ min: 10, message: '至少 10 个字', trigger: 'change' }
]
}
</script>
<template>
<NsForm :model="model" :rules="rules">
<NsFormItem label="反馈" prop="feedback">
<NsTextarea v-model="model.feedback" :maxlength="200" show-word-limit />
</NsFormItem>
</NsForm>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | null | '' | 绑定值,支持 v-model。null、undefined 按空字符串显示 |
| placeholder | string | - | 占位文字 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不写时跟随表单项、表单、ConfigProvider,都没有时是 'default' |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读 |
| maxlength | number | - | 最大输入长度 |
| showWordLimit | boolean | false | 是否显示字数统计,需要同时设置 maxlength |
| rows | number | 2 | 行数 |
| autosize | boolean | TextareaAutosize | false | 自适应高度。传对象时可以限制最少、最多几行 |
| resize | 'none' | 'both' | 'horizontal' | 'vertical' | 'vertical' | 拖动缩放的方向。开了 autosize 时固定为 'none' |
| autocomplete | string | - | 原生 autocomplete 属性 |
| form | string | - | 原生 form 属性:文本框所属 <form> 的 id |
| validateEvent | boolean | true | 值变化和失焦时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string) | 输入时触发。输入法组合期间不触发,上屏后触发一次 |
| input | (value: string) | 和 update:modelValue 同时触发 |
| change | (value: string) | 原生 change:内容有变化后失焦时触发 |
| focus | (event: FocusEvent) | 获得焦点时触发 |
| blur | (event: FocusEvent) | 失去焦点时触发 |
方法
| 名称 | 类型 | 说明 |
|---|---|---|
| focus | () => void | 让文本框获得焦点 |
| blur | () => void | 让文本框失去焦点 |
| textareaRef | HTMLTextAreaElement | 内部的 textarea 元素 |
类型
import type {
TextareaProps,
TextareaEmits,
TextareaAutosize,
TextareaResize,
TextareaSize
} from '@ns/ui'
type TextareaSize = 'large' | 'default' | 'small'
type TextareaResize = 'none' | 'both' | 'horizontal' | 'vertical'
interface TextareaAutosize {
minRows?: number
maxRows?: number
}
interface TextareaProps {
modelValue?: string | null
placeholder?: string
size?: TextareaSize
disabled?: boolean
readonly?: boolean
maxlength?: number
showWordLimit?: boolean
rows?: number
autosize?: boolean | TextareaAutosize
resize?: TextareaResize
autocomplete?: string
form?: string
validateEvent?: boolean
}
interface TextareaEmits {
'update:modelValue': [value: string]
input: [value: string]
change: [value: string]
focus: [event: FocusEvent]
blur: [event: FocusEvent]
}
注意事项
- 开了
autosize时resize固定为none,不能拖动。 autosize的高度下限:写了minRows时按minRows,可以比rows小,例如:rows="4" :autosize="{ minRows: 1, maxRows: 4 }"内容只有一行时只显示一行;autosize为true或对象里没写minRows时最少显示rows行(默认 2 行)。上限是maxRows,没写时不封顶。- 用输入法打中文时,拼音组合期间不触发
update:modelValue和input,选字上屏后才触发一次。 - 文本框始终显示绑定值:父组件没有接收
update:modelValue,或者在回调里改写了值,文本框会马上显示成绑定值。 - 组件上写的
class、style留在外层容器上,其余属性和监听都透传到内部的<textarea>:name、id、autofocus、tabindex、aria-label、data-*,以及@keydown、@paste等组件没有声明的事件,和NsInput一致。需要直接操作 textarea 时用textareaRef。 autosize按当前尺寸的行高和上下内边距算minRows、maxRows对应的高度,换尺寸后输入内容时重新计算。- 组件没有插槽,也没有清空按钮。
优化点
- [ ] 支持清空按钮
- [ ] 支持自动高度动画
- [ ] 支持字数统计位置配置