textarea

展示全部

# textarea

组件类型：UniTextareaElement

多行输入框

# 兼容性

Web	Android	iOS
4.0	3.9	4.11

# 属性

名称类型默认值兼容性描述

name

string

表单的控件名称，作为键值对的一部分与表单(form组件)一同提交

value

string

输入框的初始内容

placeholder

string

输入框为空时占位符

placeholder-style

string

指定 placeholder 的样式，目前仅支持color,font-size和font-weight

placeholder-class

string(string.ClassString)

指定 placeholder 的样式类，目前仅支持color,font-size和font-weight

maxlength

number

"不限制长度"

最大输入长度，0和正数为合法值，非法值的时候不限制最大长度

auto-focus

boolean

false

自动获取焦点，与focus属性对比，此属性只会首次生效。

focus

boolean

false

获取焦点

confirm-type

"return"

设置键盘右下角按钮的文字

合法值

兼容性

描述

return

换行

send

发送

搜索

下一个

前往

done

完成

cursor

number

指定focus时的光标位置

confirm-hold

boolean

false

点击键盘右下角按钮时是否保持键盘不收起

auto-height

boolean

false

是否自动增高，设置auto-height时，style.height不生效

fixed

boolean

如果 textarea 是在一个 position:fixed 的区域，需要显示指定属性 fixed 为 true

cursor-spacing

number

指定光标与键盘的距离，单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离

cursor-color

string(string.ColorString)

指定光标颜色

show-confirm-bar

boolean

是否显示键盘上方带有”完成“按钮那一栏

selection-start

number

-1

光标起始位置，自动聚集时有效，需与selection-end搭配使用

selection-end

number

-1

光标结束位置，自动聚集时有效，需与selection-satrt搭配使用

adjust-position

boolean

true

键盘弹起时，是否自动上推页面

inputmode

"text"

是一个枚举属性，它提供了用户在编辑元素或其内容时可能输入的数据类型的提示。在符合条件的高版本webview里，uni-app的 web 和 app-vue 平台中可使用本属性。

合法值

兼容性

描述

none

无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用。

text

使用用户本地区域设置的标准文本输入键盘。

decimal

小数输入键盘，包含数字和分隔符（通常是“ . ”或者“ , ”），设备可能也可能不显示减号键。

numeric

数字输入键盘，所需要的就是 0 到 9 的数字，设备可能也可能不显示减号键。

tel

电话输入键盘，包含 0 到 9 的数字、星号（*）和井号（#）键。表单输入里面的电话输入通常应该使用 <input type="tel"> 。

为搜索输入优化的虚拟键盘，比如，返回键可能被重新标记为“搜索”，也可能还有其他的优化。

为邮件地址输入优化的虚拟键盘，通常包含""符号和其他优化。表单里面的邮件地址输入应该使用 <input type="email"> 。

url

为网址输入优化的虚拟键盘，比如，“/”键会更加明显、历史记录访问等。表单里面的网址输入通常应该使用 <input type="url"> 。

hold-keyboard

boolean

false

focus时，点击页面的时候不收起键盘

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

名称

类型

必填

默认值

兼容性

描述

detail

UniTextareaFocusEventDetail

是

名称

类型

必备

默认值

兼容性

描述

height

number

是

键盘高度

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

Template

Script



<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <view class="main">
      <textarea :value="default_value" 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" @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"
        style="padding: 10px; border: 1px solid #666;height: 200px" />
    </view>
    <view class="content">
      <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>
      <enum-data :items="confirm_type_list" title="confirm-type，设置键盘右下角按钮。（Android仅支持return）"
        @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例子</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"
          :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>
      <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>
  <!-- #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;
  }

  .main .list-item {
    width: 100%;
    height: 100px;
    border: 1px solid #666;
  }

  .textarea-wrap {
    flex-direction: row;
    justify-content: center;
  }

  .title-wrap {
    flex-direction: row;
    align-items: center;
    margin-left: 10px;
  }

  .textarea-instance {
    flex: 1;
    border: 1 solid #666;
    margin: 10px;
  }

  .placeholder {
    background-color: yellow;
  }
</style>

# 参见

# 键盘上推专题

input和textarea组件都一个属性adjust-position，默认为true，即软键盘弹出时，默认上推页面以显示出输入框，避免输入框被软键盘遮挡。

因为此处内容与input重复，详见input文档

# inputmode说明

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

# 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属性。
当软键盘右下角为换行时，confirm-hold 恒为 true，设置为false也不生效，即按下换行时，软键盘不会消失。
在Android 9以下的系统版本，样式line-height点击键盘换行时行间距设置无效，此问题是Android系统的的bug，后续解决。