# textarea

组件类型: UniTextareaElement

多行输入框

# 兼容性

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

# 属性

名称 类型 默认值 兼容性 描述
name string -
微信小程序 Android HarmonyOS
4.0 x 3.9 4.11 4.61
表单的控件名称,作为键值对的一部分与表单(form组件)一同提交
disabled boolean false
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
是否禁用
value string ""
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
输入框的初始内容
placeholder string ""
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
输入框为空时占位符
placeholder-style string ""
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
指定 placeholder 的样式
placeholder-class string( string.ClassString ) ""
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
指定 placeholder 的样式类
maxlength number "不限制长度"
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
最大输入长度,0和正数为合法值,非法值的时候不限制最大长度
auto-focus boolean false
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
自动获取焦点,与 focus 属性对比,此属性只会首次生效。
focus boolean false
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
获取焦点
confirm-type return | send | search | next | go | done "return"
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.15 4.61
设置键盘右下角按钮的文字
合法值 兼容性 描述
return
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.15 4.61
换行
send
微信小程序 Android HarmonyOS
4.0 4.41 4.73 4.15 4.61
发送
search
微信小程序 Android HarmonyOS
4.0 4.41 4.73 4.15 4.61
搜索
next
微信小程序 Android HarmonyOS
4.0 4.41 4.73 4.15 4.61
下一个
go
微信小程序 Android HarmonyOS
4.0 4.41 4.73 4.15 4.61
前往
done
微信小程序 Android HarmonyOS
4.0 4.41 4.73 4.15 4.61
完成
cursor number 0
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
指定focus时的光标位置
confirm-hold boolean false
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
点击键盘右下角按钮时是否保持键盘不收起
auto-height boolean false
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.65
是否自动增高,设置auto-height时,style.height不生效
cursor-spacing number 0
微信小程序 Android HarmonyOS
x 4.41 3.9 4.11 x
指定光标与键盘的距离,单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离
cursor-color string( string.ColorString ) ""
微信小程序 Android HarmonyOS
- 4.41 3.99 4.11 4.61
指定光标颜色
selection-start number -1
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
光标起始位置,自动聚集时有效,需与selection-end搭配使用
selection-end number -1
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
光标结束位置,自动聚集时有效,需与selection-satrt搭配使用
adjust-position boolean true
微信小程序 Android HarmonyOS
x 4.41 3.9 4.11 4.61
键盘弹起时,是否自动上推页面
hold-keyboard boolean false
微信小程序 Android HarmonyOS
x 4.41 4.0 4.11 4.61
focus时,点击页面的时候不收起键盘
inputmode none | text | decimal | numeric | tel | search | email | url "text"
微信小程序 Android HarmonyOS
4.0 x x x 4.61
是一个枚举属性,它提供了用户在编辑元素或其内容时可能输入的数据类型的提示。在符合条件的高版本webview里,uni-app的 web 和 app-vue 平台中可使用本属性。
合法值 兼容性 描述
none
微信小程序 Android HarmonyOS
- - x x -
无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用。
text
微信小程序 Android HarmonyOS
- - x x -
使用用户本地区域设置的标准文本输入键盘。
decimal
微信小程序 Android HarmonyOS
- - x x -
小数输入键盘,包含数字和分隔符(通常是“ . ”或者“ , ”),设备可能也可能不显示减号键。
numeric
微信小程序 Android HarmonyOS
- - x x -
数字输入键盘,所需要的就是 0 到 9 的数字,设备可能也可能不显示减号键。
tel
微信小程序 Android HarmonyOS
- - x x -
电话输入键盘,包含 0 到 9 的数字、星号(*)和井号(#)键。表单输入里面的电话输入通常应该使用 <input type="tel"> 。
search
微信小程序 Android HarmonyOS
- - x x -
为搜索输入优化的虚拟键盘,比如,返回键可能被重新标记为“搜索”,也可能还有其他的优化。
email
微信小程序 Android HarmonyOS
- - x x -
为邮件地址输入优化的虚拟键盘,通常包含""符号和其他优化。表单里面的邮件地址输入应该使用 <input type="email"> 。
url
微信小程序 Android HarmonyOS
- - x x -
为网址输入优化的虚拟键盘,比如,“/”键会更加明显、历史记录访问等。表单里面的网址输入通常应该使用 <input type="url"> 。
fixed boolean -
微信小程序 Android HarmonyOS
x 4.41 x x -
如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true
show-confirm-bar boolean -
微信小程序 Android HarmonyOS
x 4.41 x x -
是否显示键盘上方带有”完成“按钮那一栏
disabled boolean -
微信小程序 Android HarmonyOS
- 4.41 - - -
(boolean)
是否禁用
disable-default-padding boolean -
微信小程序 Android HarmonyOS
- 4.41 - - -
(boolean)
是否去掉 iOS 下的默认内边距
adjust-keyboard-to boolean -
微信小程序 Android HarmonyOS
- 4.41 - - -
(boolean)
键盘对齐位置
合法值 兼容性 描述
cursor
微信小程序 Android HarmonyOS
- 4.41 - - -
对齐光标位置
bottom
微信小程序 Android HarmonyOS
- 4.41 - - -
对齐输入框底部
@confirm (event: UniInputConfirmEvent ) => void -
微信小程序 Android HarmonyOS
4.0 4.41 4.73 4.73 4.61
点击完成时, 触发 confirm 事件,event.detail = {value: value}
@input (event: UniInputEvent ) => void -
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
当键盘输入时,触发 input 事件,event.detail = {value, cursor}, @input 处理函数的返回值并不会反映到 textarea 上
@linechange (event: UniTextareaLineChangeEvent ) => void -
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.65
输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0}
@blur (event: UniTextareaBlurEvent ) => void -
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
输入框失去焦点时触发,event.detail = {value, cursor}
@keyboardheightchange (event: UniInputKeyboardHeightChangeEvent ) => void -
微信小程序 Android HarmonyOS
x 4.41 3.9 4.11 4.61
键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}
@focus (event: UniTextareaFocusEvent ) => void -
微信小程序 Android HarmonyOS
4.0 4.41 3.9 4.11 4.61
输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持
@change (event: UniInputChangeEvent ) => void -
微信小程序 Android HarmonyOS
4.81 4.41 4.73 4.73 4.73
非聚焦状态内容改变时触发(仅组件失去焦点时且用户输入改变内容才触发)

# 事件

# UniInputConfirmEvent

# UniInputConfirmEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniInputConfirmEventDetail - - -
名称 类型 必备 默认值 兼容性 描述
value string - - 输入框内容

# UniInputEvent

# UniInputEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniInputEventDetail - - -
名称 类型 必备 默认值 兼容性 描述
value string - - 输入框内容
cursor number - - 光标的位置
keyCode number - - 输入字符的Unicode值

# UniTextareaLineChangeEvent

# UniTextareaLineChangeEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniTextareaLineChangeEventDetail - - -
名称 类型 必备 默认值 兼容性 描述
lineCount number - - 行数
heightRpx number - - textarea的高度
height number - - textarea的高度

# UniTextareaBlurEvent

# UniTextareaBlurEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniTextareaBlurEventDetail - - -
名称 类型 必备 默认值 兼容性 描述
value string - - 输入框内容
cursor number - - 选择区域的起始位置

# UniInputKeyboardHeightChangeEvent

# UniInputKeyboardHeightChangeEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniInputKeyboardHeightChangeEventDetail - - -
名称 类型 必备 默认值 兼容性 描述
height number - - 键盘高度
duration number - - 持续时间

# UniTextareaFocusEvent

# UniTextareaFocusEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniTextareaFocusEventDetail - - -
名称 类型 必备 默认值 兼容性 描述
height number -
微信小程序 Android HarmonyOS
x - 3.9 4.11 -
键盘高度
value string - - 输入框内容

# UniInputChangeEvent

# UniInputChangeEvent 的属性值
名称 类型 必填 默认值 兼容性 描述
detail UniInputChangeEventDetail - - -
名称 类型 必备 默认值 兼容性 描述
value string - - 输入框内容

# 获取原生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分支示例 另见

扫码体验(手机浏览器跳转到App直达页)
扫码体验

示例

<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>