category:
  en: Form
  'zh-CN': 表单
icon: ''
extra:
  zh-CN: |
    ```html
      <group>
        <x-input title="title" v-model="value"></x-input>
      </group>
    ```

    ::: tip
    `x-input`只能在`Group`中使用
    :::

    如果你想实现在输入框右边按钮切换密码明文，请使用`slot=right`实现`type`切换。
    <br>
    ::: warning
    `mask` 在 `2.6.1` 支持，但注意的是使用 mask 后值也是经过 mask 处理后的值，进行判断或者提交到接口前应该注意。
    <br>
    比如格式化手机号码，`mask` 值为 `999 9999 9999`，得到的值将是 13 位的 `145 3456 3456`，提交或者判断都应该先清除中间空格。
    :::
tags:
  en:
    - form
    - input
  zh-CN:
    - 输入框
    - 表单
    - 单行输入框
props:
  value:
    en: input value, use `v-model` for binding
    zh-CN: 表单值，使用`v-model`绑定
  type:
    type: String
    default: text
    en: input type, one of `text`,`number`,`email`,`password`,`tel`
    zh-CN: '即input的`type`属性，目前支持 `text`,`number`,`email`,`password`,`tel`'
  is-type:
    type: String,Function
    en: "custom validating function, should return `{valid:true}` or `{valid:false, msg: error msg}`"
    zh-CN: '内置验证器，支持`email`,`china-name`,`china-mobile`, 同样也支持直接传函数, 需要同步返回一个对象`{valid:true}`或者`{valid:false, msg:错误信息}`'
  required:
    type: Boolean
    default: false
    en: if is required
    zh-CN: 是否必填，如果不禁用验证，当没有填写时会在右侧显示错误icon
  title:
    en: label text
    zh-CN: label文字
  placeholder:
    en: placeholder
    zh-CN: placeholder 提示
  show-clear:
    type: Boolean
    default: true
    en: if show clear icon
    zh-CN: 是否显示清除icon
  min:
    type: Number
    en: minlength for input
    zh-CN: 最小输入字符限制
  max:
    type: Number
    en: maxlength for input
    zh-CN: '最大输入字符限制，等同于`maxlength`，达到限制到不能再输入'
  disabled:
    type: Boolean
    default: false
    en: if input is disabled
    zh-CN: 是否禁用填写
  readonly:
    type: Boolean
    default: false
    en: if input is readonly
    zh-CN: 同input的标准属性readonly
  debounce:
    type: Number
    default: ''
    en: debounce time
    zh-CN: '`debounce`用以限制`on-change`事件触发。如果你需要根据用户输入做`ajax`请求，建议开启以节省无效请求和服务器资源，单位为毫秒'
  placeholder-align:
    type: String
    default: left
    version: v2.1.1-rc.8
    en: placeholder align value
    zh-CN: placeholder 文字对齐方式
  text-align:
    type: String
    default: left
    en: text-align setting for value
    zh-CN: 值对齐方式
  label-width:
    type: String
    version: v2.2.1-rc.4
    en: set label width which will not be overwritten by $parent.labelWidth
    zh-CN: label 宽度，权重比 group 的 labelWidth 高。不设定时将进行自动宽度计算，但超过15个字符时不会进行宽度设定。
  mask:
    version: v2.6.1
    en: (beta) value mask, 9 for DIGIT, A for ALPHA, S for ALPHA AND DIGIT
    zh-CN: (beta) 值格式化，依赖于 vanilla-masker，其中 9 表示数字，A 表示大写字母，S 表示数字或者字母
  should-toast-error:
    type: Boolean
    version: v2.6.3
    default: true
    en: whether toast error when clicking on error icon
    zh-CN: 是否在点击错误图标时用 toast 的形式显示错误
slots:
  label:
    zh-CN: '用于自定义`label`(即 title)部分内容，比如使用`icon`'
  restricted-label:
    zh-CN: '用于自定义`label`部分，和`slot=label`不同的是，该slot宽度受到父组件`group`的限制'
  right:
    zh-CN: '用以在输入框右边显示内容，比如单位，切换密码显示方式等'
  right-full-height:
    version: v2.8.1
    zh-CN: '用于放置和 cell 高度的验证码图片'
events:
  on-blur:
    params: '`(value, $event)`'
    zh-CN: 'input的`blur`事件'
  on-focus:
    params: '`(value, $event)`'
    zh-CN: 'input的`focus`事件'
  on-enter:
    params: '`(value, $event)`'
    zh-CN: 'input输入完成后点击`enter(确认)`事件'
  on-change:
    params: '`(value)`'
    zh-CN: '输入值变化时触发。如果你使用了`debounce`，那么触发将不会是实时的。'
  on-click-error-icon:
    version: v2.6.3
    params: '`(error)`'
    en: fires when clicking error icon
    zh-CN: '点击错误图标时触发，你可以关闭 `should-toast-error` 然后用这个事件来自定义显示错误的提示内容'
  on-click-clear-icon:
    version: v2.9.0
    en: fires when clicking clear icon
    zh-CN: 点击清除按钮时触发
methods:
  focus:
    en: get input focus
    zh-CN: 手动获得焦点
  blur:
    en: remove focus from input
    zh-CN: 手动设置 input 失去焦点
  reset:
    version: v2.1.1-rc.10
    params: "`(value = '')`"
    en: reset input value and clear errors
    zh-CN: 重置输入框值，清除错误信息
changes:
  v2.9.2:
    en:
      - '[fix] fix corsor misplce when set mask #2810'
    zh-CN:
      - '[fix] 修复设置 mask 时，光标错位的问题 #2810'
  v2.9.0:
    en:
      - '[fix] fix wrong valid when value is empty string #2415'
      - '[fix] fix disabled style in iOS #2458'
      - '[change] show clear icon only when input gets focus #2567'
      - '[feature] add event:on-click-clear-icon #2603'
      - '[enhance] scroll input element into view when getting focus #2604'
    zh-CN:
      - '[fix] 修复在空值时 valid 为 true 的问题 #2415'
      - '[fix] 修复 disabled 样式在 iOS 下过浅的问题 #2458'
      - '[change] 仅在获得焦点时显示清除按钮 #2567'
      - '[feature] 支持事件 on-click-clear-icon #2603'
      - '[enhance] 获得焦点时滚动到可视区域(Android) #2604'
  v2.8.1:
    en:
      - '[feature] add slot:right-full-height for containing captcha #2475'
    zh-CN:
      - '[feature] 添加 slot:right-full-height 用于方便显示验证码图片 #2475'
  v2.8.0:
    en:
      - '[fix] fix not show clear button when initial value is zero #2482'
    zh-CN:
      - '[fix] 修复初始值为0时不显示清除按钮问题 #2482'
  v2.7.9:
    en:
      - '[enhance] support china union 166 prefix phone number'
    zh-CN:
      - '[enhance] 支持中国联通手机号166号段'
  v2.7.7:
    en:
      - '[fix] Fix error message not change bugs #2348'
    zh-CN:
      - '[fix] 修复报错信息不会改变的问题 #2348'
  v2.7.6:
    en:
      - '[feature] add disabled class #2279'
    zh-CN:
      - '[feature] 增加disabled样式 #2279'
  v2.7.4:
    en:
      - '[fix] fix ssr DOM not matched issue #2201'
    zh-CN:
      - '[fix] 修复服务端渲染 DOM 不一致问题 #2201'
  v2.7.1:
    en:
      - '[fix] fix valid is false when value is zero #2134'
      - '[fix] fix event:on-blur not fires #2146'
    zh-CN:
      - '[fix] 修复数字为 0 时 valid 为 false 的问题 #2134'
      - '[fix] 修复 on-blur 事件没有正确触发的问题 #2146'
  v2.6.5:
    en:
      - '[enhance] fix validating logic for is-type:china-mobile with mask #2040'
    zh-CN:
      - '[enhance] 兼容同时使用 is-type:china-mobile 和 mask 的情况 @2040'
  v2.6.3:
    en:
      - '[enhance] toast error when clicking error icon #2009'
    zh-CN:
      - '[enhance] 点击错误图标时显示错误内容 #2009'
  v2.6.1:
    en:
      - '[enhance] set label for attribute #1983'
      - '[feature] support prop:mask'
    zh-CN:
      - '[enhance] 为 label 设置 for 属性 #1983'
      - '[feature] 支持属性 mask 对输入值进行格式化'
  v2.5.6:
    en:
      - '[fix] Fix is-type validating logic #1776'
    zh-CN:
      - '[fix] 修复 is-type 验证逻辑 #1776'
  v2.5.5:
    en:
      - '[feature] Add $event param for on-focus on-blur event #1770'
      - '[fix] Fix empty value checking logic #1759'
    zh-CN:
      - '[feature] 为 on-focus on-blur 事件添加 $event 参数 #1770'
      - '[fix] 修复值为空的错误判断逻辑 #1759'
  v2.3.1:
    en:
      - '[feature] Add blur function #1422'
    zh-CN:
      - '[feature] 添加 blur 方法 #1422'
  v2.2.1-rc.4:
    en:
      - '[feature] Support labelWidth #1186'
    zh-CN:
      - '[feature] 支持设置 label 宽度 #1186'
  v2.1.1-rc.10:
    en:
      - '[feature] Support reset method #947 @erguotou520'
    zh-CN:
      - '[feature] 支持 reset 函数 #947 @erguotou520'
  v2.1.1-rc.8:
    en:
      - '[feature] Support prop:placeholder-align'
    zh-CN:
      - '[feature] 支持设置 placeholder 对齐方式'
  v2.1.0-rc.51:
    zh-CN:
      - '[fix] 修复`slots`判断问题 #936 @zscumt123'
  v2.1.0-rc.49:
    zh-CN:
      - '[feature] 支持`slot=restricted-label` #918 @zqyadam'
  v2.1.0-rc.48:
    zh-CN:
      - '[feature] 支持`debounce` #715 @YYmmlin'
  v2.1.0-rc.46:
    zh-CN:
      - '[feature] 添加`slot=label`自定义label部分内容 #895 @erguotou520'
  v2.0.0:
    zh-CN:
      - '[feature] 添加 `novalidate` 及 `iconType` 可以禁用组件验证，手动显示 error 或者 success 样式'
      - '[feature] `is-type` 支持传入函数'
      - '[change] 受限于vue2不能动态设置type，目前`type`支持 text password number email'
  v2.0.1:
    zh-CN:
      - '[fix] 修复type未定义的问题'