# textarea
组件类型: UniTextareaElement
多行输入框
# 兼容性
| Web | 微信小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|
| 4.0 | 4.41 | 3.9 | 4.11 | 4.61 |
# 属性
| 名称 | 类型 | 默认值 | 兼容性 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | - |
|
表单的控件名称,作为键值对的一部分与表单(form组件)一同提交 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| disabled | boolean | false |
|
是否禁用 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| value | string | "" |
|
输入框的初始内容 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| placeholder | string | "" |
|
输入框为空时占位符 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| placeholder-style | string | "" |
|
指定 placeholder 的样式 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| placeholder-class | string( string.ClassString ) | "" |
|
指定 placeholder 的样式类 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxlength | number | "不限制长度" |
|
最大输入长度,0和正数为合法值,非法值的时候不限制最大长度 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| auto-focus | boolean | false |
|
自动获取焦点,与
focus
属性对比,此属性只会首次生效。
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| focus | boolean | false |
|
获取焦点 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| confirm-type | return | send | search | next | go | done | "return" |
|
设置键盘右下角按钮的文字 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cursor | number | 0 |
|
指定focus时的光标位置 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| confirm-hold | boolean | false |
|
点击键盘右下角按钮时是否保持键盘不收起 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| auto-height | boolean | false |
|
是否自动增高,设置auto-height时,style.height不生效 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cursor-spacing | number | 0 |
|
指定光标与键盘的距离,单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| cursor-color | string( string.ColorString ) | "" |
|
指定光标颜色 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| selection-start | number | -1 |
|
光标起始位置,自动聚集时有效,需与selection-end搭配使用 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| selection-end | number | -1 |
|
光标结束位置,自动聚集时有效,需与selection-satrt搭配使用 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| adjust-position | boolean | true |
|
键盘弹起时,是否自动上推页面 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hold-keyboard | boolean | false |
|
focus时,点击页面的时候不收起键盘 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| inputmode | none | text | decimal | numeric | tel | search | email | url | "text" |
|
是一个枚举属性,它提供了用户在编辑元素或其内容时可能输入的数据类型的提示。在符合条件的高版本webview里,uni-app的 web 和 app-vue 平台中可使用本属性。 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| fixed | boolean | - |
|
如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| show-confirm-bar | boolean | - |
|
是否显示键盘上方带有”完成“按钮那一栏 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| disabled | boolean | - |
|
(boolean)
是否禁用 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| disable-default-padding | boolean | - |
|
(boolean)
是否去掉 iOS 下的默认内边距 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| adjust-keyboard-to | boolean | - |
|
(boolean)
键盘对齐位置 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @confirm | (event: UniInputConfirmEvent ) => void | - |
|
点击完成时, 触发 confirm 事件,event.detail = {value: value} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @input | (event: UniInputEvent ) => void | - |
|
当键盘输入时,触发 input 事件,event.detail = {value, cursor}, @input 处理函数的返回值并不会反映到 textarea 上 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @linechange | (event: UniTextareaLineChangeEvent ) => void | - |
|
输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @blur | (event: UniTextareaBlurEvent ) => void | - |
|
输入框失去焦点时触发,event.detail = {value, cursor} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @keyboardheightchange | (event: UniInputKeyboardHeightChangeEvent ) => void | - |
|
键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @focus | (event: UniTextareaFocusEvent ) => void | - |
|
输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @change | (event: UniInputChangeEvent ) => void | - |
|
非聚焦状态内容改变时触发(仅组件失去焦点时且用户输入改变内容才触发) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
# 事件
# UniInputConfirmEvent
# UniInputConfirmEvent 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| detail | UniInputConfirmEventDetail | 是 | - | - | - | ||||||||||||
|
|||||||||||||||||
# UniInputEvent
# UniInputEvent 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| detail | UniInputEventDetail | 是 | - | - | - | ||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||
# UniTextareaLineChangeEvent
# UniTextareaLineChangeEvent 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| detail | UniTextareaLineChangeEventDetail | 是 | - | - | - | ||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||
# UniTextareaBlurEvent
# UniTextareaBlurEvent 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| detail | UniTextareaBlurEventDetail | 是 | - | - | - | ||||||||||||||||||
|
|||||||||||||||||||||||
# UniInputKeyboardHeightChangeEvent
# UniInputKeyboardHeightChangeEvent 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| detail | UniInputKeyboardHeightChangeEventDetail | 是 | - | - | - | ||||||||||||||||||
|
|||||||||||||||||||||||
# UniTextareaFocusEvent
# UniTextareaFocusEvent 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| detail | UniTextareaFocusEventDetail | 是 | - | - | - | ||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||
# UniInputChangeEvent
# UniInputChangeEvent 的属性值
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| detail | UniInputChangeEventDetail | 是 | - | - | - | ||||||||||||
|
|||||||||||||||||
# 获取原生view对象
为增强uni-app x组件的开放性,从
HBuilderX 4.25
起,UniElement对象提供了
getAndroidView
和
getIOSView
方法。
该方法可以获取到 textarea 组件对应的原生对象,即Android的
AppCompatEditText
对象、iOS的
UITextView
对象。
进而可以调用原生对象提供的方法,这极大的扩展了组件的能力。
Android 平台:
获取textarea组件对应的UniElement对象,通过UniElement对象的 getAndroidView 方法获取组件原生AppCompatEditText对象
//导入安卓原生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 平台:
获取textarea组件对应的UniElement对象,通过UniElement对象的 getIOSView 方法获取组件原生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 alpha分支 ,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例 另见
示例
<script>
import { ItemType } from '@/components/enum-data/enum-data-types'
export default {
data() {
return {
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" }] as ItemType[],
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" }] as ItemType[],
cursor_color: "#3393E2",
cursor: 0,
inputmode_enum_current: 0,
confirm_type_current: 0,
placeholder_value: "请输入",
defaultModel: '123',
textareaMaxLengthValue: "",
isSelectionFocus: false,
selectionStart: -1,
selectionEnd: -1,
hold_keyboard: false,
adjust_position: false,
disabled: false,
jest_result: false,
isAutoTest: false,
changeValue: "",
textareaRect: null as DOMRect | null,
// #ifdef APP
onReady() {
const textarea = uni.getElementById("uni-textarea")
this.textareaRect = textarea?.getBoundingClientRect()
// 加上导航栏及状态栏高度
this.textareaRect!.y += uni.getSystemInfoSync().safeArea.top + 44
// #endif
methods: {
textarea_click() { console.log(
"组件被点击时触发") },
textarea_touchstart() { console.log("手指触摸动作开始") },
textarea_touchmove() { console.log("手指触摸后移动") },
textarea_touchcancel() { console.log("手指触摸动作被打断,如来电提醒,弹窗") },
textarea_touchend() { console.log("手指触摸动作结束") },
textarea_tap() { console.log("手指触摸后马上离开") },
textarea_longpress() { console.log("如果一个组件被绑定了 longpress 事件,那么当用户长按这个组件时,该事件将会被触发。") },
textarea_confirm() { console.log("点击完成时, 触发 confirm 事件,event.detail = {value: value}") },
textarea_input(e: UniInputEvent) {
console.log("当键盘输入时,触发 input 事件,event.detail = {value, cursor}, @input 处理函数的返回值并不会反映到 textarea 上")
// #ifdef WEB
this.jest_result = e.detail.value == '11\n2\n3\n4\n5\n6'
// #endif
// #ifdef APP
this.jest_result = e.detail.value == '1\n2\n3\n4\n5\n61'
// #endif
textarea_linechange() { console.log("输入框行数变化时调用,event.detail = {height: 0, height: 0, lineCount: 0}") },
textarea_blur() { console.log("输入框失去焦点时触发,event.detail = {value, cursor}") },
textarea_keyboardheightchange() { console.log("键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}") },
textarea_focus(event: UniTextareaFocusEvent) {
this.jest_result = event.detail.height >= 0
textarea_change(event: UniInputChangeEvent) {
console.log("textarea_change", event.detail.value);
this.changeValue = event.detail.value
change_adjust_position_boolean(checked : boolean) { this.adjust_position_boolean = checked },
change_show_confirm_bar_boolean(checked : boolean) { this.show_confirm_bar_boolean = checked },
change_fixed_boolean(checked : boolean) { this.fixed_boolean = checked },
change_auto_height_boolean(checked : boolean) { this.auto_height_boolean = checked },
change_confirm_hold_boolean(checked : boolean) { this.confirm_hold_boolean = checked },
change_focus_boolean(checked : boolean) { this.focus_boolean = checked },
change_auto_focus_boolean(checked : boolean) { this.auto_focus_boolean = checked },
change_cursor_color_boolean(checked : boolean) { if (checked) { this.cursor_color = "transparent" } else { this.cursor_color = "#3393E2" } },
radio_change_inputmode_enum(checked
: number) { this.inputmode_enum_current = checked },
radio_change_confirm_type(checked : number) { this.confirm_type_current = checked },
setSelection: function (selectionStart : number, selectionEnd : number) {
this.isSelectionFocus = true;
this.selectionStart = selectionStart;
this.selectionEnd = selectionEnd;
onSelectionBlurChange() {
this.isSelectionFocus = false;
this.selectionEnd = 0;
changeHoldKeyboard(event : UniSwitchChangeEvent) {
const checked = event.detail.value;
this.hold_keyboard = checked;
changeAdjustPosition(event : UniSwitchChangeEvent) {
const checked = event.detail.value;
this.adjust_position = checked;
change_disabled_boolean(checked : boolean) {
this.disabled = checked
getBoundingClientRectForTest() : DOMRect | null {
return uni.getElementById('test-width')?.getBoundingClientRect();
</script>
<template>
<!-- #ifdef APP -->
<scroll-view style="flex: 1">
<!-- #endif -->
<view class="main">
<textarea :value="default_value" id="uni-textarea" class="uni-textarea" :auto-focus="true" :focus="focus_boolean"
:confirm-hold="confirm_hold_boolean" :auto-height="auto_height_boolean" :fixed="fixed_boolean"
:show-confirm-bar="show_confirm_bar_boolean" :adjust-position="adjust_position_boolean"
:cursor-color="cursor_color" :cursor="cursor" :placeholder="placeholder_value"
:inputmode="inputmode_enum[inputmode_enum_current].name"
:confirm-type="confirm_type_list[confirm_type_current].name" :disabled="disabled" @click="textarea_click"
@touchstart="textarea_touchstart" @touchmove="textarea_touchmove" @touchcancel="textarea_touchcancel"
@touchend="textarea_touchend" @tap="textarea_tap" @longpress="textarea_longpress" @confirm="textarea_confirm"
@input="textarea_input" @linechange="textarea_linechange" @blur="
textarea_blur"
@keyboardheightchange="textarea_keyboardheightchange" @focus="textarea_focus" @change="textarea_change"
style="padding: 10px; border: 1px solid #666;height: 200px" />
</view>
<view style="margin-bottom: 40px;">
<boolean-data :defaultValue="false" title="键盘弹起时,是否自动上推页面(限非 Web 平台)"
@change="change_adjust_position_boolean"></boolean-data>
<boolean-data :defaultValue="false" title="是否自动增高,设置auto-height时,style.height不生效"
@change="change_auto_height_boolean"></boolean-data>
<boolean-data :defaultValue="focus_boolean" title="获取焦点" @change="change_focus_boolean"></boolean-data>
<boolean-data :defaultValue="true" title="首次自动获取焦点" @change="change_auto_focus_boolean"></boolean-data>
<boolean-data :defaultValue="false" title="改变光标颜色为透明" @change="change_cursor_color_boolean"></boolean-data>
<boolean-data :defaultValue="false" title="设置禁用输入框"
@change="change_disabled_boolean"></boolean-data>
<enum-data :items="confirm_type_list" title="confirm-type,设置键盘右下角按钮。"
@change="radio_change_confirm_type"></enum-data>
<boolean-data :defaultValue="false" title="点击软键盘右下角按钮时是否保持键盘不收起(confirm-type为return时必然不收起)"
@change="change_confirm_hold_boolean"></boolean-data>
<enum-data :items="inputmode_enum" title="input-mode,控制软键盘类型。(仅限 Web 平台符合条件的高版本浏览器或webview)。"
@change="radio_change_inputmode_enum"></enum-data>
<boolean-data :defaultValue="false" title="是否显示键盘上方带有“完成”按钮那一栏(仅限小程序平台)"
@change="change_show_confirm_bar_boolean"></boolean-data>
<boolean-data :defaultValue="false" title="如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true(仅限小程序平台)"
@change
="change_fixed_boolean"></boolean-data>
<view class="title-wrap">
<view>maxlength 输入最大长度为10</view>
</view>
<view class="textarea-wrap">
<textarea id="textarea-instance-maxlength" class="textarea-instance" :value="textareaMaxLengthValue"
:maxlength="10" />
</view>
<view class="title-wrap">
<view>cursor-spacing、placeholder-class、placeholder-style例子(harmony 不支持设置 placeholder backgroundColor)</view>
</view>
<view class="textarea-wrap">
<textarea id="textarea-height-exception" class="textarea-instance" placeholder="底部textarea测试键盘遮挡"
placeholder-class="placeholder" placeholder-style="background-color:red" :cursor-spacing="300" />
</view>
<view class="title-wrap">
<view @click="setSelection(2, 5)">设置输入框聚焦时光标的起始位置和结束位置(点击生效)</view>
</view>
<view class="textarea-wrap">
<textarea id="textarea-instance-2" class="textarea-instance" value="Hello UniApp X Textarea TestCase" :focus="isSelectionFocus"
:selection-start="selectionStart" :selection-end="selectionEnd" @blur="onSelectionBlurChange" />
</view>
<view class="title-wrap">
<view>设置hold-keyboard</view>
<switch style="margin-left: 10px;" @change="changeHoldKeyboard" :checked="hold_keyboard"></switch>
</view>
<view class="textarea-wrap">
<textarea class="textarea-instance" :hold-keyboard="hold_keyboard" />
</view>
<view class="title-wrap">
<
view>同时存在 v-model 和 value</view>
</view>
<!-- harmony 不符合预期因为 switch 组件存在时,textarea 非预期 update 导致 -->
<view class="textarea-wrap">
<textarea id="both-model-value" class="textarea-instance" v-model='defaultModel' value='456'></textarea>
</view>
<view class="title-wrap">
<view>设置adjust-position</view>
<switch style="margin-left: 10px;" @change="changeAdjustPosition" :checked="adjust_position"></switch>
</view>
<view class="textarea-wrap">
<textarea class="textarea-instance" :adjust-position="adjust_position" />
</view>
<view v-if="isAutoTest" class="textarea-wrap">
<textarea id="test-width" class="test-width" value="123456" placeholder="" />
</view>
<view class="title-wrap">
<view>设置line-height</view>
</view>
<view class="textarea-wrap">
<textarea class="textarea-instance" style="line-height: 1.2em;" value="设置line-height为1.2em" ></textarea>
</view>
<view class="title-wrap">
<view>设置max-height与auto-height</view>
</view>
<view class="textarea-wrap">
<textarea class="textarea-instance" style="max-height: 50px;" auto-height="true" :value="default_value"></textarea>
</view>
<view class=
"title-wrap">
<view>同时设置value与text-align</view>
</view>
<view class="textarea-wrap">
<textarea class="textarea-instance" style="height: 50px;text-align: right;" value="同时设置value与text-align"></textarea>
</view>
<view class="title-wrap">
<view>scroll-view嵌套textarea滚动</view>
</view>
<scroll-view style="height: 150px;" direction="vertical">
<textarea class="textarea-instance" :adjust-position="false" :auto-height="true" :value="value2" />
</scroll-view>
</view>
<!-- #ifdef APP -->
</scroll-view>
<!-- #endif -->
</template>
<style>
.main {
min-height: 100px;
padding: 5px 0;
border-bottom: 1px solid rgba(0, 0, 0, 0.06);
flex-direction: row;
justify-content: center;
.test-width {
width: 100px;
height: 100px;
background-color: aqua;
.textarea-wrap {
flex-direction: row;
justify-content: center;
.title-wrap {
flex-direction: row;
align-items: center;
margin-left: 10px;
.textarea-instance {
flex: 1;
border: 1px solid #666;
margin: 10px;
.placeholder {
background-color: yellow;
</style>