介绍

宫格可以在水平方向上把页面分隔成等宽度的区块，用于展示内容或进行页面导航。

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { Grid, GridItem } from 'vant';

const app = createApp();
app.use(Grid);
app.use(GridItem);

代码演示

基础用法

通过 ​icon​ 属性设置格子内的图标，​text​ 属性设置文字内容。

<van-grid>
  <van-grid-item icon="photo-o" text="文字" />
  <van-grid-item icon="photo-o" text="文字" />
  <van-grid-item icon="photo-o" text="文字" />
  <van-grid-item icon="photo-o" text="文字" />
</van-grid>

自定义列数

默认一行展示四个格子，可以通过 ​column-num​ 自定义列数。

<van-grid :column-num="3">
  <van-grid-item v-for="value in 6" :key="value" icon="photo-o" text="文字" />
</van-grid>

自定义内容

通过插槽可以自定义格子展示的内容。

<van-grid :border="false" :column-num="3">
  <van-grid-item>
    <van-image
      src="https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg"
    />
  </van-grid-item>
  <van-grid-item>
    <van-image
      src="https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg"
    />
  </van-grid-item>
  <van-grid-item>
    <van-image
      src="https://fastly.jsdelivr.net/npm/@vant/assets/apple-3.jpeg"
    />
  </van-grid-item>
</van-grid>

正方形格子

设置 ​square​ 属性后，格子的高度会和宽度保持一致。

<van-grid square>
  <van-grid-item v-for="value in 8" :key="value" icon="photo-o" text="文字" />
</van-grid>

格子间距

通过 ​gutter​ 属性设置格子之间的距离。

<van-grid :gutter="10">
  <van-grid-item v-for="value in 8" :key="value" icon="photo-o" text="文字" />
</van-grid>

内容横排

将 ​direction​ 属性设置为 ​horizontal​，可以让宫格的内容呈横向排列。

<van-grid direction="horizontal" :column-num="3">
  <van-grid-item icon="photo-o" text="文字" />
  <van-grid-item icon="photo-o" text="文字" />
  <van-grid-item icon="photo-o" text="文字" />
</van-grid>

页面导航

通过 ​to​ 属性设置 ​vue-router​ 跳转链接，通过 ​url​ 属性设置 URL 跳转链接。

<van-grid clickable :column-num="2">
  <van-grid-item icon="home-o" text="路由跳转" to="/" />
  <van-grid-item icon="search" text="URL 跳转" url="https://github.com" />
</van-grid>

徽标提示

设置 ​dot​ 属性后，会在图标右上角展示一个小红点。设置 ​badge​ 属性后，会在图标右上角展示相应的徽标。

<van-grid :column-num="2">
  <van-grid-item icon="home-o" text="文字" dot />
  <van-grid-item icon="search" text="文字" badge="99+" />
</van-grid>

API

Grid Props

参数	说明	类型	默认值
column-num	列数	number | string	4
icon-size	图标大小，默认单位为px	number | string	28px
gutter	格子之间的间距，默认单位为px	number | string	0
border	是否显示边框	boolean	true
center	是否将格子内容居中显示	boolean	true
square	是否将格子固定为正方形	boolean	false
clickable	是否开启格子点击反馈	boolean	false
direction	格子内容排列的方向，可选值为 horizontal	string	vertical
reverse v3.1.0	是否调换图标和文本的位置	boolean	false

GridItem Props

参数	说明	类型	默认值
text	文字	string	-
icon	图标名称或图片链接，等同于 Icon 组件的 name 属性	string	-
icon-prefix	图标类名前缀，等同于 Icon 组件的 class-prefix 属性	string	van-icon
icon-color	图标颜色，等同于 Icon 组件的 color 属性	string	-
dot	是否显示图标右上角小红点	boolean	false
badge	图标右上角徽标的内容	number | string	-
badge-props v3.2.8	自定义徽标的属性，传入的对象会被透传给 Badge 组件的 props	BadgeProps	-
url	点击后跳转的链接地址	string	-
to	点击后跳转的目标路由对象，等同于 vue-router 的 to 属性	string | object	-
replace	是否在跳转时替换当前页面历史	boolean	false

GridItem Events

事件名	说明	回调参数
click	点击格子时触发	event: MouseEvent

GridItem Slots

名称	说明
default	自定义宫格的所有内容
icon	自定义图标
text	自定义文字

类型定义

组件导出以下类型定义：

import type { GridProps, GridDirection, GridItemProps } from 'vant';

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-grid-item-content-padding	var(--van-padding-md) var(--van-padding-xs)	-
--van-grid-item-content-background	var(--van-background-2)	-
--van-grid-item-content-active-color	var(--van-active-color)	-
--van-grid-item-icon-size	28px	-
--van-grid-item-text-color	var(--van-text-color)	-
--van-grid-item-text-font-size	var(--van-font-size-sm)	-