外观
Grid 宫格布局
约 1429 字大约 5 分钟
2025-10-31
宫格组件一般用于同时展示多个同类项目的场景,可以给宫格的项目设置徽标组件(badge),或者图标等,也可以扩展为左右滑动的轮播形式。
基本使用
- 该组件外层为
un-grid组件包裹,通过col设置内部宫格的列数 - 内部通过
un-grid-item组件的slot设置宫格的内容 - 如果不需要宫格的边框,可以设置
border为false - 通过
align属性可以设置宫格的对齐方式
<template>
<view>
<un-grid
:border="false"
@click="handleClick"
align="center"
>
<un-grid-item
v-for="(baseListItem,baseListIndex) in baseList"
:key="baseListIndex"
>
<un-icon
:customStyle="{paddingTop:'10px'}"
:name="baseListItem.name"
:size="22"
></un-icon>
<text class="grid-text">{{baseListItem.title}}</text>
</un-grid-item>
</un-grid>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type BaseList = {
name: string,
title: string
}
const baseList = ref<BaseList[]>([
{
name: 'photo',
title: '图片'
},
{
name: 'lock',
title: '锁头'
},
])
const handleClick = (name: string | number) => {
uni.showToast({
title: `点击了第${name}个`
})
}
</script>
<style lang="scss">
.grid-text {
font-size: 14px;
color: #909399;
padding: 10rpx 0 20rpx 0rpx;
/* #ifndef APP-PLUS */
box-sizing: border-box;
/* #endif */
}
</style>显示边框
通过设置border属性为true,可以显示宫格的边框。
<template>
<view>
<un-grid :border="true">
<un-grid-item
v-for="(listItem,listIndex) in list"
:key="listIndex"
customStyle="padding-top: 10px; padding-bottom: 10px"
>
<un-icon
:customStyle="{paddingTop:20+'rpx'}"
:name="listItem.name"
:size="22"
></un-icon>
<text class="grid-text">{{listItem.title}}</text>
</un-grid-item>
</un-grid>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const list = ref([{
name: 'photo',
title: '图片'
},
{
name: 'lock',
title: '锁头'
},
{
name: 'star',
title: '星星'
},
{
name: 'hourglass',
title: '沙漏'
},
{
name: 'home',
title: '首页'
},
{
name: 'star',
title: '音量'
},
])
</script>
<style lang="scss">
.grid-text {
font-size: 14px;
color: #909399;
padding: 10rpx 0 20rpx 0rpx;
/* #ifndef APP-PLUS */
box-sizing: border-box;
/* #endif */
}
</style>绑定点击事件&自定义列数
<template>
<view>
<un-grid
:border="false"
col="4"
@click="click"
>
<un-grid-item
v-for="(listItem,listIndex) in list"
:key="listIndex"
>
<un-icon
:customStyle="{paddingTop:20+'rpx'}"
:name="listItem.name"
:size="22"
></un-icon>
<text class="grid-text">{{listItem.title}}</text>
</un-grid-item>
</un-grid>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const list = ref([{
name: 'photo',
title: '图片'
},
{
name: 'lock',
title: '锁头'
},
{
name: 'star',
title: '星星'
},
{
name: 'hourglass',
title: '沙漏'
},
{
name: 'home',
title: '首页'
},
{
name: 'star',
title: '音量'
},
])
const click = (name: string | number) => {
uni.showToast({
title: `点击了第${name}个`
})
}
</script>
<style lang="scss">
.grid-text {
font-size: 14px;
color: #909399;
padding: 10rpx 0 20rpx 0rpx;
/* #ifndef APP-PLUS */
box-sizing: border-box;
/* #endif */
}
</style>实现宫格的左右滑动
结合uni的swiper组件可以实现宫格的左右滑动,因为swiper特性的关系,请指定swiper的高度 ,否则swiper的高度不会被内容撑开,可以自定义swiper的指示器,达到更高的灵活度
<template>
<swiper :indicator-dots="true" class="swiper">
<swiper-item>
<un-grid :border="true">
<un-grid-item
:customStyle="{width:220+'rpx',height:220+'rpx'}"
v-for="(item, index) in swiperList"
:index="index"
:key="index"
>
<un-icon
:customStyle="{paddingTop:20+'rpx'}"
:name="item"
:size="22"
></un-icon>
<text class="grid-text">{{ '宫格' + (index + 1) }}</text>
</un-grid-item>
</un-grid>
</swiper-item>
<swiper-item>
<un-grid :border="true">
<un-grid-item
:customStyle="{width:220+'rpx',height:220+'rpx'}"
v-for="(item, index) in swiperList"
:index="index + 9"
:key="index"
>
<un-icon
:customStyle="{paddingTop:20+'rpx'}"
:name="item"
:size="22"
></un-icon>
<text class="grid-text">{{ '宫格' + (index + 1) }}</text>
</un-grid-item>
</un-grid>
</swiper-item>
<swiper-item>
<un-grid :border="true">
<un-grid-item
:customStyle="{width:220+'rpx',height:220+'rpx'}"
v-for="(item, index) in swiperList"
:index="index + 18"
:key="index"
>
<un-icon
:customStyle="{paddingTop:20+'rpx'}"
:name="item"
:size="22"
></un-icon>
<text class="grid-text">{{ "宫格" + (index + 1) }}</text>
</un-grid-item>
</un-grid>
</swiper-item>
</swiper>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const swiperList = ref(['integral', 'kefu-ermai', 'coupon', 'gift', 'scan', 'pause-circle', 'wifi', 'email', 'list'])
</script>
<style lang="scss">
.swiper {
height: 720rpx;
}
.grid-text {
font-size: 14px;
color: #909399;
padding: 10rpx 0 20rpx 0rpx;
/* #ifndef APP-PLUS */
box-sizing: border-box;
/* #endif */
}
</style>间距
通过设置gutter属性,可以设置宫格之间的间距。
<template>
<view>
<un-grid :border="false" col="3" gutter="10">
<un-grid-item v-for="(listItem,listIndex) in list" :key="listIndex">
<view class="grid-item-content">
<un-icon
:customStyle="{paddingTop:20+'rpx'}"
:name="listItem.name"
:size="22"
></un-icon>
<text class="grid-text">{{listItem.title}}</text>
</view>
</un-grid-item>
</un-grid>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const list = ref([{
name: 'photo',
title: '图片'
},
{
name: 'lock',
title: '锁头'
},
{
name: 'star',
title: '星星'
},
{
name: 'hourglass',
title: '沙漏'
},
{
name: 'home',
title: '首页'
},
{
name: 'star',
title: '音量'
},
])
</script>
<style lang="scss">
.grid-text {
font-size: 14px;
color: #909399;
padding: 10rpx 0 20rpx 0rpx;
/* #ifndef APP-PLUS */
box-sizing: border-box;
/* #endif */
}
.grid-item-content {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
height: 100%;
}
</style>API
Grid Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| col | 宫格的列数 | String | Number | 3 |
| border | 是否显示宫格的边框 | Boolean | false |
| align | 宫格的对齐方式,用于控制只有一两个宫格时的对齐场景 | Enum | left |
| gutter | 栅格间隔,左右各为此值的一半,单位任意 | String | Number | 0 |
| round | 设置圆角值 | String | Number | - |
| bgColor | 背景颜色 | String | - |
Grid-item Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 宫格的name | String | Number | - |
| bgColor | 宫格的背景颜色 | String | transparent(背景透明) |
| customStyle | 自定义样式,对象形式 | String | Object | - |
| index | 宫格的索引 | String | Number | - |
Grid Event
注意:请在<un-grid></un-grid>上监听此事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击宫格触发 | name: string | number |
Grid-item Event
注意:请在<un-grid-item></un-grid-item>上监听此事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击宫格触发 | 无 |
数据类型
GridProps
| 字段名 | 类型 | 说明 |
|---|---|---|
| col | string | number | 宫格的列数 |
| border | boolean | 是否显示宫格的边框 |
| align | string | 宫格的对齐方式 |
| gutter | string | number | 栅格间隔,左右各为此值的一半 |
| round | string | number | 设置圆角值 |
| bgColor | string | 背景颜色 |
| customStyle | string | object | 自定义样式,对象形式 |
GridItemProps
| 字段名 | 类型 | 说明 |
|---|---|---|
| name | string | number | 宫格的name |
| bgColor | string | 宫格的背景颜色 |
| customStyle | string | object | 自定义样式,对象形式 |
| index | string | number | 宫格的索引 |
Scss 变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-grid-item-bg-color | $bg-color | 宫格项背景颜色 |
提示
组件内部默认使用 scss 变量,如需修改,请查看 scss 变量使用 文档
