# Item 列表项目

[toc]

属于基础布局组件，帮助用户快速搭建列表布局。`Item` 可单独使用、亦可与组件 `List` 联合使用。 `List` 可以为 `Item` 提供上下外边框等属性，具体可参考 [List 组件](/mp/packages/list)。

## 组件引入

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

```json

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

```

## 用法

### 基础用法

`Item` 可以单独使用，也可以与 `List` 搭配使用。具体使用方式可参考 [List 组件](/mp/packages/list)。

```html
<tea-list>
  <tea-item title="标题文字"></tea-item>
  <tea-item title="标题文字" value="内容文字"></tea-item>
  <tea-item title="双行列表标题文字" description="说明文字"></tea-item>
  <tea-item title="双行列表标题文字双行列表标题文字双行列表标题文字" description="说明文字" value="内容文字"></tea-item>
</tea-list>
```

### 右侧内容文字对齐方式

`Item` 预设右侧内容文字靠右对齐，此属性提供给需要调整对齐方式为靠左的用户使用。<br>
设置 `valueAlignLeft` 属性后，右侧内容文字改为靠左对齐，此属性必须与 `titleWidth` 一同使用才生效。

```html
<tea-item title="标题文字" titleWidth="5em" value="内容文字" valueAlignLeft></tea-item>
```

### 列表项大小

通过 `itemHeight` 属性可以控制列表项的大小，可设置 `sm`、`md`、`lg`、`auto`。默认值为 `sm`。<br>

`sm`、`md` 预设为单行列表使用，`lg` 预设为双行列表使用，文案超出皆以缩略进行处理，若需要文本换行形式建议使用 `auto`。

```html
<!-- 小列表项(属性默认值、单行列表预设高度) -->
<tea-item title="标题文字" value="内容文字"></tea-item>

<!-- 中列表项(单行列表) -->
<tea-item title="标题文字" value="内容文字" itemHeight="md"></tea-item>

<!-- 大列表项(双行列表预设高度) -->
<tea-item title="标题文字" value="内容文字" description="说明文字" itemHeight="lg"></tea-item>

<!-- 不定高列表项 -->
<tea-item title="标题文字" value="内容文字" description="说明文字说明文字说明文字说明文字说明文字说明文字说明文字说明文字说明文字说明文字说明文字说明文字说明文字说明文字" itemHeight="auto"></tea-item>
```

### 开启点击反馈

设置 `clickable` 属性来开启点击反馈。

```html
<tea-item title="标题文字" value="内容文字" clickable></tea-item>
```

### 页面跳转

设置 `route` 与 `url` 属性来指定进行页面跳转，并可通过 `linkType` 属性控制跳转方式。

```html
<tea-item title="标题文字" value="内容文字" url="/pages/index/index" linkType="navigateTo" route></tea-item>
```

### 展示箭头

设置 `detail` 属性后，会在列表项右侧显示箭头。

```html
<tea-item title="标题文字" value="内容文字" detail></tea-item>
```

### 展示图标

设置 `icon`、`iconColor`、`iconSize` 属性来展示左侧图标，不能与 `thumb` 同时存在。

```html
<tea-item icon="info-fill" iconColor="#006EFF" title="标题文字" detail></tea-item>
```

### 展示缩略图

设置 `thumb`、`thumbPosition` 属性来展示缩略图，不能与 `icon` 同时存在。

```html
<tea-item title="标题文字" value="内容文字" thumb="https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/image.svg"></tea-item>
<tea-item title="标题文字" value="内容文字" thumb="https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/image.svg" thumbPosition="right"></tea-item>
```

## Props

| 参数             | 描述                                         | 类型              | 默认值          | 可选值                                                     |
| -------------- | ------------------------------------------ | --------------- | ------------ | ------------------------------------------------------- |
| icon           | 左侧图标名称，可选值请参见 [Icon 组件](/mp/packages/icon) | `String`        | -            | -                                                       |
| iconColor      | 图标颜色                                       | `String`        | -            | -                                                       |
| iconSize       | 图标大小，最大为 `64px`。默认单位为 `px`，支持自带单位。         | `Number,String` | `24px`       | -                                                       |
| title          | 左侧标题                                       | `String`        | -            | -                                                       |
| titleWidth     | 设置标题宽度                                     | `Number,String` | -            | -                                                       |
| description    | 标题下方的描述信息                                  | `String`        | -            | -                                                       |
| value          | 右侧内容                                       | `String`        | -            | -                                                       |
| required       | 是否显示必填星号                                   | `Boolean`       | `false`      | -                                                       |
| clickable      | 是否开启点击反馈                                   | `Boolean`       | `false`      | -                                                       |
| route          | 是否尝试以 url 跳转                               | `Boolean`       | `false`      | -                                                       |
| linkType       | 链接跳转类型                                     | `String`        | `navigateTo` | `["navigateTo", "redirectTo", "switchTab", "reLaunch"]` |
| url            | 点击后跳转的链接地址                                 | `String`        | -            | -                                                       |
| detail         | 是否展示右侧箭头                                   | `Boolean`       | `false`      | -                                                       |
| thumb          | 列表项缩略图                                     | `String`        | -            | -                                                       |
| thumbPosition  | 列表项缩略图位置                                   | `String`        | `left`       | `["left", "right"]`                                     |
| itemHeight     | 单行列表高度                                     | `String`        | `sm`         | `["sm", "md", "lg", "auto"]`                            |
| valueAlignLeft | 右侧内容文字是否靠左对齐，需与 `titleWidth` 搭配使用          | `Boolean`       | `false`      | -                                                       |
| bordered       | 是否显示下边框                                    | `Boolean`       | `false`      | -                                                       |

## 事件

| 事件名        | 描述      |
| ---------- | ------- |
| bind:click | 点击元素时触发 |

## Slots

| 名称         | 描述                                                   |
| ---------- | ---------------------------------------------------- |
| -          | 自定义 `value` 显示内容，如果设置了 `value` 属性则不生效                |
| icon       | 自定义 `icon` 显示内容，如果设置了 `icon` 与 `thumb` 属性则不生效        |
| title      | 自定义 `title` 显示内容，如果设置了 `title`与 `description` 属性则不生效 |
| right-icon | 自定义右侧图标，如果设置了 `detail` 属性则不生效                        |

## 外部样式类

| 类名                      | 描述       |
| ----------------------- | -------- |
| `ext-class`             | 组件根节点样式类 |
| `ext-class-title`       | 标题样式类    |
| `ext-class-description` | 描述信息样式类  |
| `ext-class-value`       | 右侧内容样式类  |

## CSS变量属性表

| 变量名                          | 默认值                               | 描述  |
| ---------------------------- | --------------------------------- | --- |
| item-sm-height               | @item-height-sm                   | -   |
| item-md-height               | @item-height-md                   | -   |
| item-lg-height               | @item-height-lg                   | -   |
| item-line-height             | @line-height-zh                   | -   |
| item-background-color        | @form-background-base-color       | -   |
| item-background-hover-color  | @form-background-base-hover-color | -   |
| item-divider-color           | @border-divider-color             | -   |
| item-required-color          | @color-danger                     | -   |
| item-padding-vertical        | @padding-sm                       | -   |
| item-padding-horizontal      | @padding-md                       | -   |
| item-title-text-size         | @font-size-h4                     | -   |
| item-title-text-color        | @text-base-color                  | -   |
| item-description-text-size   | @font-size-xs                     | -   |
| item-description-text-color  | @text-light-color                 | -   |
| item-description-margin-top  | @margin-base                      | -   |
| item-value-text-size         | @font-size-md                     | -   |
| item-value-text-color        | @text-light-color                 | -   |
| item-thumb-size              | 72px                              | -   |
| item-left-icon-margin-right  | @margin-sm                        | -   |
| item-left-thumb-margin-right | @margin-md                        | -   |
| item-right-icon-margin-left  | @margin-sm                        | -   |
| item-right-thumb-margin-left | @margin-md                        | -   |
| item-width-thumb-left        | 104px                             | -   |