::: 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
maxlength 输入最大长度为10
cursor-spacing、placeholder-class、placeholder-style例子(harmony 不支持设置 placeholder backgroundColor)
设置输入框聚焦时光标的起始位置和结束位置(点击生效)
同时存在 v-model 和 value
设置line-height
设置min-height
设置max-height
设置min-height与auto-height
设置max-height与auto-height
同时设置value与text-align
scroll-view嵌套textarea滚动
注册confirm事件,点击换行效果
style 设置 font-size:20px
style 设置 font-size:20px
placeholder-class 设置 30px
style 设置 font-size:20px
placeholder-class 设置 30px
placeholder-style 设置 40px
textarea样式大合集
textarea 设置自定义字体
```
:::
### 参见
- [参见uni-app相关文档](https://uniapp.dcloud.io/component/textarea.html)
## 键盘上推专题
input和textarea组件都一个属性`adjust-position`,默认为true,即软键盘弹出时,默认上推页面以显示出输入框,避免输入框被软键盘遮挡。
因为此处内容与input重复,详见[input文档](input.md#adjust-position)
## inputmode说明
inputmode 兼容性:Chrome >= 66、Edge >= 79、Firefox >= 95、Chrome Android >= 66、Firefox for Android >= 79、Safari on iOS >= 12.2、WebView Android >= 66
## 默认样式和自定义样式
- textarea 的 font-size 默认值统一为 16px,width 默认值为300px。
- HBuilder 5.36 起,App 平台蒸汽模式下,textarea 组件的默认输入文字颜色随应用主题自动切换。light主题下,文字颜色为 `#000000`;dark主题下,默认文字颜色为 `#ffffff`。
- 目前各平台、各版本textarea默认背景色未统一,建议显式设置背景色。后续会统一背景色为透明。
- HBuilder 5.36 起,App 平台蒸汽模式下,textarea 组件支持通过 CSS `caret-color` 自定义光标颜色,例如 `style="caret-color: red"`,也可在 `class` 中设置,并支持 CSS 变量和媒体查询。若同时设置 `cursor-color` 组件属性,则优先使用 `cursor-color` 的值。
### placeholder-style和placeholder-class说明
- 目前各平台、各版本textarea默认place-holder文字颜色未统一,建议显式设置背景色。后续会统一颜色为light下#808080、dark下#5f5f5f。
- App平台 蒸汽模式 支持的css和普通文字css相同
- App平台 VDOM模式 支持的css有限:`color`、`font-size`、`font-weight`、`font-family`、`font-style`、`text-align`,其中`text-align`仅App-Android平台支持,App-iOS平台的placeholder位置取决于input的`text-align`。`font-size`样式不支持rpx单位。
- App-HarmonyOS VDOM模式 `placeholder-class` 不支持 css 变量。
## Tips
* uni-app x 4.0 起,App-Android平台 textarea 点击输入框外的屏幕会自动收起软键盘。
* uni-app x 4.15 起,App-iOS平台 textarea 软键盘默认右下角改为 return(换行) ,换行时,键盘不会收起。
* 由于Android系统限制,textarea的键盘右下角按钮只能是`换行`,所以暂时不提供`confirm-type`属性。
* 当软键盘右下角为 换行 时,confirm-hold 恒为 true,设置为false也不生效,即按下 换行 时,软键盘不会消失。
* 在Android 9以下的系统版本,样式`line-height`点击键盘换行时行间距设置无效,此问题是Android系统的bug,后续解决。
* 所有 boolean 类型的属性,只有设置为布尔类型的 false 才会关闭该属性,其他任何值(包括字符串 "false")都会被当做 true 处理(微信小程序中空字符串会被视为 false)。
* 支付宝小程序默认开启字数显示功能,真机上外层套用 `scroll-view` 时,点击 textarea 内容可能溢出组件范围。