# input

> 基础库 1.0.0 开始支持，低版本需做[兼容处理](1003706)。

> __微信 Windows 版__：支持
> 
> __微信 Mac 版__：支持
> 
> __微信 鸿蒙 OS 版__：支持

渲染框架支持情况：Skyline （使用最新 [Nightly](/miniprogram/dev/devtools/nightly.html) 工具调试）、WebView

## 功能描述

输入框。该组件是[原生组件](/miniprogram/dev/component/native-component)，使用时请注意相关限制

## 通用属性


```json
[
  {
    "属性": "value",
    "类型": "string",
    "默认值": "",
    "必填": "是",
    "说明": "输入框的初始内容",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "type",
    "类型": "string",
    "默认值": "text",
    "必填": "否",
    "说明": "input 的类型",
    "最低版本": "[1.0.0](1003706)",
    "子项": [
      {
        "合法值": "text",
        "说明": "文本输入键盘",
        "最低版本": ""
      },
      {
        "合法值": "number",
        "说明": "数字输入键盘",
        "最低版本": ""
      },
      {
        "合法值": "idcard",
        "说明": "身份证输入键盘",
        "最低版本": ""
      },
      {
        "合法值": "digit",
        "说明": "带小数点的数字键盘",
        "最低版本": ""
      },
      {
        "合法值": "safe-password",
        "说明": "密码安全输入键盘 [指引](/miniprogram/dev/framework/open-ability/safe-password.md)。仅 Webview 支持。",
        "最低版本": "[2.18.0](1003706)"
      },
      {
        "合法值": "nickname",
        "说明": "昵称输入键盘。",
        "最低版本": "[2.21.2](1003706)"
      }
    ]
  },
  {
    "属性": "password",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否是密码类型",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "placeholder",
    "类型": "string",
    "默认值": "",
    "必填": "是",
    "说明": "输入框为空时占位符",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "placeholder-style",
    "类型": "string",
    "默认值": "",
    "必填": "是",
    "说明": "指定 placeholder 的样式",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "disabled",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "是否禁用",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "maxlength",
    "类型": "number",
    "默认值": "140",
    "必填": "否",
    "说明": "最大输入长度，设置为 -1 的时候不限制最大长度",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "cursor-spacing",
    "类型": "number",
    "默认值": "0",
    "必填": "否",
    "说明": "指定光标与键盘的距离，取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "auto-focus",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "(即将废弃，请直接使用 focus )自动聚焦，拉起键盘",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "focus",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "获取焦点",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "confirm-type",
    "类型": "string",
    "默认值": "done",
    "必填": "否",
    "说明": "设置键盘右下角按钮的文字，仅在type='text'时生效",
    "最低版本": "[1.1.0](1003706)",
    "子项": [
      {
        "合法值": "send",
        "说明": "右下角按钮为“发送”"
      },
      {
        "合法值": "search",
        "说明": "右下角按钮为“搜索”"
      },
      {
        "合法值": "next",
        "说明": "右下角按钮为“下一个”"
      },
      {
        "合法值": "go",
        "说明": "右下角按钮为“前往”"
      },
      {
        "合法值": "done",
        "说明": "右下角按钮为“完成”"
      }
    ]
  },
  {
    "属性": "always-embed",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "强制 input 处于同层状态，默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效)",
    "最低版本": "[2.10.4](1003706)"
  },
  {
    "属性": "confirm-hold",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "点击键盘右下角按钮时是否保持键盘不收起",
    "最低版本": "[1.1.0](1003706)"
  },
  {
    "属性": "cursor",
    "类型": "number",
    "默认值": "",
    "必填": "是",
    "说明": "指定focus时的光标位置",
    "最低版本": "[1.5.0](1003706)"
  },
  {
    "属性": "cursor-color",
    "类型": "string",
    "默认值": "",
    "必填": "是",
    "说明": "光标颜色。iOS 下的格式为十六进制颜色值 #000000，安卓下的只支持 default 和 green，Skyline 下无限制",
    "最低版本": "[3.1.0](1003706)"
  },
  {
    "属性": "selection-start",
    "类型": "number",
    "默认值": "-1",
    "必填": "否",
    "说明": "光标起始位置，自动聚集时有效，需与selection-end搭配使用",
    "最低版本": "[1.9.0](1003706)"
  },
  {
    "属性": "selection-end",
    "类型": "number",
    "默认值": "-1",
    "必填": "否",
    "说明": "光标结束位置，自动聚集时有效，需与selection-start搭配使用",
    "最低版本": "[1.9.0](1003706)"
  },
  {
    "属性": "adjust-position",
    "类型": "boolean",
    "默认值": "true",
    "必填": "否",
    "说明": "键盘弹起时，是否自动上推页面",
    "最低版本": "[1.9.90](1003706)"
  },
  {
    "属性": "hold-keyboard",
    "类型": "boolean",
    "默认值": "false",
    "必填": "否",
    "说明": "focus时，点击页面的时候不收起键盘",
    "最低版本": "[2.8.2](1003706)"
  },
  {
    "属性": "safe-password-cert-path",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "安全键盘加密公钥的路径，只支持包内路径。鸿蒙 OS 暂不支持",
    "最低版本": "[2.18.0](1003706)"
  },
  {
    "属性": "safe-password-length",
    "类型": "number",
    "默认值": "",
    "必填": "否",
    "说明": "安全键盘输入密码长度。鸿蒙 OS 暂不支持",
    "最低版本": "[2.18.0](1003706)"
  },
  {
    "属性": "safe-password-time-stamp",
    "类型": "number",
    "默认值": "",
    "必填": "否",
    "说明": "安全键盘加密时间戳。鸿蒙 OS 暂不支持",
    "最低版本": "[2.18.0](1003706)"
  },
  {
    "属性": "safe-password-nonce",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "安全键盘加密盐值。鸿蒙 OS 暂不支持",
    "最低版本": "[2.18.0](1003706)"
  },
  {
    "属性": "safe-password-salt",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "安全键盘计算hash盐值，若指定custom-hash 则无效。鸿蒙 OS 暂不支持",
    "最低版本": "[2.18.0](1003706)"
  },
  {
    "属性": "safe-password-custom-hash",
    "类型": "string",
    "默认值": "",
    "必填": "否",
    "说明": "安全键盘计算hash的算法表达式，如 \u0000INLINECODE_0\u0000。鸿蒙 OS 暂不支持",
    "最低版本": "[2.18.0](1003706)"
  },
  {
    "属性": "bind:input",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "是",
    "说明": "键盘输入时或内容改变时触发。event.detail = { value: string, cursor?: number, keyCode?: number }，cursor 为光标位置，keyCode 为键值。2.1.0 起支持，处理函数可以直接 return 一个字符串，将替换输入框的内容。",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:change",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "是",
    "说明": "键盘非聚焦状态内容改变时触发。event.detail = { value: string }",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:focus",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "是",
    "说明": "输入框聚焦时触发，event.detail = { value: string, height: number }，height 为键盘高度，在基础库 1.9.90 起支持",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:blur",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "是",
    "说明": "输入框失去焦点时触发，event.detail = { value: string, encryptedValue?: string, encryptError?: string }",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:confirm",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "是",
    "说明": "点击完成按钮时触发，event.detail = { value: string, encryptedValue?: string, encryptError?: string }",
    "最低版本": "[1.0.0](1003706)"
  },
  {
    "属性": "bind:keyboardheightchange",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "是",
    "说明": "键盘高度发生变化的时候触发此事件，event.detail = {height: number, duration: number}",
    "最低版本": "[2.7.0](1003706)"
  },
  {
    "属性": "bind:nicknamereview",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "是",
    "说明": "用户昵称审核完毕后触发，仅在 type 为 \"nickname\" 时有效，event.detail = { pass: boolean, timeout: boolean }",
    "最低版本": "[2.29.1](1003706)"
  }
]
```

## Skyline 特有属性


```json
[
  {
    "属性": "bind:selectionchange",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "选区改变事件, {selectionStart, selectionEnd}",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "bind:keyboardcompositionstart",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入法开始新的输入时触发 （仅当输入法支持时触发）",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "bind:keyboardcompositionupdate",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入法输入字符时触发（仅当输入法支持时触发）",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "bind:keyboardcompositionend",
    "类型": "eventhandle",
    "默认值": "",
    "必填": "否",
    "说明": "输入法输入结束时触发（仅当输入法支持时触发）",
    "最低版本": "[3.2.0](1003706)"
  },
  {
    "属性": "worklet:onkeyboardheightchange",
    "类型": "worklet",
    "默认值": "",
    "必填": "否",
    "说明": "键盘高度变化时触发。event.detail = {height: height, pageBottomPadding: pageBottomPadding}； height: 键盘高度，pageBottomPadding: 页面上推高度",
    "最低版本": "[3.2.4](1003706)"
  }
]
```

## WebView 特有属性


```json
[
  {
    "属性": "placeholder-class",
    "类型": "string",
    "默认值": "input-placeholder",
    "必填": "否",
    "说明": "指定 placeholder 的样式类",
    "最低版本": "[1.0.0](1003706)"
  }
]
```

## Bug & Tip

1. `tip`: confirm-type的最终表现与手机输入法本身的实现有关，部分安卓系统输入法和第三方输入法可能不支持或不完全支持
1. `tip` : input 组件是一个原生组件，字体是系统字体，所以无法设置 font-family
1. `tip` : 在 input 聚焦期间，避免使用 css 动画
1. `tip` : 对于将 `input` 封装在自定义组件中、而 `form` 在自定义组件外的情况， `form` 将不能获得这个自定义组件中 `input` 的值。此时需要使用自定义组件的 [内置 behaviors](/miniprogram/dev/framework/component-framework/behaviors.md) `wx://form-field`
1. `tip` : 键盘高度发生变化，keyboardheightchange事件可能会多次触发，开发者对于相同的height值应该忽略掉
1. `bug` : 微信版本 `6.3.30`, focus 属性设置无效
1. `bug` : 微信版本 `6.3.30`, placeholder 在聚焦时出现重影问题

## 示例代码

[在开发者工具中预览效果](https://developers.weixin.qq.com/s/Is4OlSm27MJe)