# Field 输入框

[toc]

表单中的输入框组件，包含 `input` 与 `textarea` 组件。

## 组件引入

在`app.json`或在`index.json`中引入：

```json

{
  "usingComponents": {
    "tea-field": "../dist/field/index"
  }
}

```

## 用法

### 输入框类型

通过 `type` 属性来设置按钮类型，支持 `text`、`number`、`digit`、`idcard`、`password`、`textarea` 六种类型，默认为 `text`。

```html
<tea-field type="text" placeholder="单行文本"></tea-field>
<tea-field type="number" placeholder="请输入数字"></tea-field>
<tea-field type="digit" placeholder="请输入小数"></tea-field>
<tea-field type="idcard" placeholder="请输入身分证号码"></tea-field>
<tea-field type="password" placeholder="请输入密码"></tea-field>
<tea-field type="textarea" placeholder="多行文本"></tea-field>
```

### 禁用状态

通过 `disabled` 属性来展示禁用状态，此时输入框无法进行输入。

```html
<tea-field type="text" placeholder="禁用状态" disabled></tea-field>
```

### 错误状态

通过 `invalid` 属性来展示当前输入区域内容为不合法值，此时输入框标红。

```html
<tea-field type="text" placeholder="错误状态" invalid></tea-field>
```

### 输入框边框

通过 `bordered` 属性来展示输入框边框。

```html
<tea-field type="text" placeholder="请输入文本内容" bordered></tea-field>
```

### 高度自适应

通过 `autoHeight` 属性设置输入框高度自适应，此属性仅在 `type="textarea"` 生效。

```html
<tea-field type="textarea" placeholder="请输入文本内容" autoHeight></tea-field>
```

### 文字计数

通过 `hasCount` 属性来开启文字计数，此属性仅在 `type="textarea"` 生效。

```html
<tea-field type="textarea" placeholder="请输入文本内容" hasCount></tea-field>
```

## Props

| 参数                    | 描述                                                               | 类型        | 默认值                      | 可选值                                                             |
| --------------------- | ---------------------------------------------------------------- | --------- | ------------------------ | --------------------------------------------------------------- |
| name                  | 输入框的唯一标识                                                         | `String`  | -                        | -                                                               |
| value                 | 输入框当前的内容                                                         | `String`  | -                        | -                                                               |
| type                  | 输入框类型                                                            | `String`  | `text`                   | `["text", "number", "idcard", "digit", "password", "textarea"]` |
| password              | 是否为密码类型                                                          | `Boolean` | `false`                  | -                                                               |
| placeholder           | 输入框为空时占位符                                                        | `String`  | -                        | -                                                               |
| placeholderStyle      | 指定 placeholder 的样式                                               | `String`  | -                        | -                                                               |
| placeholderClass      | 指定 placeholder 的样式类                                              | `String`  | `tea-field__placeholder` | -                                                               |
| disabled              | 是否禁用                                                             | `Boolean` | `false`                  | -                                                               |
| readonly              | 是否只读                                                             | `Boolean` | `false`                  | -                                                               |
| maxLength             | 最大输入长度，设置为 -1 的时候不限制最大长度                                         | `Number`  | `-1`                     | -                                                               |
| cursor                | 指定focus时的光标位置                                                    | `Number`  | `-1`                     | -                                                               |
| cursorSpacing         | 指定光标与键盘的距离                                                       | `Number`  | `0`                      | -                                                               |
| focus                 | 获取焦点                                                             | `Boolean` | `false`                  | -                                                               |
| autoFocus             | 自动聚焦，拉起键盘 (即将废弃，请直接使用 focus)                                     | `Boolean` | `false`                  | -                                                               |
| confirmType           | 设置键盘右下角按钮的文字，仅在 type='text' 时生效                                  | `String`  | `done`                   | `["send", "search", "next", "go", "done"]`                      |
| confirmHold           | 点击键盘右下角按钮时是否保持键盘不收起，在 type='textarea' 时无效                        | `Boolean` | `false`                  | -                                                               |
| autoHeight            | 是否自动增高，设置 auto-height 时，style.height 不生效，仅在 type='textarea' 时生效  | `Boolean` | `false`                  | -                                                               |
| fixed                 | 如果 type='textarea' 且在一个 position:fixed 的区域，需要显示指定属性 fixed 为 true | `Boolean` | `false`                  | -                                                               |
| showConfirmBar        | 是否显示键盘上方带有”完成“按钮那一栏，仅在 type='textarea' 时生效                       | `Boolean` | `true`                   | -                                                               |
| disableDefaultPadding | 是否去掉 iOS 下的默认内边距，仅在 type='textarea' 时生效                          | `Boolean` | `true`                   | -                                                               |
| hasCount              | 是否显示文字计数功能，仅在 type='textarea' 时生效                                | `Boolean` | `false`                  | -                                                               |
| bordered              | 是否显示输入框边框                                                        | `Boolean` | `false`                  | -                                                               |
| borderPosition        | 外边框显示位置，需与 bordered 搭配使用                                         | `String`  | `surrounded`             | `["horizontal", "surrounded"]`                                  |
| invalid               | 输入区域内容是否为不合法值                                                    | `Boolean` | `false`                  | -                                                               |
| selectionStart        | 光标起始位置，自动聚集时有效，需与 selectionEnd 搭配使用                              | `Number`  | `-1`                     | -                                                               |
| selectionEnd          | 光标结束位置，自动聚集时有效，需与 selectionStart 搭配使用                            | `Number`  | `-1`                     | -                                                               |
| adjustPosition        | 键盘弹起时，是否自动上推页面                                                   | `Boolean` | `true`                   | -                                                               |
| holdKeyboard          | focus时，点击页面的时候不收起键盘                                              | `Boolean` | `false`                  | -                                                               |

## 事件

| 事件名                       | 描述               | 回调参数                                           |
| ------------------------- | ---------------- | ---------------------------------------------- |
| bind:input                | 输入内容时触发          | e.detail.value: 当前输入值                          |
| bind:focus                | 输入框聚焦时触发         | e.detail.value: 当前输入值<br>e.detail.height: 键盘高度 |
| bind:blur                 | 输入框失去焦点时触发       | e.detail = { value, cursor }                   |
| bind:confirm              | 点击完成按钮时触发        | e.detail.value: 当前输入值                          |
| bind:linechange           | 输入框行数变化时调用       | e.detail = { height, heightRpx, lineCount }    |
| bind:keyboardheightchange | 键盘高度发生变化的时候触发此事件 | e.detail = { duration, height }                |

## 外部样式类

| 类名                   | 描述           |
| -------------------- | ------------ |
| `ext-class`          | 组件根节点样式类     |
| `ext-class-input`    | input 外部容器样式类    |
| `ext-class-input-item`    | input 样式类    |
| `ext-class-textarea` | textarea 外部容器样式类 |
| `ext-class-textarea-item`    | textarea 样式类    |

## CSS变量属性表

| 变量名                             | 默认值                             | 描述  |
| ------------------------------- | ------------------------------- | --- |
| field-text-size                 | @font-size-md                   | -   |
| field-counter-text-size         | @font-size-sm                   | -   |
| field-text-color                | @text-base-color                | -   |
| field-disabled-text-color       | @form-text-disabled-color       | -   |
| field-invalid-text-color        | @text-danger-color              | -   |
| field-counter-number-text-color | @text-light-color               | -   |
| field-current-number-text-color | @text-base-color                | -   |
| field-placeholder-text-color    | @text-placeholder-color         | -   |
| field-input-height              | @item-height-sm                 | -   |
| field-textarea-min-height       | 96px                            | -   |
| field-textarea-max-height       | 180px                           | -   |
| field-background-color          | @background-base-color          | -   |
| field-disabled-background-color | @background-base-disabled-color | -   |
| field-focus-border-color        | @border-primary-color           | -   |
| field-disabled-border-color     | @border-disabled-color          | -   |
| field-invalid-border-color      | @border-danger-color            | -   |
| field-input-padding             | @padding-sm                     | -   |
| field-textarea-padding          | @padding-sm                     | -   |
| field-border-radius             | @border-radius-none             | -   |