uView Next
4.0.105

外观

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 | Number3
border是否显示宫格的边框Booleanfalse
align宫格的对齐方式，用于控制只有一两个宫格时的对齐场景
Enum
left
gutter栅格间隔，左右各为此值的一半，单位任意String | Number0
round设置圆角值String | Number-
bgColor背景颜色String-

Grid-item Props

参数说明类型默认值
name宫格的nameString | Number-
bgColor宫格的背景颜色Stringtransparent(背景透明)
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

字段名类型说明
colstring | number宫格的列数
borderboolean是否显示宫格的边框
alignstring宫格的对齐方式
gutterstring | number栅格间隔，左右各为此值的一半
roundstring | number设置圆角值
bgColorstring背景颜色
customStylestring | object自定义样式，对象形式

GridItemProps

字段名类型说明
namestring | number宫格的name
bgColorstring宫格的背景颜色
customStylestring | object自定义样式，对象形式
indexstring | number宫格的索引

Scss 变量

变量名默认值说明
$un-grid-item-bg-color$bg-color宫格项背景颜色

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next