# textarea

多行输入框。

属性说明

属性名 类型 默认值 说明 平台差异说明
value String 输入框的内容
placeholder String 输入框为空时占位符
placeholder-style String 指定 placeholder 的样式
placeholder-class String textarea-placeholder 指定 placeholder 的样式类,注意页面或组件的style中写了scoped时,需要在类名前写/deep/ 抖音小程序、飞书小程序、快手小程序不支持
disabled Boolean false 是否禁用
maxlength Number 140 最大输入长度,设置为 -1 的时候不限制最大长度
focus Boolean false 获取焦点 在 H5 平台能否聚焦以及软键盘是否跟随弹出,取决于当前浏览器本身的实现。nvue 页面不支持,需使用组件的 focus()、blur() 方法控制焦点
auto-focus Boolean false 自动聚焦,拉起键盘 京东小程序
auto-height Boolean false 是否自动增高,设置auto-height时,style.height不生效
fixed Boolean false 如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true 微信小程序、百度小程序、抖音小程序、飞书小程序、QQ小程序、快手小程序、京东小程序
cursor-spacing Number 0 指定光标与键盘的距离,单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 App、微信小程序、百度小程序、抖音小程序、飞书小程序、QQ小程序、京东小程序
cursor Number 指定focus时的光标位置 微信小程序、App、H5、百度小程序、抖音小程序、飞书小程序、QQ小程序、京东小程序
cursor-color String 光标颜色 H5(4.0+)、App-Vue(4.0+)
confirm-type String done 设置键盘右下角按钮的文字 微信小程序基础库2.13.0+、App-vue和H5(2.9.9+,且要求设备webview内核Chrome81+、Safari13.7+)
confirm-hold Boolean false 点击键盘右下角按钮时是否保持键盘不收起 App(3.3.7+)、H5 (3.3.7+)、微信小程序 (基础库 2.16.0+)、百度小程序 (基础库 3.130.1+)、快手小程序
show-confirm-bar Boolean true 是否显示键盘上方带有”完成“按钮那一栏 微信小程序、百度小程序、QQ小程序、京东小程序
selection-start Number -1 光标起始位置,自动聚焦时有效,需与selection-end搭配使用 微信小程序、App、H5、百度小程序、抖音小程序、飞书小程序、QQ小程序、京东小程序
selection-end Number -1 光标结束位置,自动聚焦时有效,需与selection-start搭配使用 微信小程序、App、H5、百度小程序、抖音小程序、飞书小程序、QQ小程序、京东小程序
adjust-position Boolean true 键盘弹起时,是否自动上推页面 App-Android(softinputMode 为 adjustResize 时无效)、微信小程序、百度小程序、QQ小程序、京东小程序
disable-default-padding boolean false 是否去掉 iOS 下的默认内边距 微信小程序2.10.0、飞书小程序 3.46
hold-keyboard boolean false focus时,点击页面的时候不收起键盘 微信小程序2.8.2
auto-blur boolean false 键盘收起时,是否自动失去焦点 App-vue 3.0.0+ ,App-nvue不支持
ignoreCompositionEvent boolean true 是否忽略组件内对文本合成系统事件的处理。为 false 时将触发 compositionstart、compositionend、compositionupdate 事件,且在文本合成期间会触发 input 事件 App-vue (3.4.4+)、H5 (3.4.4+)、App-nvue不支持
inputmode String "text" 是一个枚举属性,它提供了用户在编辑元素或其内容时可能输入的数据类型的提示。有效值 H5(3.7.0+)、App-vue(3.7.0+)
@focus EventHandle 输入框聚焦时触发,event.detail = { value, height },height 为键盘高度 仅微信小程序、京东小程序、App(HBuilderX 2.0+ nvue uni-app模式) 、QQ小程序支持 height
@blur EventHandle 输入框失去焦点时触发,event.detail = {value, cursor} 快手小程序不支持
@linechange EventHandle 输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0} 抖音小程序、飞书小程序、快手小程序不支持
@input EventHandle 当键盘输入时,触发 input 事件,event.detail = {value, cursor}, @input 处理函数的返回值并不会反映到 textarea 上 快手小程序不支持
@confirm EventHandle 点击完成时, 触发 confirm 事件,event.detail = {value: value} 微信小程序、百度小程序、QQ小程序、京东小程序
@keyboardheightchange Eventhandle 键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration} 微信小程序基础库2.7.0+、App 3.1.0+

confirm-type 有效值

说明
send 右下角按钮为“发送”
search 右下角按钮为“搜索”
next 右下角按钮为“下一个”
go 右下角按钮为“前往”
done 右下角按钮为“完成”

示例 查看示例

以下示例代码,来自于hello uni-app项目,推荐使用HBuilderX,新建uni-app项目,选择hello uni-app模板,可直接体验完整示例。

Template

<!-- 本示例未包含完整css,获取外链css请参考上文,在hello uni-app项目中查看 -->
<template>
	<view>
		<view class="uni-title uni-common-pl">输入区域高度自适应,不会出现滚动条</view>
		<view class="uni-textarea">
			<textarea @blur="bindTextAreaBlur" auto-height />
			</view>
			<view class="uni-title uni-common-pl">占位符字体是红色的textarea</view>
			<view class="uni-textarea">
				<textarea placeholder-style="color:#F76260" placeholder="占位符字体是红色的"/>
			</view>
		</view>
</template>
<script>
export default {
    data() {
        return {}
    },
    methods: {
        bindTextAreaBlur: function (e) {
            console.log(e.detail.value)
        }
    }
}
</script>

Tips

  • textarea 的 blur 事件会晚于页面上的 tap 事件,如果需要在 button 的点击事件获取 textarea,可以使用 form 的 @submit。
  • 如果遇到 value 属性设置不生效的问题参考:组件属性设置不生效解决办法
  • 微信小程序、百度小程序、抖音小程序、飞书小程序中,textarea是原生组件,层级高于前端组件,请勿在 scroll-view、swiper、picker-view、movable-view 中使用 textarea 组件。覆盖textarea需要使用cover-view。详见
  • 小程序端 css 动画对 textarea 组件无效。
  • H5 平台只能在用户交互时修改 focus 生效。
  • 如果遇到 focus 属性设置不生效的问题参考:组件属性设置不生效解决办法
  • 软键盘的弹出和收起逻辑,详见input的文档
  • 如需禁止点击其他位置收起键盘的默认行为,可以监听touch事件并使用prevent修饰符(仅支持App、H5,其他平台可以通过设置focus来使输入框重新获取焦点),例如在确认按钮上使用:@touchend.prevent="onTap"
  • js中给textarea组件赋值为字符串,在字符串中加\n可实现换行。
  • nvue 样式 word-wrap 在 Android 平台暂不支持
  • 旧版本chrome或同内核浏览器会将输入多个标点符号放在一行,此时可通过将textarea样式设置为word-break: break-word;实现自动换行。
  • placeholder-style指定样式类font-size单位为rpx时,抖音小程序、飞书小程序、快手小程序不支持,可使用uni.upx2px()将rpx单位值转换成px。
  • App-iOS nvue页面默认是收起键盘,如果想换行需要设置confirm-hold为true。
<template>
    <view class="content">
        <textarea class="textarea" v-model="txt"></textarea>
    </view>
</template>
<script>
    export default {
        data() {
            return {
                "txt":"hello world!\n textarea多行输入框"
            }
        }
    }
</script>

nvue下键盘右下角按钮点击仅触发换行;如想监听该按钮事件可以参考,示例代码如下:

<template>
	<view class="content">
		<textarea class="textarea" v-model="txt"></textarea>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				txt:"txt"
			}
		},
		watch: {
			txt(txt) {
				if( txt.indexOf('\n') != -1 ){ //敲了回车键了
				   uni.hideKeyboard() //收起软键盘
				}
			}
		},
		methods: {
		}
	}
</script>

<style>
.textarea{
	border: solid 1px red;
}
</style>

# inputmode 有效值

新增于 uni-app 3.7.0+ inputmode是html规范后期更新的内容。各家小程序还未支持此属性。

在符合条件的高版本webview里,uni-app的web和app-vue平台中可使用本属性。

说明
none 无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用。
text 使用用户本地区域设置的标准文本输入键盘。
decimal 小数输入键盘,包含数字和分隔符(通常是“ . ”或者“ , ”),设备可能也可能不显示减号键。
numeric 数字输入键盘,所需要的就是 0 到 9 的数字,设备可能也可能不显示减号键。
tel 电话输入键盘,包含 0 到 9 的数字、星号(*)和井号(#)键。表单输入里面的电话输入通常应该使用 <input type="tel"> 。
search 为搜索输入优化的虚拟键盘,比如,返回键可能被重新标记为“搜索”,也可能还有其他的优化。
email 为邮件地址输入优化的虚拟键盘,通常包含"@"符号和其他优化。表单里面的邮件地址输入应该使用 <input type="email"> 。
url 为网址输入优化的虚拟键盘,比如,“/”键会更加明显、历史记录访问等。表单里面的网址输入通常应该使用 <input type="url"> 。

注意事项

  • inputmode 兼容性:Chrome >= 66Edge >= 79Firefox >= 95Chrome Android >= 66Firefox for Android >= 79Safari on iOS >= 12.2WebView Android >= 66
  • input组件有 inputmodetypecomfirm-tye 3个相似的属性,它们的区别详解如下:
    • type:在 uni-app 和小程序中仅仅是输入框,定义 input 的工作方式,此值决定可输入什么值。比如 number 只能输入数字。
    • comfirm-type:定义键盘右下角按键的文字
    • inputmode:inputmode 属性是当使用某些值时会对键盘所作出的优化。
      • 同时使用 inputmode 和 comfirm-type 时,若设值冲突,键盘右下角按键类型由 comfirm-type 决定
      • type 属性和 inputmode 属性并不冲突

富文本编辑的解决方案 在输入框里图文混排内容,在web上该功能依赖document,而小程序和app的正常页面又没有document。

  • 方式一:使用uni-app自带的editor组件,该组件支持App、H5、微信小程序,其他家小程序自身未提供这类解决方案。
  • 方式二:采用markdown编辑器方案,输入区输入markdown语法,预览区提供预览。这种方式可以跨端。插件市场搜富文本编辑,有不少插件。
  • 方式三:使用web-view组件,加载html页面,此时可使用web中常见的各种富文本编辑器,插件市场也有这类插件。