::: sourceCode ## textarea > issues: https://issues.dcloud.net.cn/?mid=component.form-component.textarea > 源码: https://github.com/dcloudio/uni-app/tree/uni-app-x-alpha/src/uni_modules/uni-form/components/textarea ::: > 组件类型:[UniTextareaElement](/api/dom/unitextareaelement.md) 多行输入框 ### 兼容性 Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 ### 属性 | 名称 | 类型 | 默认值 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | name | string | "textarea" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 表单的控件名称,作为键值对的一部分与表单(form组件)一同提交 | | disabled | boolean | false | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 是否禁用 | | value | string | "" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 输入框的初始内容 | | placeholder | string | "" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 输入框为空时占位符 | | placeholder-style | string | "" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 指定 placeholder 的样式 | | placeholder-class | string([string.ClassString](/uts/data-type.md#ide-string)) | "" | Web: x; 微信小程序: x; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 指定 placeholder 的样式类 | | maxlength | string \| number | -1 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 最大输入长度,0和正数为合法值,非法值的时候不限制最大长度 | | auto-focus | boolean | false | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 自动获取焦点,与`focus`属性对比,此属性只会首次生效。 | | focus | boolean | false | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 获取焦点 | | confirm-type | string | "return" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.15; HarmonyOS: 4.61 | 设置键盘右下角按钮的文字 | | cursor | number | -1 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 指定focus时的光标位置 | | confirm-hold | boolean | false | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 点击键盘右下角按钮时是否保持键盘不收起 | | auto-height | boolean | false | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.65 | 是否自动增高,设置auto-height时,style.height不生效 | | cursor-spacing | number | 0 | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: x | 指定光标与键盘的距离,单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 | | cursor-color | string([string.ColorString](/uts/data-type.md#ide-string)) | "" | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: 3.99; iOS: 4.11; HarmonyOS: 4.61 | 指定光标颜色 | | selection-start | number | -1 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 光标起始位置,自动聚集时有效,需与selection-end搭配使用 | | selection-end | number | -1 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 光标结束位置,自动聚集时有效,需与selection-start搭配使用 | | adjust-position | boolean | true | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 键盘弹起时,是否自动上推页面 | | hold-keyboard | boolean | false | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: 4.0; iOS: 4.11; HarmonyOS: 4.61 | focus时,点击页面的时候不收起键盘 | | inputmode | none \| text \| decimal \| numeric \| tel \| search \| email \| url | "text" | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 是一个枚举属性,它提供了用户在编辑元素或其内容时可能输入的数据类型的提示。在符合条件的高版本webview里,uni-app的 web 和 app-vue 平台中可使用本属性。 | | fixed | boolean | | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true | | show-confirm-bar | boolean | | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 是否显示键盘上方带有”完成“按钮那一栏 | | disable-default-padding | boolean | | 微信小程序: 4.41; 支付宝小程序: x | *(boolean)*
是否去掉 iOS 下的默认内边距 | | adjust-keyboard-to | string | | 微信小程序: 4.41; 支付宝小程序: x | 键盘对齐位置 | | @confirm | (event: [UniInputConfirmEvent](#uniinputconfirmevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 4.73; iOS: 4.73; HarmonyOS: 4.61 | 点击完成时, 触发 confirm 事件,event.detail = {value: value} | | @input | (event: [UniInputEvent](#uniinputevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 当键盘输入时,触发 input 事件,event.detail = {value, cursor}, @input 处理函数的返回值并不会反映到 textarea 上 | | @linechange | (event: [UniTextareaLineChangeEvent](#unitextarealinechangeevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.65 | 输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0} | | @blur | (event: [UniTextareaBlurEvent](#unitextareablurevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 输入框失去焦点时触发,event.detail = {value, cursor} | | @keyboardheightchange | (event: [UniInputKeyboardHeightChangeEvent](#uniinputkeyboardheightchangeevent)) => void | | Web: x; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration} | | @focus | (event: [UniTextareaFocusEvent](#unitextareafocusevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61 | 输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持 | | @change | (event: [UniInputChangeEvent](#uniinputchangeevent)) => void | | Web: 4.81; 微信小程序: 4.41; 支付宝小程序: x; Android: 4.73; iOS: 4.73; HarmonyOS: 4.73 | 非聚焦状态内容改变时触发(仅组件失去焦点时且用户输入改变内容才触发) | #### confirm-type 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | return | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 3.9; iOS: 4.15; HarmonyOS: 4.61 | 换行 | | send | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 发送 | | search | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 搜索 | | next | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 下一个 | | go | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 前往 | | done | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 4.73; iOS: 4.15; HarmonyOS: 4.61 | 完成 | #### inputmode 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | none | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用。 | | text | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 使用用户本地区域设置的标准文本输入键盘。 | | decimal | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 小数输入键盘,包含数字和分隔符(通常是“ . ”或者“ , ”),设备可能也可能不显示减号键。 | | numeric | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 数字输入键盘,所需要的就是 0 到 9 的数字,设备可能也可能不显示减号键。 | | tel | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 电话输入键盘,包含 0 到 9 的数字、星号(*)和井号(#)键。表单输入里面的电话输入通常应该使用 \ 。 | | search | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 为搜索输入优化的虚拟键盘,比如,返回键可能被重新标记为“搜索”,也可能还有其他的优化。 | | email | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 为邮件地址输入优化的虚拟键盘,通常包含"@"符号和其他优化。表单里面的邮件地址输入应该使用 \ 。 | | url | Web: 4.0; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 为网址输入优化的虚拟键盘,比如,“/”键会更加明显、历史记录访问等。表单里面的网址输入通常应该使用 \ 。 | #### adjust-keyboard-to 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | cursor | 微信小程序: 4.41; 支付宝小程序: x | 对齐光标位置 | | bottom | 微信小程序: 4.41; 支付宝小程序: x | 对齐输入框底部 | ### 事件 #### UniInputConfirmEvent ```mermaid graph LR UniInputConfirmEvent -- Extends --> UniEvent style UniEvent color:#42b983 click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent" ``` ##### UniInputConfirmEvent 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | detail | **UniInputConfirmEventDetail** | 是 | #### detail 的属性描述 | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 | #### UniInputEvent ```mermaid graph LR UniInputEvent -- Extends --> UniEvent style UniEvent color:#42b983 click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent" ``` ##### UniInputEvent 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | detail | **UniInputEventDetail** | 是 | #### detail 的属性描述 | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 | | cursor | number | 是 | 光标的位置 | | keyCode | number | 是 | 输入字符的Unicode值 | #### UniTextareaLineChangeEvent ```mermaid graph LR UniTextareaLineChangeEvent -- Extends --> UniEvent style UniEvent color:#42b983 click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent" ``` ##### UniTextareaLineChangeEvent 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | detail | **UniTextareaLineChangeEventDetail** | 是 | #### detail 的属性描述 | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | lineCount | number | 是 | 行数 | | heightRpx | number | 是 | textarea的高度 | | height | number | 是 | textarea的高度 | #### UniTextareaBlurEvent ```mermaid graph LR UniTextareaBlurEvent -- Extends --> UniEvent style UniEvent color:#42b983 click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent" ``` ##### UniTextareaBlurEvent 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | detail | **UniTextareaBlurEventDetail** | 是 | #### detail 的属性描述 | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 | | cursor | number | 是 | 选择区域的起始位置 | #### UniInputKeyboardHeightChangeEvent ```mermaid graph LR UniInputKeyboardHeightChangeEvent -- Extends --> UniEvent style UniEvent color:#42b983 click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent" ``` ##### UniInputKeyboardHeightChangeEvent 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | detail | **UniInputKeyboardHeightChangeEventDetail** | 是 | #### detail 的属性描述 | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | height | number | 是 | 键盘高度 | | duration | number | 是 | 持续时间 | #### UniTextareaFocusEvent ```mermaid graph LR UniTextareaFocusEvent -- Extends --> UniEvent style UniEvent color:#42b983 click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent" ``` ##### UniTextareaFocusEvent 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | detail | **UniTextareaFocusEventDetail** | 是 | #### detail 的属性描述 | 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | height | number | 是 | Web: x; Android: 3.9; iOS: 4.11 | 键盘高度 | | value | string | 是 | | 输入框内容 | #### UniInputChangeEvent ```mermaid graph LR UniInputChangeEvent -- Extends --> UniEvent style UniEvent color:#42b983 click UniEvent "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unievent" ``` ##### UniInputChangeEvent 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | detail | **UniInputChangeEventDetail** | 是 | #### detail 的属性描述 | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | value | string | 是 | 输入框内容 | #### 获取原生view对象 为增强uni-app x组件的开放性,从 `HBuilderX 4.25` 起,UniElement对象提供了 [getAndroidView](../dom/unielement.md#getandroidview) 和 [getIOSView](../dom/unielement.md#getiosview) 方法。 该方法可以获取到 textarea 组件对应的原生对象,即Android的`AppCompatEditText`对象、iOS的`UITextView`对象。 进而可以调用原生对象提供的方法,这极大的扩展了组件的能力。 **Android 平台:** 获取textarea组件对应的UniElement对象,通过UniElement对象的[getAndroidView](../dom/unielement.md#getandroidview-2)方法获取组件原生AppCompatEditText对象 ```uts //导入安卓原生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() } ``` **iOS 平台:** 获取textarea组件对应的UniElement对象,通过UniElement对象的[getIOSView](../dom/unielement.md#getiosview)方法获取组件原生UITextView对象。 ```uts //通过 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](https://gitcode.com/dcloud/hello-uni-app-x/blob/alpha/uni_modules/uts-get-native-view/utssdk/app-ios/index.uts) ### 子组件 @children-tags 不可以嵌套组件 ### 示例 示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/component/textarea/textarea.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/component/textarea/textarea.uvue) ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/component/textarea/textarea > appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/component/textarea/textarea >示例 ```vue