# Grid 宫格

[toc]

`Grid` 组件提供常见的几种基础宫格布局，帮助用户快速实现宫格效果。

## 组件引入

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

```json

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

```

## 用法

### 基础用法

需要传入一个 `gridItems` 的数组，数组的每一项是一个对象，对象属性详情见文档下方表格。

```html
  <tea-grid gridItems="{{ gridItems }}"></tea-grid>
```

```javascript
Page({
  data: {
    gridItems: [
      {
        icon: "https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/image-s.svg", 
        title: "标题文字", 
        description: "描述文字"
      },
      {
        icon: "https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/image-s.svg", 
        title: "标题文字", 
        description: "描述文字"
      },
      {
        icon: "https://imgcache.qq.com/open_proj/proj_qcloud_v2/tc-x/tea-ui/assets/image-s.svg", 
        title: "标题文字", 
        description: "描述文字"
      }
    ]
  }
})
```

### 指定每列宫格元素数量

默认一行展示三个宫格元素，可以通过 `columnNum` 自定义每列宫格元素数量。

```html
<tea-grid gridItems="{{ gridItems }}" columnNum="4"></tea-grid>
```

### 正方形宫格

设置 `square` 属性后，宫格元素的高度会和宽度保持一致。

```html
<tea-grid gridItems="{{ gridItems }}" square></tea-grid>
```

### 指定宫格元素间距

通过 `gutter` 属性设置宫格元素之间的距离。

```html
<tea-grid gridItems="{{ gridItems }}" gutter="10"></tea-grid>
```

### 开启点击反馈

通过 `clickable` 属性来开启点击反馈。

```html
<tea-grid gridItems="{{ gridItems }}" clickable></tea-grid>
```

### 页面跳转

设置 `route` 属性来指定进行页面跳转，通过 `gridItems` 数组对象的 `url` 属性来指定跳转链接地址。

```html
<tea-grid gridItems="{{ gridItems }}" route></tea-grid>
```

```javascript
Page({
  data: {
    gridItems: [
      {
        icon: "../../common/images/home/icon-widget.svg", 
        title: "页面跳转", 
        description: "组件库首页", 
        url: "../../pages/index/index"
      },
      {
        icon: "../../common/images/home/icon-widget.svg", 
        title: "页面跳转", 
        description: "Avatar组件", 
        url: "../../pages/avatar/index"
      },
      {
        icon: "../../common/images/home/icon-widget.svg", 
        title: "页面跳转", 
        description: "Swiper组件", 
        url: "../../pages/swiper/index", 
        linkType: "redirectTo"
      }
    ]
  }
})
```

### 宫格元素边框

通过 `bordered` 属性来控制是否显示宫格元素边框。

```html
<tea-grid gridItems="{{ gridItems }}" bordered="{{ false }}"></tea-grid>
```

## Props

| 参数        | 描述                   | 类型              | 默认值          | 可选值                                                     |
| --------- | -------------------- | --------------- | ------------ | ------------------------------------------------------- |
| gutter    | 宫格元素之间的间距            | `Number`        | `0`          | -                                                       |
| bordered  | 是否显示边框               | `Boolean`       | `true`       | -                                                       |
| gridItems | 宫格布局各元素数据            | `Array`         | `[]`         | -                                                       |
| columnNum | 每一列有多少个              | `Number`        | `3`          | -                                                       |
| square    | 是否将宫格元素固定为正方形        | `Boolean`       | `false`      | -                                                       |
| clickable | 是否开启宫格元素点击反馈         | `Boolean`       | `false`      | -                                                       |
| route     | 是否尝试以 url 跳转         | `Boolean`       | `false`      | -                                                       |
| linkType  | 链接跳转类型               | `String`        | `navigateTo` | `["navigateTo", "redirectTo", "switchTab", "reLaunch"]` |
| url       | 点击后跳转的链接地址           | `String`        | -            | -                                                       |
| iconSize  | 图标大小。默认单位为 px，支持自带单位 | `Number,String` | `32px`       | -                                                       |

## 事件

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

## gridItems

`Props` 中的 `gridItems` 为一个对象数组，数组中的每一个对象配置每一列，每一列有以下 `key`：

| 键名          | 描述                                            | 类型        | 默认值     | 可选值 |
| ----------- | --------------------------------------------- | --------- | ------- | --- |
| icon        | 图标名称或图片链结，可选值请查阅 [Icon 组件](/mp/packages/icon) | `String`  | -       | -   |
| iconColor   | 图标颜色                                          | `String`  | -       | -   |
| title       | 标题文字                                          | `String`  | -       | -   |
| description | 标题下方的描述信息                                     | `String`  | -       | -   |
| route       | 是否尝试以 url 跳转                                  | `Boolean` | `false` | -   |
| url         | 点击后跳转的链接地址                                    | `String`  | -       | -   |

## 外部样式类

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

## CSS变量属性表

| 变量名                              | 默认值                          | 描述  |
| -------------------------------- | ---------------------------- | --- |
| grid-item-title-text-size        | @font-size-h5                | -   |
| grid-item-title-text-color       | @text-base-color             | -   |
| grid-item-description-text-size  | @font-size-xs                | -   |
| grid-item-description-text-color | @text-light-color            | -   |
| grid-item-background-color       | @background-base-color       | -   |
| grid-item-hover-background-color | @background-base-hover-color | -   |
| grid-item-divider-color          | @border-divider-color        | -   |