Grid 宫格

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

引入

通过 easycom 自动引入，无需手动注册。

代码演示

基础用法

通过 items 属性设置宫格项列表。

<zq-grid :items="[
  { icon: 'image', text: '图片' },
  { icon: 'music', text: '音乐' },
  { icon: 'video', text: '视频' },
  { icon: 'file-text', text: '文件' },
]" />

自定义列数

通过 column-num 属性设置列数，默认为 4。

<zq-grid :items="items" :column-num="3" />
<zq-grid :items="items" :column-num="5" />

使用图片

宫格项支持 image 属性展示图片。

<zq-grid :items="[
  { image: '/static/icon1.png', text: '图片一' },
  { image: '/static/icon2.png', text: '图片二' },
]" />

自定义图标大小和颜色

通过 icon-size 和 icon-color 属性自定义图标大小和颜色。

<zq-grid :items="items" :icon-size="32" icon-color="#ee0a24" />

正方形宫格

通过 square 属性设置宫格项为正方形。

<zq-grid :items="items" square />

显示边框

通过 border 属性控制是否显示边框，默认显示。

<zq-grid :items="items" :border="false" />

横向排列

通过 direction="row" 设置内容横向排列。

<zq-grid :items="items" direction="row" />

带徽标

宫格项支持 badge 和 dot 属性展示徽标。

<zq-grid :items="[
  { icon: 'mail', text: '邮件', badge: 5 },
  { icon: 'bell', text: '通知', dot: true },
  { icon: 'settings', text: '设置' },
]" />

页面导航

宫格项支持 url 属性，点击后跳转到指定页面。

<zq-grid :items="[
  { icon: 'home', text: '首页', url: '/pages/index/index' },
  { icon: 'user', text: '我的', url: '/pages/mine/index' },
]" />

禁用点击反馈

通过 :clickable="false" 禁用点击反馈效果。

<zq-grid :items="items" :clickable="false" />

监听点击事件

<zq-grid :items="items" @click="onClick" />

function onClick({ item, index }) {
  console.log('点击:', item.text, index)
}

API

Props

参数	说明	类型	默认值
items	宫格项列表	GridItem[]	[]
column-num	列数	number	4
border	是否显示边框	boolean	true
square	是否将宫格项固定为正方形	boolean	false
clickable	是否开启点击反馈	boolean	true
direction	内容排列方向	'column' | 'row'	'column'
icon-size	图标大小	number	24
icon-color	图标颜色	string	'var(--color-primary)'

GridItem 数据结构

键名	说明	类型
icon	图标名称	string
image	图片地址（与 icon 二选一）	string
text	文字内容	string
badge	徽标内容	number | string
dot	是否显示小红点	boolean
url	点击跳转地址	string
iconColor	单独设置图标颜色	string

Events

事件名	说明	回调参数
click	点击宫格项时触发	{ item: GridItem, index: number }

注意事项

• 当设置了 url 属性时，点击宫格项会自动调用 uni.navigateTo 跳转。
• image 的尺寸为 iconSize * 2 rpx。
• 徽标使用 zq-badge 组件渲染，定位在宫格项右上角。

主题定制

变量名	说明
--color-bg-card	宫格背景色
--color-bg-hover	点击态背景色
--color-primary	默认图标颜色
--color-divider	边框颜色
--color-text-primary	文字颜色