开发
API

input

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

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

属性说明

属性名类型默认值必填说明最低支持版本
valuestring""输入框的初始值。如果想在键盘输入时改变 input 框的值,可以直接在 bindinput 回调里 return 指定值,详细示例1.0.0
typestringtextinput 的类型,详情见下方说明1.0.0
passwordbooleanfalse是否为密码输入1.0.0
placeholderstring""占位字符1.0.0
placeholder-stylestring占位符的样式1.0.0
disabledbooleanfalse是否禁用1.0.0
maxlengthnumber140最大输入长度1.0.0
focusbooleanfalse获取焦点,详情见下方 Tip1.0.0
cursor-spacingnumber0指定软键盘弹出时,与光标的距离是多少,单位是 px1.0.0
cursornumber-1指定 focus 时的光标位置,详情见下方 Tip1.0.0
selection-startnumber-1指定 focus 时选中片段的起始位置,详情见下方 Tip1.0.0
selection-endnumber-1指定 focus 时选中片段的结束位置,详情见下方 Tip1.0.0
bindinputfunction键盘输入时触发,详见下方说明1.0.0
bindfocusfunction输入框聚焦时触发,详见下方说明1.0.0
bindblurfunction输入框失去焦点时触发,详见下方说明1.0.0
bindconfirmfunction用户点击键盘的完成按钮时触发,详见下方说明1.0.0
adjust-positionbooletrue键盘弹起时,是否自动上推页面1.0.0
confirm-typestringdone设置键盘右下角按钮的文字,仅在 type='text'时生效1.0.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

bindinput 说明

  • 键盘输入时触发, 若返回 string 则替换 input 内文本内容。
  • bindinput event 介绍

    • event.detail.value 为输入框内容
    • event.detail.cursor 为光标位置
  • bindinput 中改变输入值有以下方式

【代码示例 1】通过 return 设置输入框值

<input bindinput="handleInput" />
Page({
  handleInput(event) {
    console.log(event.detail.cursor);

    // 每一次输入内容后面都追加一个 “!”
    return event.detail.value + "!";
  },
});

【代码示例 2】通过 setData 设置输入框值

<input value="{{inputValue}}" bindinput="handleInput" />
Page({
  data: {
    inputValue: "",
  },
  handleInput(event) {
    const value = event.detail.value;
    this.setData({
      inputValue: value,
    });
  },
});

【代码示例 3】通过 setData 设置输入框值(某些情境下设置为固定值)

<input value="{{inputValue}}" bindinput="handleInput" />
Page({
  data: {
    inputValue: "",
  },
  handleInput(event) {
    const value = event.detail.value;
    if (value === "byte") {
      this.setData(
        {
          inputValue: value,
        },
        () => {
          this.setData({
            inputValue: "ByteDance",
          });
        }
        // 或者直接 return 'ByteDance'
      );
    }
  },
});

bindfocus 说明

输入框获取焦点时触发

event.detail.value 为输入框内容

event.detail.height 为键盘高度

<input bindfocus="handleFocus" />
Page({
  handleFocus(event) {
    console.log(event.detail.value); // 输出 input 内容
    console.log(event.detail.height); // 输出键盘高度
  },
});

bindblur 说明

输入框失去焦点时触发

event.detail.value 为输入框内容

<input bindblur="handleBlur" />
Page({
  handleBlur(event) {
    console.log(event.detail.value); // 输出 input 内容
  },
});

bindconfirm 说明

用户点击键盘的完成按钮时触发

event.detail.value 为输入框内容

<input bindconfirm="handleConfirm" />
Page({
  handleConfirm(event) {
    console.log(event.detail.value); // 输出 input 内容
  },
});

效果示例

代码示例

开发者工具中预览

<view class="page-cells page-cells_after-title">
  <view class="page-cell page-cell_input">
    <input
      class="page-input"
      placeholder="这个只有在按钮点击的时候才聚焦"
      focus="{{focus}}"
    />
  </view>
</view>
<view class="btn-area">
  <button bindtap="bindButtonTap">使得输入框获取焦点</button>
</view>

<view class="page-cells page-cells_after-title">
  <view class="page-cell page-cell_input">
    <input
      class="page-input"
      placeholder="focus详情"
      bindfocus="onfocus"
      bindconfirm="onconfirm"
    />
  </view>
</view>

<view class="btn-area">{{focusDetail}}</view>

<view class="page-cells page-cells_after-title">
  <view class="page-cell page-cell_input">
    <input class="page-input" placeholder="blur测试" bindblur="onblur" />
  </view>
</view>
Page({
  data: {
    focus: false,
  },
  bindButtonTap: function (e) {
    this.setData({
      focus: true,
    });
  },
  onfocus: function (e) {
    console.log(e);
    this.setData({ focusDetail: JSON.stringify(e.detail) });
  },
  onblur: function (e) {
    tt.showToast({ title: "blur" });
  },
  onconfirm: function (e) {
    tt.showToast({ title: "confirm" });
  },
});

扫码体验

请使用字节宿主APP扫码

Bug & Tip

  • Tip: 避免过于频繁地在 bindinput 回调里执行 setData({ value: ... }),如果想在键盘输入时改变 input 框的值,可以直接在 bindinput 回调里 return 一个字符串。
  • Tip: 重新设置 focus cursor selection-start selection-end 可以触发对应效果。 但由用户行为导致的失去焦点选择文字 行为不会同步更新 data。因此使用 this.setData 更新关联 data 可以理解为派发了一个事件,但是不能根据 data 判断组件当前状态。
点击纠错
评价此篇文档