# Form Item 表单项目

[toc]

`Form Item` 组件提供常见的几种表单布局，帮助用户快速实现表单效果。

## 组件引入

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

```json

{
  "usingComponents": {
    "tea-form-item": "../dist/form-item/index"
  }
}

```

## 用法

### 基础用法

```html
<tea-list title="基础用法" bordered>
  <tea-form-item label="单行六个文字" placeholder="请输入文字" bordered bind:input="handleInput"></tea-form-item>
  <tea-form-item label="标题超过六个文字折行展示" placeholder="请输入文字" bordered></tea-form-item>
  <tea-form-item placeholder="无标题"></tea-form-item>
</tea-list>
```

```javascript
Page({
  data: {
    value: ""
  },

  handleInput(e) {
    // e.detail 为当前输入的值
    console.log(e.detail);
  }
})
```

### 输入内容类型

通过 `type` 属性来设置输入内容类型，支持 `text`、`number`、`idcard`、`digit`、`textarea`、`password`、`code`、`bankcard`、`select` 九种类型，默认为 `text`。

```html
<tea-list title="输入类型" bordered>
  <tea-form-item label="单行文本" placeholder="请输入单行文本" bordered></tea-form-item>
  <tea-form-item type="select" label="选择" placeholder="请选择内容" detail clickable bordered></tea-form-item>
  <tea-form-item type="number" label="数字" placeholder="请输入数字" bordered></tea-form-item>
  <tea-form-item type="digit" label="小数" placeholder="请输入小数" bordered></tea-form-item>
  <tea-form-item type="idcard" label="身份证" placeholder="请输入身份证号码" bordered></tea-form-item>
  <tea-form-item type="bankcard" label="银行卡" placeholder="请输入银行卡号码" bordered></tea-form-item>
  <tea-form-item type="password" label="密码" placeholder="密码不能少于10位数" bordered></tea-form-item>
  <tea-form-item type="code" label="验证码" placeholder="请输入验证码" clock="30" getCodeText="获取验证码" bordered></tea-form-item>
  <tea-form-item type="textarea" label="多行文本" placeholder="请输入多行文本"></tea-form-item>
</tea-list>
```

#### 输入内容类型 + Popup组件 + Picker组件

当 `type="select"` 时，内容区提供一个可读状态的输入框组件，此时不允许用户做任何输入。可以依照具体场景自定义或搭配其它组件使用。以下为搭配 `Popup & Picker` 使用范例：

```html
<tea-list title="必填栏位" bordered>
  <tea-form-item 
    type="select" 
    label="选择" 
    placeholder="请选择内容" 
    value="{{ value }}" 
    detail 
    clickable 
    bordered 
    bind:select="handleSelect" 
  />
</tea-list>

<tea-popup
  show="{{ show }}"
  position="bottom" 
  backdropClosable="{{ true }}" 
>
  <tea-picker 
    value="{{ value }}" 
    range="{{ array }}" 
    bind:confirm="handleConfirm" 
    bind:cancel="handleCancel" 
  />
</tea-popup>
```

```javascript
Page({
  data: {
    show: false,
    value: "", 
    array: ['选项一', '选项二', '选项三']
  }, 
  
  handleSelect(e) {
    this.setData({
      show: true
    })
  }, 
  
  handleConfirm(e) {
    const { value } = e.detail
    
    this.setData({
      show: false, 
      value: value
    })
  }, 
  
  handleCancel(e) {
    this.setData({
      show: false
    })
  }
})
```

### 展示必填栏位星号

通过 `required` 属性来展示必填栏位星号。

```html
<tea-list title="必填栏位" bordered>
  <tea-form-item label="帐号" placeholder="请输入帐号" bordered required></tea-form-item>
  <tea-form-item label="密码" placeholder="请输入密码" required></tea-form-item>
</tea-list>
```

### 内容对齐方式

通过 `textAlign` 属性设置输入内容文字对齐方式，支持 `left`、`center`、`right` 三种方式，默认为 `left`。

```html
<tea-list title="内容对齐方式" bordered>
  <tea-form-item label="标题文字" placeholder="请输入文本内容" textAlign="left" bordered></tea-form-item>
  <tea-form-item label="标题文字" placeholder="请输入文本内容" textAlign="center" bordered></tea-form-item>
  <tea-form-item label="标题文字" placeholder="请输入文本内容" textAlign="right"></tea-form-item>
</tea-list>
```

### 自定义右侧内容

通过 `useSlot` 属性来设置开启自定义右侧内容，此时输入框相关属性（如：`placeholder`、`value`等）不生效。

```html
<tea-list title="自定义右侧内容" bordered>
  <tea-form-item useSlot="{{ true }}" label="身份证类型">
    <tea-checkbox-group class="demo-checkbox-group" value="{{ ['idcard'] }}" single>
      <tea-checkbox class="demo-checkbox" name="idcard">身份证</tea-checkbox>
      <tea-checkbox class="demo-checkbox" name="passport">护照</tea-checkbox>
    </tea-checkbox-group>
  </tea-form-item>
</tea-list>
```

### 辅助文本

通过 `helperText` 属性增加当前栏位对应的辅助文本。不可与 `invalidText` 同时使用。

```html
<tea-list title="辅助文本" bordered>
  <tea-form-item label="帐号" placeholder="请输入帐号" helperText="帐号不能多于10个字符，可中英文数字搭配" required bordered></tea-form-item>
  <tea-form-item label="密码" placeholder="请输入密码" helperText="密码不能少于10位数" password required></tea-form-item>
</tea-list>
```

### 错误提示

通过 `invalid` 或 `invalidText` 属性增加当前栏位对应的错误提示。不可与 `helperText` 同时使用。

```html
<tea-list title="错误提示" bordered>
  <tea-form-item label="联系人" placeholder="请输入中文名" required invalid bordered></tea-form-item>
  <tea-form-item type="number" label="手机号码" placeholder="请输入手机号码" required value="123456" invalidText="手机号格式错误"></tea-form-item>
</tea-list>
```

### 垂直布局

通过 `vertical` 属性来展示垂直布局表单。

```html
<tea-list title="垂直布局" bordered>
  <tea-form-item label="帐号" placeholder="请输入帐号" value="username" helperText="帐号不能多于10个字符，可中英文数字搭配" required vertical bordered></tea-form-item>
  <tea-form-item type="password" label="密码" placeholder="请输入密码" value="1234567890" invalidText="密码不能少于10位数" required vertical></tea-form-item>
</tea-list>
```

## Props

| 参数               | 描述                                                        | 类型              | 默认值                      | 可选值                                                                                           |
| ---------------- | --------------------------------------------------------- | --------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
| vertical         | 是否为垂直表单布局                                                 | `Boolean`       | `false`                  | -                                                                                             |
| icon             | 左侧图标名称，可选值请参见 Icon 组件                                     | `String`        | \`\`                     | -                                                                                             |
| iconColor        | 图标颜色                                                      | `String`        | \`\`                     | -                                                                                             |
| iconSize         | 图标大小，最大为 64px。默认单位为 px，支持自带单位。                            | `Number,String` | `24px`                   | -                                                                                             |
| label            | 左侧标题，为空时不展示                                               | `String`        | \`\`                     | -                                                                                             |
| labelWidth       | 设置左侧标题宽度                                                  | `Number,String` | `6em`                    | -                                                                                             |
| required         | 是否显示表单必填星号                                                | `Boolean`       | `false`                  | -                                                                                             |
| clickable        | 是否开启点击反馈                                                  | `Boolean`       | `false`                  | -                                                                                             |
| detail           | 是否展示右侧箭头                                                  | `Boolean`       | `false`                  | -                                                                                             |
| textEllipsis     | 是否省略处理右侧过长内容文字，仅在type='select'生效                          | `Boolean`       | `true`                   | -                                                                                             |
| bordered         | 是否显示下边框                                                   | `Boolean`       | `false`                  | -                                                                                             |
| value            | 输入框的内容                                                    | `String`        | -                        | -                                                                                             |
| type             | 支持input原生类型，并扩充验证码与银行卡等类型供选择                              | `String`        | `text`                   | `['text', 'number', 'idcard', 'digit', 'textarea', 'password', 'code', 'bankcard', 'select']` |
| 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`                  | -                                                                                             |
| selectionStart   | 光标起始位置，自动聚集时有效，需与 selectionEnd 一同使用才生效                    | `Number`        | `-1`                     | -                                                                                             |
| selectionEnd     | 光标结束位置，自动聚集时有效，需与 selectionStart 一同使用才生效                  | `Number`        | `-1`                     | -                                                                                             |
| adjustPosition   | 键盘弹起时，是否自动上推页面                                            | `Boolean`       | `true`                   | -                                                                                             |
| holdKeyboard     | focus时，点击页面的时候不收起键盘                                       | `Boolean`       | `false`                  | -                                                                                             |
| autoHeight       | 是否自动增高，设置 auto-height 时，style.height 不生效，只对 textarea 有效   | `Boolean`       | `false`                  | -                                                                                             |
| fixed            | 如果 textarea 是在一个 position:fixed 的区域，需要显示指定属性 fixed 为 true | `Boolean`       | `false`                  | -                                                                                             |
| showConfirmBar   | 是否显示键盘上方带有”完成“按钮那一栏，只对 textarea 有效                        | `Boolean`       | `true`                   | -                                                                                             |
| textAlign        | 右侧内容文字对齐方式                                                | `String`        | `left`                   | `['left', 'center', 'right']`                                                                 |
| hasCount         | 是否显示文字计数功能                                                | `Boolean`       | `false`                  | -                                                                                             |
| invalid          | 输入区域内容是否为不合法值                                             | `Boolean`       | `false`                  | -                                                                                             |
| invalidText      | 输入区域校验错误信息，为空时不展示。不可与 helperText 同时使用                     | `String`        | \`\`                     | -                                                                                             |
| helperText       | 输入区域辅助文案，为空时不展示。不可与 invalidText 同时使用                      | `String`        | \`\`                     | -                                                                                             |
| clock            | 获取验证码按钮禁用秒数。仅在 type='code' 时生效                            | `Number`        | `-1`                     | -                                                                                             |
| getCodeText      | 获取验证码按钮文案。仅在 type='code' 时生效                              | `String`        | `获取验证码`                  | -                                                                                             |
| useSlot          | 是否自定义右侧内容区域                                               | `Boolean`       | `false`                  | -                                                                                             |

## 事件

| 事件名                       | 描述                                | 回调参数                                           |
| ------------------------- | --------------------------------- | ---------------------------------------------- |
| bind:select               | 点击单列时触发，仅在`type='select'`时生效      | -                                              |
| bind:getCode              | 点击获取验证码按钮时触发，仅在`type='code'`时生效   | -                                              |
| bind:input                | 输入内容时触发                           | value: 当前输入值                                   |
| bind:focus                | 输入框聚焦时触发                          | e.detail.value: 当前输入值<br>e.detail.height: 键盘高度 |
| bind:blur                 | 输入框失去焦点时触发                        | e.detail = { value, cursor }                   |
| bind:confirm              | 点击完成按钮时触发                         | value: 当前输入值                                   |
| bind:linechange           | 输入框行数变化时触发，仅在`type='textarea'`时生效 | e.detail = { height, heightRpx, lineCount }    |
| bind:keyboardheightchange | 键盘高度发生变化时触发                       | e.detail = { duration, height }                |

## Slots

| 名称    | 描述                         |
| ----- | -------------------------- |
| -     | 自定义右侧内容                    |
| icon  | 自定义左侧图标                    |
| label | 自定义标题                      |
| extra | 自定义右侧尾部区域内容，`useSlot` 时不生效 |

## 外部样式类

| 类名          | 描述       |
| ----------- | -------- |
| `ext-class` | 组件根节点样式类 |

## CSS变量属性表

| 变量名                                             | 默认值                               | 描述  |
| ----------------------------------------------- | --------------------------------- | --- |
| form-item-background-color                      | @form-background-base-color       | -   |
| form-item-hover-background-color                | @form-background-base-hover-color | -   |
| form-item-padding                               | @padding-sm @padding-md           | -   |
| form-item-label-text-size                       | @font-size-h4                     | -   |
| form-item-label-text-color                      | @text-base-color                  | -   |
| form-item-value-text-size                       | @font-size-md                     | -   |
| form-item-value-text-color                      | @text-base-color                  | -   |
| form-item-value-disabled-text-color             | @form-text-disabled-color         | -   |
| form-item-assistive-text-size                   | @font-size-xs                     | -   |
| form-item-assistive-text-margin-top             | @margin-base                      | -   |
| form-item-helper-text-color                     | @text-light-color                 | -   |
| form-item-invalid-text-color                    | @text-danger-color                | -   |
| form-item-verification-code-text-size           | @font-size-md                     | -   |
| form-item-verification-code-text-color          | @text-primary-color               | -   |
| form-item-verification-code-disabled-text-color | @text-primary-disabled-color      | -   |
| form-item-vertical-label-text-size              | @font-size-h5                     | -   |
| form-item-vertical-label-text-color             | @text-light-color                 | -   |
| form-item-vertical-controls-margin-top          | @margin-base                      | -   |