Grid 宫格

17:06

说明

ux-grid 是容器：col 划分列数，border 控制描边，align 决定未排满一行时的水平对齐，hover-class 指定按压反馈类。ux-grid-item 是单个格子：index 为点击回传值，bg-color 设背景；子项通过父级注入的上下文读取列数与边框，等宽平分容器（宽度 = 100% / col），点击时先触发自身的 click，再把同一 index 冒泡给 ux-grid 的 click。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

默认 3 列，点击宫格触发 click 事件并返回索引。

查看源码

<template>
    <ux-grid :col="3" @click="onClick">
        <ux-grid-item :index="0">
            <ux-icon name="photo" :size="23" />
            <text class="text">图片</text>
        </ux-grid-item>
        <ux-grid-item :index="1">
            <ux-icon name="lock" :size="23" />
            <text class="text">锁定</text>
        </ux-grid-item>
        <ux-grid-item :index="2">
            <ux-icon name="hourglass" :size="23" />
            <text class="text">沙漏</text>
        </ux-grid-item>
        <ux-grid-item :index="3">
            <ux-icon name="home" :size="23" />
            <text class="text">首页</text>
        </ux-grid-item>
        <ux-grid-item :index="4">
            <ux-icon name="star" :size="23" />
            <text class="text">收藏</text>
        </ux-grid-item>
        <ux-grid-item :index="5">
            <ux-icon name="volume-up" :size="23" />
            <text class="text">音量</text>
        </ux-grid-item>
    </ux-grid>
</template>

<script setup lang="uts">
function onClick(index: string | number): void {
    uni.showToast({ title: '点击了第' + (Number(index) + 1) + '个', icon: 'none' });
}
</script>

<style scoped>
.text {
    font-size: 14px;
    margin-top: 2px;
    color: #909399;
}
</style>

自定义列数

通过 col 属性设置列数，这里为 4 列。

查看源码

<template>
    <ux-grid :col="4">
        <ux-grid-item :index="0">
            <ux-icon name="integral" :size="20" />
            <text class="text">积分</text>
        </ux-grid-item>
        <ux-grid-item :index="1">
            <ux-icon name="gift" :size="20" />
            <text class="text">礼物</text>
        </ux-grid-item>
        <ux-grid-item :index="2">
            <ux-icon name="scan" :size="20" />
            <text class="text">扫码</text>
        </ux-grid-item>
        <ux-grid-item :index="3">
            <ux-icon name="trash" :size="20" />
            <text class="text">删除</text>
        </ux-grid-item>
        <ux-grid-item :index="4">
            <ux-icon name="shopping-cart" :size="20" />
            <text class="text">购物车</text>
        </ux-grid-item>
        <ux-grid-item :index="5">
            <ux-icon name="rewind-right" :size="20" />
            <text class="text">快退</text>
        </ux-grid-item>
    </ux-grid>
</template>

<style scoped>
.text {
    font-size: 14px;
    margin-top: 2px;
    color: #909399;
}
</style>

无边框

通过 border=false 隐藏宫格边框。

查看源码

<template>
    <ux-grid :col="3" :border="false">
        <ux-grid-item :index="0">
            <ux-icon name="photo" :size="23" />
            <text class="text">图片</text>
        </ux-grid-item>
        <ux-grid-item :index="1">
            <ux-icon name="lock" :size="23" />
            <text class="text">锁定</text>
        </ux-grid-item>
        <ux-grid-item :index="2">
            <ux-icon name="home" :size="23" />
            <text class="text">首页</text>
        </ux-grid-item>
    </ux-grid>
</template>

<style scoped>
.text {
    font-size: 14px;
    margin-top: 2px;
    color: #909399;
}
</style>

对齐方式

通过 align 属性设置宫格对齐方式，这里为居中。

查看源码

<template>
    <ux-grid :col="3" align="center">
        <ux-grid-item :index="0">
            <ux-icon name="star" :size="23" />
            <text class="text">收藏</text>
        </ux-grid-item>
        <ux-grid-item :index="1">
            <ux-icon name="home" :size="23" />
            <text class="text">首页</text>
        </ux-grid-item>
    </ux-grid>
</template>

<style scoped>
.text {
    font-size: 14px;
    margin-top: 2px;
    color: #909399;
}
</style>

API

Props

ux-grid

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
col	分成几列（默认2）	number | string	3	-
border	是否显示边框（默认true）	boolean	true	-
align	宫格对齐方式，数量少时靠左/居中/靠右（默认left）	string	'left'	-
hoverClass	宫格按压时的样式类，"none"为无效果（默认ux-grid--hover）	string	'ux-grid-item--hover'	-

ux-grid-item

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
bgColor	背景颜色	string	''	-
index	点击时返回的index	string | number	''	-

Events

ux-grid

事件名	说明	回调参数	版本
click	点击宫格触发	index: number | string	-

ux-grid-item

事件名	说明	回调参数	版本
click	点击宫格触发	index: string | number	-

Slots

ux-grid

插槽名	说明	版本
default	放置 ux-grid-item 子项	-

ux-grid-item

插槽名	说明	版本
default	格子内容（图标、文字等）	-

注意事项

1. ux-grid-item 的列数与边框来自 ux-grid 注入的上下文；脱离 ux-grid 单独使用时按 3 列、显示边框处理，且不会向上冒泡点击。
2. 点击一个格子会先后触发 ux-grid-item 与 ux-grid 的 click（同一 index），两个事件都监听会各收到一次。
3. ux-grid 容器本身不描边：每条线由单个格子绘制（每格画右/下，首行格补上、首列格补左），保证相邻格之间恒为 1px；未排满的行与 align 居中时，格项边框仍各自围合成闭合矩形。
4. hover-class 默认 ux-grid-item--hover，传 "none" 可关闭按压反馈。
5. col 传数字或字符串均可，组件内部统一转为数字。