uni-app x textarea 多行输入框组件完全指南：属性、事件、原生 View 获取与键盘上推实践-开发者社区

uni-app x textarea 多行输入框组件完全指南：属性、事件、原生 View 获取与键盘上推实践

【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app

本文以 uni-app x 官方组件文档 docs/component/textarea.md 为骨架，结合开源仓库 uni-app 内uni-textarea组件的真实源码（textarea.uvue、app-harmony/index.uts、cppsdk/textarea.h）与官方示例页（textarea.uvue、textarea-performance.uvue），系统讲解多行输入框的组件类型、全部属性与事件语义、confirm-type/inputmode合法值、键盘上推策略、占位符样式限制以及获取原生AppCompatEditText/UITextView对象的高级用法。

textarea 是什么

textarea是 uni-app x 中的多行文本输入框组件，与单行输入框input互为补充，用于收集用户输入的较长文本（如备注、简介、反馈内容等）。它的组件类型为 UniTextareaElement，即 textarea 在 DOM 树中对应的元素对象，继承自UniElement，扩展出name、disabled、autofocus、value等属性值。

兼容性

| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.9 | 4.11 | 4.61 |

上表数值为 uni-app x 引入对应能力的最低 HBuilderX 版本号。部分属性（如cursor-spacing、fixed、show-confirm-bar、hold-keyboard）在不同平台的兼容版本并不一致，具体以各属性表格中的"兼容性"列为准。

组件属性全解析

textarea 的所有属性均通过v-bind或静态方式传入，下表完整列出官方文档定义的属性及其默认值。

关键属性解读

name 与表单提交：name默认值为"textarea"。在仓库源码 textarea.uvue 中可以看到，组件挂载时会通过inject获取 form 上下文（UNI_FORM_CTX），并以name为键注册registerField({ name, getValue, reset })，卸载时调用unregisterField反注册。因此设置了name的 textarea 会自动成为 form 表单提交数据的一部分。
value 与 modelValue：源码中getInitValue()的规则是modelValue非空时优先使用modelValue，否则回退到value（textarea.uvue）。watch监听两者变化并同步到原生视图，同时会按maxlength截断超长内容。
maxlength：默认-1表示不限制；0表示禁止输入；正整数表示最大长度。源码中所有写入路径（如props.value/props.modelValue变化）都会执行substring(0, maxlength)截断逻辑。
auto-focus 与 focus 的区别：auto-focus只在组件首次渲染时生效一次，而focus是可重复触发的布尔开关，置为true即聚焦、false即失焦。
adjust-position：默认true，即软键盘弹出时自动上推页面，避免输入框被遮挡，详细策略见下文"键盘上推专题"。
fixed 与 show-confirm-bar：这两个属性仅微信小程序平台支持。当 textarea 处于position: fixed的区域时必须显式设置fixed为true；show-confirm-bar控制键盘上方带有"完成"按钮的那一栏是否显示。
布尔属性统一规则：所有 boolean 类型属性，只有设置为布尔类型的false才会关闭该属性，其他任何值（包括字符串"false"）都会被当作true处理（微信小程序中空字符串会被视为false）。建议始终使用:prop="false"的绑定写法。

confirm-type 的属性描述

confirm-type用于设置键盘右下角按钮的文字，textarea 默认值为"return"（换行），与 input 组件的默认"done"不同。

| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | return | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.15; HarmonyOS: 4.61 | 换行 | | send | Web: 4.0; 微信小程序: 4.41; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 发送 | | search | Web: 4.0; 微信小程序: 4.41; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 搜索 | | next | Web: 4.0; 微信小程序: 4.41; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 下一个 | | go | Web: 4.0; 微信小程序: 4.41; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 前往 | | done | Web: 4.0; 微信小程序: 4.41; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 完成 |

在 HarmonyOS 平台，源码 app-harmony/index.uts 中定义了一张CONFIRM_TYPES映射表，将return/send/search/next/go/done分别映射为 ArkUI 的EnterKeyType.NEW_LINE / Send / Search / Next / Go / Done，updateConfirmType即据此设置键盘回车键类型。

inputmode 的属性描述

inputmode是标准 HTML 枚举属性，提示浏览器应展示哪种软键盘类型。仅 Web: 4.0 平台支持（微信小程序、Android、iOS、HarmonyOS 均为x不支持），需在符合条件的高版本 webview 中使用。

| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | none | Web: 4.0 | 无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用 | | text | Web: 4.0 | 使用用户本地区域设置的标准文本输入键盘 | | decimal | Web: 4.0 | 小数输入键盘，包含数字和分隔符（通常是" . "或" , "），设备可能也可能不显示减号键 | | numeric | Web: 4.0 | 数字输入键盘，所需要的就是 0 到 9 的数字，设备可能也可能不显示减号键 | | tel | Web: 4.0 | 电话输入键盘，包含 0 到 9 的数字、星号（*）和井号（#）键 | | search | Web: 4.0 | 为搜索输入优化的虚拟键盘，比如返回键可能被重新标记为"搜索" | | email | Web: 4.0 | 为邮件地址输入优化的虚拟键盘，通常包含"@"符号和其他优化 | | url | Web: 4.0 | 为网址输入优化的虚拟键盘，比如"/"键会更加明显、支持历史记录访问等 |

inputmode 浏览器兼容性：Chrome >= 66、Edge >= 79、Firefox >= 95、Chrome Android >= 66、Firefox for Android >= 79、Safari on iOS >= 12.2、WebView Android >= 66。

组件事件与事件对象

textarea 支持 7 个输入相关事件 + 2 个通用交互事件（@tap、@longpress等与 view 一致），所有输入事件对象均继承自UniEvent。

| 事件 | 回调签名 | 兼容性 | 说明 | | :- | :- | :- | :- | | @confirm | (event: UniInputConfirmEvent) => void | Web: 4.0; 微信小程序: 4.41; Android: 4.73; iOS: 4.73; HarmonyOS: 4.61 | 点击完成/右下角按钮时触发，event.detail = { value }| | @input | (event: UniInputEvent) => void | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 键盘输入时触发，event.detail = { value, cursor }；@input 处理函数的返回值并不会反映到 textarea 上| | @linechange | (event: UniTextareaLineChangeEvent) => void | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.65 | 输入框行数变化时触发，event.detail = { height, heightRpx, lineCount }| | @blur | (event: UniTextareaBlurEvent) => void | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 失去焦点时触发，event.detail = { value, cursor }| | @keyboardheightchange | (event: UniInputKeyboardHeightChangeEvent) => void | Web: x; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 键盘高度变化时触发，event.detail = { height, duration }| | @focus | (event: UniTextareaFocusEvent) => void | Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 聚焦时触发，event.detail = { value, height }，height 为键盘高度 | | @change | (event: UniInputChangeEvent) => void | Web: 4.81; 微信小程序: 4.41; Android: 4.73; iOS: 4.73; HarmonyOS: 4.73 |非聚焦状态内容改变时触发（仅组件失去焦点且用户输入改变内容时才触发） | | @update:value | Event | — | — |

UniInputConfirmEvent

UniInputConfirmEvent -- Extends --> UniEvent，属性值：

| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniInputConfirmEventDetail| 是 |

detail 属性描述：

| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 |

UniInputEvent

UniInputEvent -- Extends --> UniEvent，属性值：

| 名称 | 类型 | 必填 | | :- | :- | :- | | detail |UniInputEventDetail| 是 |

detail 属性描述：

| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 | | cursor | number | 是 | 光标的位置 | | keyCode | number | 是 | 输入字符的Unicode值 |

在 HarmonyOS 实现中，dispatchInput通过updateLineCount()计算行数，并在输入期间同步value与cursor（app-harmony/index.uts）。

UniTextareaLineChangeEvent

UniTextareaLineChangeEvent -- Extends --> UniEvent，detail 属性描述：

| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | lineCount | number | 是 | 行数 | | heightRpx | number | 是 | textarea的高度 | | height | number | 是 | textarea的高度 |

UniTextareaBlurEvent

UniTextareaBlurEvent -- Extends --> UniEvent，detail 属性描述：

| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 | | cursor | number | 是 | 选择区域的起始位置 |

UniInputKeyboardHeightChangeEvent

UniInputKeyboardHeightChangeEvent -- Extends --> UniEvent，detail 属性描述：

| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | height | number | 是 | 键盘高度 | | duration | number | 是 | 持续时间 |

UniTextareaFocusEvent

UniTextareaFocusEvent -- Extends --> UniEvent，detail 属性描述：

| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | height | number | 是 | Web: x; Android: 3.9; iOS: 4.11 | 键盘高度 | | value | string | 是 | — | 输入框内容 |

UniInputChangeEvent

UniInputChangeEvent -- Extends --> UniEvent，detail 属性描述：

| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 |

在 HarmonyOS 源码中，dispatchChange()只有value !== preTextValue时才派发change事件（app-harmony/index.uts），与文档中"非聚焦状态内容改变才触发"的语义一致。

获取 textarea 的原生 View 对象

为增强 uni-app x 组件的开放性，从 HBuilderX 4.25 起，UniElement 对象提供了 getAndroidView 和 getIOSView 方法，可以获取到 textarea 组件对应的原生对象——即 Android 的AppCompatEditText对象、iOS 的UITextView对象，进而调用原生对象提供的方法，极大扩展组件能力。

Android 平台

通过uni.getElementById(id)获取 textarea 的 UniElement 对象，再调用其getAndroidView方法（泛型指定为AppCompatEditText）获取原生对象；如果泛型不匹配会返回null。

// 导入安卓原生AppCompatEditText对象 import AppCompatEditText from "androidx.appcompat.widget.AppCompatEditText" // 通过textarea组件定义的id属性值，获取textarea标签的UniElement对象 const textareaElement = uni.getElementById(id) // UniElement.getAndroidView设置泛型为安卓底层AppCompatEditText对象，直接获取AppCompatEditText， 如果泛型不匹配会返回null if(textareaElement != null) { // editText就是textarea组件对应的原生view对象 const editText = textareaElement.getAndroidView<AppCompatEditText>() }

iOS 平台

通过uni.getElementById(id)获取 UniElement 对象，再调用getIOSView()获取原生 view，并判断其类型是否为UITextView。

// 通过 textarea 组件定义的 id 属性值，获取 textarea 标签的 UniElement 对象 const textareaElement = uni.getElementById(id) // 获取原生 view const view = inputElement?.getIOSView(); // 判断 view 是否存在，类型是否为 UITextView if (view != null && view instanceof UITextView) { // 将 view 转换为 UITextView 类型 const textField = view! as UITextView; }

注意：iOS 平台 uvue 环境使用 js 驱动无法处理原生类型，getIOSView方法需要在 uts 插件中使用。更多示例可参考仓库内的 uts 插件 uts-get-native-view。

完整示例（官方示例页核心代码）

以下代码摘自官方 hello uni-app x 示例页（仓库对应文件为 src/pages/component/textarea/textarea.uvue），演示了 textarea 的属性绑定、事件监听与动态控制面板的完整用法。

<script setup lang="uts"> import { ItemType } from '@/components/enum-data/enum-data-types' type DataType = { value2: string; adjust_position_boolean: boolean; show_confirm_bar_boolean: boolean; fixed_boolean: boolean; auto_height_boolean: boolean; confirm_hold_boolean: boolean; focus_boolean: boolean; auto_focus_boolean: boolean; default_value: string; inputmode_enum: ItemType[]; confirm_type_list: ItemType[]; cursor_color: string; cursor: number; inputmode_enum_current: number; confirm_type_current: number; placeholder_value: string; defaultModel: string; textareaMaxLengthValue: string; isSelectionFocus: boolean; selectionStart: number; selectionEnd: number; hold_keyboard: boolean; adjust_position: boolean; disabled: boolean; jest_result: boolean; isAutoTest: boolean; changeValue: string; textareaRect: DOMRect | null; } // 使用reactive避免ref数据在自动化测试中无法访问 const data = reactive({ value2: '第一行\n第二行\n第三行\n第四行\n第五行\n第六行\n第七行\n第八行\n第九行\n第十行\n十一行', adjust_position_boolean: false, show_confirm_bar_boolean: false, fixed_boolean: false, auto_height_boolean: false, confirm_hold_boolean: false, focus_boolean: true, auto_focus_boolean: false, default_value: "1\n2\n3\n4\n5\n6", inputmode_enum: [{ "value": 1, "name": "text" }, { "value": 2, "name": "decimal" }, { "value": 3, "name": "numeric" }, { "value": 4, "name": "tel" }, { "value": 5, "name": "search" }, { "value": 6, "name": "email" }, { "value": 7, "name": "url" }, { "value": 0, "name": "none" }], confirm_type_list: [{ "value": 0, "name": "return" }, { "value": 1, "name": "done" }, { "value": 2, "name": "send" }, { "value": 3, "name": "search" }, { "value": 4, "name": "next" }, { "value": 5, "name": "go" }], cursor_color: "#3393E2", cursor: "1\n2\n3\n4\n5\n6".length, inputmode_enum_current: 0, confirm_type_current: 0, placeholder_value: "请输入", defaultModel: '123', textareaMaxLengthValue: "", textareaPlaceholderClass: "placeholder-class", isSelectionFocus: false, selectionStart: -1, selectionEnd: -1, hold_keyboard: false, adjust_position: false, disabled: false, jest_result: false, inputEventTriggered: false, isAutoTest: false, changeValue: "", textareaRect: null, } as DataType) const textarea_confirm = () => { console.log("点击完成时，触发 confirm 事件，event.detail = {value: value}") } const textarea_input = (_e: UniInputEvent) => { console.log("当键盘输入时，触发 input 事件，event.detail = {value, cursor}， @input 处理函数的返回值并不会反映到 textarea 上") } const textarea_linechange = () => { console.log("输入框行数变化时调用，event.detail = {height, lineCount}") } const textarea_blur = () => { console.log("输入框失去焦点时触发，event.detail = {value, cursor}") } const textarea_keyboardheightchange = () => { console.log("键盘高度发生变化的时候触发此事件，event.detail = {height, duration}") } const textarea_focus = (event: UniTextareaFocusEvent) => { data.jest_result = event.detail.height >= 0 } const textarea_change = (event: UniInputChangeEvent) => { console.log("textarea_change", event.detail.value); data.changeValue = event.detail.value } </script> <template> <view class="main uni-theme-root"> <textarea :value="data.default_value" id="uni-textarea" class="uni-textarea themed-textarea" :auto-focus="true" :focus="data.focus_boolean" :confirm-hold="data.confirm_hold_boolean" :auto-height="data.auto_height_boolean" :fixed="data.fixed_boolean" :show-confirm-bar="data.show_confirm_bar_boolean" :adjust-position="data.adjust_position_boolean" :cursor-color="data.cursor_color" :cursor="data.cursor" :placeholder="data.placeholder_value" :inputmode="data.inputmode_enum[data.inputmode_enum_current].name" :confirm-type="data.confirm_type_list[data.confirm_type_current].name" :disabled="data.disabled" @click="textarea_click" @confirm="textarea_confirm" @input="textarea_input" @linechange="textarea_linechange" @blur="textarea_blur" @keyboardheightchange="textarea_keyboardheightchange" @focus="textarea_focus" @change="textarea_change" style="padding: 10px;height: 200px" /> </view> </template>

子组件约束

textarea不可以嵌套组件（无 children 标签），占位符、光标等能力全部由组件自身与底层原生控件完成。

键盘上推专题

input和textarea组件都有adjust-position属性，默认为true，即软键盘弹出时默认上推页面以显示出输入框，避免输入框被软键盘遮挡。完整论述见 input 文档的键盘上推专题。

默认上推策略

软键盘弹出后会挡住输入框，此时启动上推逻辑，默认策略为：

如果输入框在 scroll-view 里，会优先滚动 scroll-view，以保证显示出输入框；
如果没有可滚动区域，会 transform 上移页面，以保证显示出输入框。

手动控制上推

默认的上推策略无法适配所有场景，有些场景需要关闭默认上推策略——把adjust-position设为false，然后在输入框的focus或keyboardheightchange事件中获取键盘高度，手动调整界面。

与自定义导航栏的注意事项

默认上推策略下，如果页面使用了自定义导航栏，软键盘弹出后可能把自定义导航栏推出可视范围。此时注意：

顶部导航栏不能在滚动视图中，且需要使用 css 固定在顶部；
下面放一个 scroll-view，输入框放在 scroll-view 中，就不会把自定义导航栏顶飞；
如果这种方式仍不能满足需求，则需关闭默认上推策略，手动控制。

Web 平台的差异

在 web 端平台，输入框上推逻辑由浏览器自动完成，属性adjust-position无效。但 iOS safari 软键盘弹出时，整个页面会上推而不是挤压，导致 pages.json 配置的导航栏会上移到屏幕之外。

在 HarmonyOS 源码中，NativeTextareaView在handleFocus时调用uiContext.setKeyboardAvoidMode(KeyboardAvoidMode.NONE)、handleBlur时恢复为KeyboardAvoidMode.OFFSET，即通过切换 ArkUI 的键盘避让模式实现"聚焦时不避让、失焦后恢复"的行为（app-harmony/index.uts）。

placeholder-style 与 placeholder-class 说明

uni-app x 4.41 之前，App 平台仅支持color、font-size、font-weight。
uni-app x 4.41 之后，App 平台新增支持font-family、font-style、text-align；其中text-align仅 App-Android 平台支持，App-iOS 平台的 placeholder 位置取决于 textarea 的text-align。
App-HarmonyOS 的placeholder-class暂不支持 css 变量。

在组件实现层面，App 端 placeholder 是一个独立的<text>元素（textarea.uvue），其placeholderStyle计算逻辑会读取 textarea 自身的font-size并拼接到内联样式中（textarea.uvue），从而实现"占位符字体与输入字体一致"的效果。

Tips（平台行为与已知限制）

uni-app x 4.0 起，App-Android 平台 textarea 点击输入框外的屏幕会自动收起软键盘。
uni-app x 4.0 起，App-Android 平台 textarea 的 font-size 默认值统一为 16px，line-height 默认值为 1.2em，width 默认值为 300px。
uni-app x 4.15 起，App-iOS 平台 textarea 软键盘默认右下角改为 return(换行)，换行时键盘不会收起。
由于 Android 系统限制，textarea 的键盘右下角按钮只能是"换行"，所以暂时不提供confirm-type属性（对应 Android 平台）。
补充说明：官方属性表中confirm-type标注的 Android 兼容版本为 3.9/4.73，但 Tips 明确 Android 受系统限制仅支持"换行"按钮，因此confirm-type在 Android 上的实际效果以系统表现为准，send/search/next/go/done等按钮文字在 Android 上无法呈现。
当软键盘右下角为"换行"时，confirm-hold恒为 true，设置为 false 也不生效，即按下"换行"时软键盘不会消失。
在 Android 9 以下的系统版本，样式line-height点击键盘换行时行间距设置无效，此问题是 Android 系统的 bug。
App 平台蒸汽模式（vapor）样式设置暂不支持 css 变量。
所有 boolean 类型的属性，只有设置为布尔类型的false才会关闭该属性，其他任何值（包括字符串"false"）都会被当做true处理（微信小程序中空字符串会被视为false）。

底层实现：uni-textarea 组件模块结构

该组件在仓库中的完整实现位于 src/uni_modules/uni-textarea 模块：

从源码结构看，textarea 在 App 端采用"uvue 组件壳 + 原生控件"的混合渲染方案：

App（Android/iOS）：textarea.uvue内部通过<native-view>承载原生输入控件，并在onViewInit中创建NativeTextareaView实例，随后把全部属性（value、disabled、selection、focus、confirm-type、auto-height、adjust-position、hold-keyboard、maxlength、cursor-color 等）逐一updateXxx同步到原生层（textarea.uvue）；同时用watch监听 props 变化实时更新原生视图（textarea.uvue）。
HarmonyOS：通过bindHarmonyWrappedBuilder将 ArkUI 的TextArea包装成 BuilderNode 挂在UniNativeViewElement上，TextAreaController负责光标（caretPosition）、选区（setTextSelection）、行数（getTextContentLineCount）与内容尺寸（getTextContentRect）等操作（app-harmony/index.uts）。
Web：直接渲染原生<textarea />标签（textarea.uvue）。

性能与自动化测试参考

仓库提供了两个与 textarea 直接相关的实战页面：

src/pages/component/textarea/textarea.uvue：官方 textarea 示例页（与本文示例同源），覆盖属性控制面板、maxlength、cursor-spacing、selection-start/end、hold-keyboard、v-model 与 value 共存、line-height/min-height/max-height 与 auto-height 组合、scroll-view 嵌套滚动、自定义字体（Pacifico）等全部场景，其中textarea_focus通过event.detail.height >= 0校验键盘高度事件数据，供 jest 自动化测试断言。
src/pages/component/textarea/textarea-performance.uvue：性能测试页，单页渲染 100 个 textarea 组件，配合fps组件监控帧率，通过"清空内容/禁用输入"按钮与共享 value 验证大批量 textarea 的输入响应性能。

uni-app x textarea 多行输入框组件完全指南：属性、事件、原生 View 获取与键盘上推实践