amis Textarea 多行文本输入框完整指南从基础配置到事件动作与源码实现【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amisTextarea多行文本输入框是 amis 表单体系中最常用的文本录入组件之一用于采集备注、简介、长文本等多行内容。本文以 amis 官方文档 textarea.md 为主体完整覆盖它的基本使用、清空与重置、字符计数器、属性表、事件表与动作表并结合仓库内渲染器源码Textarea.tsx、UI 层实现Textarea.tsx与单元测试textarea.test.tsx做纵深讲解。读完本文你将能在 JSON Schema 中熟练配置 Textarea 的自动高度、输入裁剪、字数限制、清除按钮并通过onEvent完成清空、重置、聚焦、赋值等联动动作。基本使用Textarea 使用方式与普通表单项一致在form的body中配置type: textarea即可。name为必填字段标识该值在表单数据域中的key详见 FormItem 普通表单项label用于展示表单项标签。最简配置如下{ type: form, api: /api/mock2/form/saveForm, body: [ { name: textarea, type: textarea, label: 多行文本 } ] }在渲染器层组件由TextAreaControlRenderer注册其类型声明位于 AMISTextareaSchema约束type: textarea并提供minRows、maxRows、readOnly、borderMode、maxLength、showCounter、clearable、resetValue等扩展属性。最终实际渲染的textarea由 amis-ui 中的 Textarea 组件 承担它内部基于react-textarea-autosize实现输入框高度随内容自动伸缩。清空输入框配置clearable: true后输入框右侧会出现移除图标点击图标可删除全部内容。同时可以配置resetValue清空后输入框会被重置为指定值{ type: form, api: /api/mock2/form/saveForm, body: [ { name: textarea, type: textarea, label: 多行文本, clearable: true, value: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmodtion tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. } ] }{ type: form, api: /api/mock2/form/saveForm, body: [ { name: textarea, type: textarea, label: 多行文本, clearable: true, resetValue: reset } ] }这里有两个值得注意的底层细节均可在源码中得到印证清除图标的显示条件UI 层仅在clearable !disabled value同时满足时渲染清除按钮Textarea.tsx 渲染逻辑即禁用态或有值时才不出现。点击清除按钮实际写入的是resetValueUI 层的handleClear调用onChange?.(resetValue)handleClear 实现并非写入空字符串。单测Renderer:textarea with maxLength clearable resetValue验证了这一点配置clearable: true、resetValue: i am reset value后点击清除图标输入框内容变为i am reset value见 textarea.test.tsx。若希望清空为真正的空串可将resetValue显式设为。显示计数器配置showCounter: true后输入框下方会显示当前已输入字符数。计数器一般与maxLength配合使用以限制输入长度如果只配置showCounter而不配置maxLength则仅展示计数并不会限制用户输入{ type: form, body: [ { name: a, type: textarea, label: A, showCounter: true, placeholder: 请输入, clearable: true }, { name: b, type: textarea, label: B, showCounter: true, maxLength: 30, placeholder: 请输入 } ] }从 UI 层源码看计数器的计算与渲染逻辑如下计数器渲染计数值 valueToString(value).length即按字符串长度统计valueToString会把undefined/null归一为空串非字符串值则JSON.stringify见 valueToString。仅在maxLength为有效数字时才渲染当前数 / 最大数的分式结构否则只渲染当前字符数。单测中可见对应 DOM 形态未配置maxLength时计数器为span3/span配置maxLength: 9且值为123时为span3/spani//ispan9/span见 textarea.test.tsx。需要补充的是maxLength会同时传给底层textarea maxLength{maxLength}Textarea.tsx因此它既是显示信息也是浏览器级的输入拦截而经由清除按钮写入的resetValue可以突破maxLength单测中点击清除后计数器显示16/9提交时出现has-error--maxLength校验错误见 textarea.test.tsx。属性表Textarea 作为表单项使用时除了支持 普通表单项属性表 中的全部配置name、label、value、placeholder、disabled、required、validations、visibleOn、static等外还支持以下专属配置属性名类型默认值说明minRowsnumber3最小行数maxRowsnumber20最大行数trimContentsbooleantrue是否去除首尾空白文本readOnlybooleanfalse是否只读showCounterbooleanfalse是否显示计数器maxLengthnumber-限制最大字数clearablebooleanfalse是否可清除resetValuestring清除后设置此配置项给定的值。上述默认值与渲染器/UI 层的defaultProps一一对应渲染器 defaultProps 与 UI 层 defaultProps 均定义了minRows: 3、maxRows: 20、trimContents: true、resetValue: 、clearable: false。其余要点minRows / maxRows控制输入框高度的自动伸缩范围。行数由react-textarea-autosize依据内容计算内容超出maxRows后出现内部滚动条。trimContents失焦blur时自动去除输入内容的首尾空白。该逻辑实际在渲染器层实现handleBlur中先执行onChange(value.trim())再派发blur事件Textarea.tsx。单测Renderer:textarea with trimContents showCounter验证输入 12345 后失焦输入框内容被裁剪为12345见 textarea.test.tsx。readOnly只读模式UI 层将其映射为textarea readonly同时输入框外层会添加is-disabled样式类单测通过断言textarea[readonly]存在来验证textarea.test.tsx。borderMode边框模式支持full | half | none用于适配不同表单风格AMISTextareaSchema。事件表Textarea 会对外派发以下事件可通过onEvent监听并在actions中配置执行动作actions中可通过${事件参数名}或${event.data.[事件参数名]}获取事件数据完整机制见 事件动作。[name]表示当前组件绑定的名称即name属性若未配置name则通过value取值。事件名称事件参数说明change[name]: string组件的值值变化时触发focus[name]: string组件的值输入框获取焦点时触发blur[name]: string组件的值输入框失去焦点时触发三个事件的派发位置均可从渲染器源码确认changehandleChange中先dispatchEvent(change, resolveEventData(this.props, {value: e}))再回调onChangeTextarea.tsxfocushandleFocus中异步派发focus事件若rendererEvent?.prevented为真则中止后续默认onFocusTextarea.tsx这意味着监听方可拦截焦点默认行为blurhandleBlur中先执行trimContents裁剪、再派发blur事件同样支持prevented拦截Textarea.tsx。动作表Textarea 对外暴露以下特性动作其他组件可通过actionType: 动作名称、componentId: 该组件id触发动作参数通过args: {动作配置项名称: xxx}传入详见 事件动作之触发其他组件的动作。动作名称动作配置说明clear-清空reset-将值重置为初始值。6.3.0 及以下版本为resetValuefocus-获取焦点setValuevalue: string更新的值更新数据动作的最终执行位于渲染器的doAction方法Textarea.tsxclear执行onChange?.()并focus()。注意与点击清除图标写入resetValue不同clear动作写入的是真正的空串reset通过getVariable(formStore?.pristine ?? store?.pristine, name)取表单的初始值pristine 值取不到时回退到resetValue再onChange(pristineVal)并聚焦focus直接调用focus()通过forwardRef指向底层textarea并让光标落到文本末尾UI 层 focus 实现setValue由表单控制层统一处理通过args.value更新该组件的值。下面逐一给出各动作的完整可运行示例。clear配置actionType: clearcomponentId指向目标 textarea 的id{ type: form, debug: true, body: [ { name: text, id: clear_text, type: textarea, label: text, value: 清空我 }, { type: button, label: 清空, onEvent: { click: { actions: [ { actionType: clear, componentId: clear_text } ] } } } ] }reset如果配置了resetValue则重置时使用resetValue的值否则使用初始值。reset动作的“初始值”指表单数据域中的 pristine 值字段在表单初始渲染时的值这一行为与源码中getVariable(formStore?.pristine ?? store?.pristine, name) ?? resetValue一致{ type: form, debug: true, body: [ { name: text, id: reset_text, type: textarea, label: text, value: 重置我 }, { type: button, label: 重置, onEvent: { click: { actions: [ { actionType: reset, componentId: reset_text } ] } } } ] }focus{ type: form, debug: true, body: [ { name: text, id: focus_text, type: textarea, label: text, value: 聚焦我 }, { type: button, label: 聚焦, onEvent: { click: { actions: [ { actionType: focus, componentId: focus_text } ] } } } ] }setValue通过args.value指定要写入的值{ type: form, debug: true, body: [ { name: text, id: setvalue_text, type: textarea, label: text, value: amis }, { type: button, label: 赋值, onEvent: { click: { actions: [ { actionType: setValue, componentId: setvalue_text, args: { value: amis go go go! } } ] } } } ] }静态展示与主题定制除了交互态Textarea 也支持表单项静态展示static: true。渲染器的renderStatic会将其渲染为multiline-text类型且默认最多展示5行maxRows: staticSchema.limit || 5可通过 staticSchema.limit 调整renderStatic 实现。样式定制方面渲染层通过CustomStyle与setThemeClassName将themeCss应用到inputControlClassName覆盖default / hover / focused / disabled四态下的.TextareaControl-input样式Textarea.tsx可在页面主题中按需调整输入框的边框、背景与聚焦态外观。测试用例佐证仓库为 Textarea 提供了覆盖主要能力的单元测试textarea.test.tsx可直接作为行为契约参考基础值修改fireEvent.change后输入框内容同步为456trimContents 与 showCounter失焦后首尾空白被裁剪计数器同步更新maxLength、clearable 与 resetValue清除按钮写入resetValue超长值在提交时触发has-error--maxLength校验错误readOnly渲染出textarea[readonly]。测试统一从../../../src导入渲染入口通过makeEnv({})构造测试环境查询选择器为.cxd-TextareaControl textarea.cxd-TextareaControl-input默认主题类名前缀为cxd对于在自定义主题下调试样式类名也有一定参考价值。小结Textarea 是 amis 中最轻量的长文本录入方案开箱即用的自动伸缩高度minRows/maxRows、失焦裁剪trimContents、字数统计与限制showCounter/maxLength、可配置的清除与重置clearable/resetValue再加上change/focus/blur事件与clear/reset/focus/setValue动作足以覆盖绝大多数多行文本录入与联动场景。结合 渲染器源码、UI 组件源码 与 单元测试开发者可以精确把握每个配置项的运行时行为在复杂表单中放心组合使用。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考