Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
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对应的高度,换尺寸后输入内容时重新计算。- 组件没有插槽,也没有清空按钮。
优化点
- [ ] 支持清空按钮
- [ ] 支持自动高度动画
- [ ] 支持字数统计位置配置