input 输入框
收藏
我的收藏

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

输入框组件，用于键盘交互。

属性说明

属性名	类型	默认值	必填	说明	最低支持版本
value	string	无	否	输入框的初始值。	1.0.0
type	string	text	否	input 的类型，详情见 type 的合法值。	1.0.0
password	boolean	false	否	是否是密码类型。	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.57.0
disabled	boolean	false	否	是否禁用。	1.0.0
maxlength	number	140	否	最大输入长度。	1.0.0
cursor-spacing	number	0	否	指定软键盘弹出时，与光标的距离是多少，单位是 px。	1.0.0
focus	boolean	false	否	获取焦点，详情见 Bug & Tip。	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	否	键盘弹起时，是否自动上推页面。	1.0.0
confirm-type	string	done	否	设置键盘右下角按钮的文字，仅在 `type='text'` 时生效，详情见 confirm-type 的合法值。	1.0.0
confirm-hold	boolean	false	否	点击键盘右下角按钮时是否保持键盘不收起。	2.57.0
hold-keyboard	boolean	false	否	focus 时，点击页面的时候不收起键盘。	2.57.0
bindinput	EventHandle	无	否	键盘输入时触发，处理函数可以直接 return 一个字符串，将替换输入框的内容，详情见 bindinput 说明。	1.0.0
bindfocus	EventHandle	无	否	输入框聚焦时触发，详情见 bindfocus 说明。	1.0.0
bindblur	EventHandle	无	否	输入框失去焦点时触发，详情见 bindblur 说明。	1.0.0
bindconfirm	EventHandle	无	否	用户点击键盘的完成按钮时触发，详情见 bindconfirm 说明。	1.0.0
bindkeyboardheightchange	EventHandle	无	否	键盘高度发生变化的时候触发此事件，详情见 bindkeyboardheightchange 说明。	2.87.0

type 的合法值

值	说明	最低支持版本
text	文本输入键盘	1.0.0
number	数字输入键盘	1.0.0
digit	带小数点的数字键盘	1.0.0

confirm-type 的合法值

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

光标位置说明

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

•

当值为 -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 时会替换 input 内文本内容，也支持返回对象的形式同时控制输入框内容、光标位置，详情见代码示例。

bindfocus 说明

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

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

bindblur 说明

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

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

bindconfirm 说明

用户点击键盘的完成按钮时触发，事件对象的 detail 为 object 类型，属性如下：

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

bindkeyboardheightchange 说明

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

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

扫码体验

**请使用字节宿主APP扫码**

代码示例

开发者工具中预览

<input
  type="text"
  placeholder="placeholder"
  bindinput="handleInput"
  bindfocus="handleFocus"
  bindblur="handleBlur"
  bindconfirm="handleConfirm"
  bindkeyboardheightchange="handleKeyboardHeightChange"
/>

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);
  },
  handleKeyboardHeightChange(e) {
    console.log("keyboardHeightChange", e.detail);
  },
});

获取用户输入的值

<input
  type="text"
  placeholder="placeholder"
  bindinput="handleInput"
  value="{{value}}"
/>
<button type="default" size="default" bindtap="getInputValue">
  获取输入框内容
</button>

Page({
  data: {
    value: "",
  },
  handleInput(e) {
    this.setData({
      value: e.detail.value,
    });
  },
  getInputValue() {
    tt.showToast({
      title: this.data.value,
    });
  },
});

清空输入框

<input
  type="text"
  placeholder="placeholder"
  bindinput="handleInput"
  value="{{value}}"
/>
<button type="default" size="default" bindtap="getInputValue">
  获取输入框内容
</button>
<button type="default" size="default" bindtap="clear">清空输入框</button>

Page({
  data: {
    value: "",
  },
  handleInput(e) {
    this.setData({
      value: e.detail.value,
    });
  },
  getInputValue() {
    tt.showToast({
      title: this.data.value,
    });
  },
  clear() {
    this.setData({
      value: "",
    });
  },
});

自动获取键盘焦点

<input type="text" placeholder="placeholder" focus="{{autoFocus}}" />

Page({
  data: {
    autoFocus: true,
  },
});

设置输入框的值

可以通过 setData 或 bindinput return 两种方式设置输入框的值，两种方式各有优势：

•

通过 setData 设置输入框的值，用户输入的内容会与输入框绑定的 value 相关联，获取用户输入内容、清空输入框等操作都会比较容易。但频繁的执行 setData 回调在部分低端机型中性能表现较差。

•

通过 bindinput return 的方式设置输入框的值没有性能问题，但此时用户输入并不会直接响应到 input 绑定的 value 上。

•

可以根据实际情况选择上述的一种方法，也可以组合使用两种方法来给用户提供最佳的使用体验。

setData 方式

<input
  type="number"
  placeholder="placeholder"
  bindinput="handleInput"
  value="{{value}}"
/>

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

return string 方式

<input type="number" placeholder="placeholder" bindinput="handleInput" />

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

return 对象方式

<input type="number" placeholder="placeholder" bindinput="handleInput" />

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

复杂场景下组合使用

<input
  type="number"
  placeholder="placeholder"
  bindinput="handleInput"
  value="{{showValue}}"
/>
<button type="default" size="default" bindtap="show">展示输入框内容</button>
<button type="default" size="default" bindtap="clear">清空输入框</button>

Page({
  data: {
    showValue: "", // input 框的展示的值
    _value: "", // 用来存储用户输入的内容
  },
  handleInput(e) {
    // 用户每输入 4 个数字，会额外输出一个空格符
    const value = e.detail.value.replace(/(\d{4})(?=\d)/g, "$1 ");
    // 数据上，存储用户输入的内容
    this.setData({
      _value: value,
    });
    // 视图上，通过 return string 的方式高效渲染
    return value;
  },
  // 展示用户输入内容
  show() {
    tt.showToast({
      title: this.data._value,
    });
  },
  // 清空输入框
  clear() {
    this.setData(
      {
        showValue: this.data._value,
      },
      () => {
        this.setData({
          showValue: "",
          _value: "",
        });
      }
    );
  },
});

Bug & Tip

•

Bug：input 使用 catch 绑定事件时会无法拉起键盘；

•

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

•

Tip：当 input 没有宽度时，默认跟随父组件宽度。当所有祖先节点都没有宽度时，会触发兜底策略，但不同设备、不同系统上默认宽度表现略有差异；

•

Tip：hold-keyboard 时点击页面不会收起键盘，但滑动页面仍会收起键盘。

input 输入框收藏我的收藏

​属性说明​

​type 的合法值​

​confirm-type 的合法值​

​光标位置说明​

​bindinput 说明​

​bindfocus 说明​

​bindblur 说明​

​bindconfirm 说明​

​bindkeyboardheightchange 说明​

​扫码体验​

​代码示例​

​获取用户输入的值​

​清空输入框​

​自动获取键盘焦点​

​设置输入框的值​

​setData 方式​

​return string 方式​

​return 对象方式​

​复杂场景下组合使用​

​Bug & Tip​