textarea 多行文本输入框
收藏
我的收藏

基础库 1.0.0 开始支持本组件。

多行文本输入框。该组件是原生组件，支持同层渲染。

属性说明

属性名	类型	默认值	必填	说明	最低支持版本
value	string	无	否	输入框的内容	1.0.0
placeholder	string	无	否	输入框为空时占位符	1.0.0
placeholder-style	string	无	否	指定 placeholder 的样式，只支持 `font-size`、`font-weight`、`color` 三个 CSS 特性。	1.0.0
placeholder-class	string	无	否	指定 placeholder 的样式类	2.43.0
disabled	boolean	false	否	是否禁用	1.0.0
maxlength	number	140	否	最大输入长度，设置为 `-1` 的时候不限制最大长度。	1.0.0
focus	boolean	false	否	是否获得焦点，详情见 Bug & Tip。	1.0.0
auto-height	boolean	false	否	是否自动增高，设置 auto-height 时，设置 height 样式不生效。	1.0.0
cursor-spacing	number	0	否	指定软键盘弹出时，与光标的距离是多少，单位是 px。	1.0.0
cursor	number	-1	否	指定 focus 时的光标位置，详情见光标位置说明。	1.0.0
selection-start	number	-1	否	指定 focus 时选中片段的起始位置，详情见光标位置说明。	1.0.0
selection-end	number	-1	否	指定 focus 时选中片段的结束位置，详情见光标位置说明，	1.0.0
adjust-position	boolean	true	否	键盘弹起时，是否自动上推页面。	2.43.0
hold-keyboard	boolean	false	否	focus 时，点击页面的时候不收起键盘。	2.43.0
disable-default-padding	boolean	true	否	是否去掉 iOS 下的默认内边距。	2.24.0
confirm-type	string	return	否	设置键盘右下角按钮的文字，详情见 confirm-type 的合法值。	2.43.0
confirm-hold	boolean	false	否	点击键盘右下角按钮时是否保持键盘不收起。	2.43.0
show-confirm-bar	boolean	true	否	是否显示键盘上方带有”完成“按钮那一栏。	2.43.0
bindinput	EventHandle	无	否	键盘输入时触发，详情见 bindinput 说明。	1.0.0
bindfocus	EventHandle	无	否	输入框聚焦时触发，详情见 bindfocus 说明。	1.0.0
bindblur	EventHandle	无	否	输入框失去焦点时触发，详情见 bindblur 说明。	1.0.0
bindconfirm	EventHandle	无	否	用户点击键盘的完成按钮时触发，详情见 bindconfirm 说明。	1.0.0
bindlinechange	EventHandle	无	否	输入框行数变化时触发，详情见 bindlinechange 说明。	2.43.0
bindkeyboardheightchange	EventHandle	无	否	键盘高度发生变化的时候触发此事件，详情见 bindkeyboardheightchange 说明。	2.87.0

confirm-type 的合法值

值	说明	最低支持版本
send	右下角按钮为“发送”	2.43.0
search	右下角按钮为“搜索”	2.43.0
next	右下角按钮为“下一个”	2.43.0
go	右下角按钮为“前往”	2.43.0
done	右下角按钮为“完成”	2.43.0
return	右下角按钮为“换行”	2.43.0

光标位置说明

textarea 组件的光标受 cursor、selection-start、selection-end 三个属性共同影响，关系如下：

•

当值为 -1 时，表示不控制光标，光标置于文本末尾。

•

selection-start 和 selection-end 的优先级比 cursor 高，表示选中区域。

•

selection-start 和 selection-end 需要成对使用，只使用一个属性时并不会生效。

•

当设置的光标位置不合理时，光标置于文本末尾，下面列出 3 种常见的不合理设置：

◦

cursor 超出了 (0, text.length) 的范围selection-start。

◦

selection-end 超出了 (0, text.length) 的范围。

◦

selection-end < selection-start 时无效

•

cursor、selection-start、selection-end 三个属性都是半受控属性，详情见 Bug & Tip。

bindinput 说明

键盘输入时触发，事件对象的 detail 为 object 类型，属性如下：

属性名	类型	说明	最低支持版本
value	string	输入框的内容	1.0.0
cursor	number	光标位置	1.0.0

绑定的回调函数允许返回字符串，当返回 string 时会替换 textarea 内文本内容，也支持返回对象的形式同时控制输入框内容、光标位置，详情见代码示例。

bindfocus 说明

输入框获取焦点时触发，事件对象的 detail 为 object 类型，属性如下：

属性名	类型	说明	最低支持版本
value	string	输入框的内容	1.0.0
height	number	键盘高度	1.0.0

bindblur 说明

输入框失去焦点时触发，事件对象的 detail 为 object 类型，属性如下：

属性名	类型	说明	最低支持版本
value	string	输入框的内容	1.0.0

bindconfirm 说明

•

当 confirm-type 不等于 return 时，用户点击键盘的完成按钮时触发。

•

当 show-confirm-bar 为 true 时，点击键盘上方触控栏完成按钮时触发。

事件对象的 detail 为 object 类型，属性如下：

属性名	类型	说明	最低支持版本
value	string	输入框的内容	1.0.0

bindlinechange 说明

输入框行数变化（如用户换行）时触发，事件对象的 detail 为 object 类型，属性如下：

属性名	类型	说明	最低支持版本
height	number	输入框内容高度，单位 px	2.43.0
heightRpx	number	输入框内容高度，单位 rpx	2.43.0
lineCount	number	行数	2.43.0

bindkeyboardheightchange 说明

键盘高度发生变化时触发此事件，事件对象的 detail 为 object 类型，属性如下：

属性名	类型	说明	最低支持版本
height	number	键盘的具体高度	2.87.0
duration	number	键盘变化的动画耗时	2.87.0

扫码体验

请使用字节宿主 APP 扫码

代码示例

开发者工具中预览

html复制
<textarea
  placeholder="placeholder"
  bindinput="handleInput"
  bindfocus="handleFocus"
  bindblur="handleBlur"
  bindconfirm="handleConfirm"
  bindlinechange="handleLineChange"
/>

js复制
Page({
  data: {},
  handleInput(e) {
    console.log("input", e.detail);
  },
  handleFocus(e) {
    console.log("focus", e.detail);
  },
  handleBlur(e) {
    console.log("blur", e.detail);
  },
  handleConfirm(e) {
    console.log("confirm", e.detail);
  },
  handleLineChange(e) {
    console.log("linechange", e.detail);
  },
});

设置输入框的值

可以通过 setData 或 bindinput return 两种方式设置输入框的值。

setData 方式

html复制
<textarea
  type="number"
  placeholder="placeholder"
  bindinput="handleInput"
  value="{{value}}"
/>

js复制
Page({
  data: {
    value: "",
  },
  handleInput(e) {
    // 用户每输入 4 个数字，会额外输出一个空格符
    const value = e.detail.value.replace(/(\d{4})(?=\d)/g, "$1 ");
    this.setData({
      value: value,
    });
  },
});

return string 方式

html复制
<textarea type="number" placeholder="placeholder" bindinput="handleInput" />

js复制
Page({
  data: {},
  handleInput(e) {
    // 用户每输入 4 个数字，会额外输出一个空格符
    return e.detail.value.replace(/(\d{4})(?=\d)/g, "$1 ");
  },
});

return 对象方式

html复制
<textarea type="number" placeholder="placeholder" bindinput="handleInput" />

js复制
Page({
  data: {},
  handleInput() {
    // 不管输入什么，输入框里都显示 "bytedance" 且光标在 "byte" 后面
    return {
      value: "bytedance",
      cursor: 4,
    };
  },
});

Bug & Tip

•

Bug：少部分 Android 机型 fixed 样式会有异常，如果出现异常可在组件上添加fixed 属性；

•

Tip: textarea 是半受控组件，即该组件表现由用户行为和 data 两方共同决定。textarea 可以通过设置 value、focus、cursor、selection-start、selection-end 等属性来触发对应效果，但由用户行为导致的失去焦点，选择文字行为不会同步更新 data。因此不能根据 data 判断组件当前聚焦、光标选择的状态；

•