使用方法

TextArea 用于输入多行纯文本，适合个人简介、反馈意见、评论等需要换行的内容。标签、说明与校验消息由内置的 Field 自动关联，通过 v-model 管理内容即可：

<script setup lang="ts">
import { TextArea } from '@astryx-vue/core/TextArea'
import { shallowRef } from 'vue'

const bio = shallowRef('')
</script>

<template>
  <TextArea v-model="bio" label="Bio" :rows="4" />
</template>

主题在应用入口引入一次：

import '@astryx-vue/themes/neutral.css'

最佳实践

指引	实践
推荐	提供可见的标签，让用户知道该输入什么。若必须隐藏标签，设置 isLabelHidden，并为屏幕阅读器提供描述性标签。
推荐	设有字数上限时，设置 maxLength 并显示字数统计。这能帮助用户在提交前控制字数。
推荐	使用 status 属性显示行内校验反馈：输入有效时用 success，软限制用 warning，硬错误用 error。
推荐	添加说明或占位文字，说明预期内容，例如 “Describe the issue in detail”。避免只用占位文字作为唯一标签。
避免	用文本域输入名称或邮箱等单行短内容。应使用文本输入框。
避免	只依赖占位文字说明字段用途。占位文字在获得焦点后会消失，且不是可访问的标签。
避免	在未设置状态类型时显示状态消息。边框颜色和图标正是吸引用户注意消息的元素。
避免	用 Tooltip 包裹禁用的文本域来解释禁用原因。禁用的控件会吞掉包裹层需要的悬停事件。应改用 disabledMessage 属性。

示例

基本用法

BioRequired

A short introduction.

Ada Lovelace is widely considered the first computer programmer.

用于长文本。标签、说明与状态消息通过 Field 自动关联。

尺寸

Small

Small size.

Medium

Medium size.

Large

Large size.

提供 sm、md、lg 三种高度。宽度由 width 属性控制。

行数与长度

Reply

Maximum 140 characters.

rows、cols、minlength 与 maxlength 直接透传给原生 textarea。

禁用与只读

Disabled

Unavailable

Read-only

This value is still included in form submission.

This value is read-only.

Locked

Only editors can edit this.

You need the Editor role to edit this field.

禁用后表单不提交值。提供 disabledMessage 时仍可聚焦并查看原因。

验证状态

Summary

Summary must be at least 20 characters.

status 显示错误、警告或成功消息。默认附在字段下方。

异步保存

Content

Type here to simulate an async save.

changeAction 在每次内容变化后执行。执行期间显示加载状态。

键盘操作

文本域沿用浏览器原生 textarea 的按键行为，组件只在个别按键上追加了处理，因此大部分操作和系统里的其它多行输入框一致：

• 按 Tab 把焦点移入或移出文本域。
• 按 Shift + Enter 在光标处插入一个换行。
• 按 Enter 时组件触发 enter 事件，你可以在回调里处理提交等逻辑。
• 按 Escape 关闭已经打开的禁用原因提示或状态提示。

如果「按 Enter 提交」这类行为对你有意义，直接在 enter 事件里实现即可。

使用建议

文本域不会限制用户输入什么，字数控制和内容校验都需要在你的应用里完成：

• 对字数有明确要求时，把 minlength 与 maxlength 写进 description，让用户在提交前就知道预期长度。
• isRequired 只负责显示必填提示并设置对应的 ARIA 状态，不会执行浏览器原生的必填校验。
• 输入内容是否符合业务规则，由应用层负责校验。