Grid
17:06Description
ux-grid is the container: col sets the number of columns, border toggles the grid lines, align controls the horizontal alignment of a partially filled row, and hover-class sets the pressed feedback class. ux-grid-item is a single cell: index is the value reported on click and bg-color sets its background. Items read the column count and border from the parent via injected context, split the container evenly (width = 100% / col), and on click emit their own click first and then bubble the same index to the grid's click.
Compatibility
| Platform | Support |
|---|---|
| App | ✅ Supported |
| H5 | ✅ Supported |
| WeChat Mini Program | ✅ Supported |
Examples
Basic Usage
3 columns by default; tapping a grid item triggers the click event with its index.
View source
vue
<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>Custom Columns
Set the number of columns via the col prop; here it is 4 columns.
View source
vue
<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>No Border
Hide the grid border via border=false.
View source
vue
<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>Alignment
Set the grid alignment via the align prop; here it is centered.
View source
vue
<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
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
customStyle | Custom root element style | UTSJSONObject | - | - |
customClass | Custom root element style class | string | '' | - |
col | Number of columns (2 by default) | number | string | 3 | - |
border | Whether to show the grid border (true by default) | boolean | true | - |
align | Grid alignment when items are few: left / center / right (left by default) | string | 'left' | - |
hoverClass | Style class applied while a cell is pressed; "none" disables the effect (default ux-grid--hover) | string | 'ux-grid-item--hover' | - |
ux-grid-item
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
customStyle | Custom root element style | UTSJSONObject | - | - |
customClass | Custom root element style class | string | '' | - |
bgColor | Background color | string | '' | - |
index | Index returned on click | string | number | '' | - |
Events
ux-grid
| Event | Description | Params | Version |
|---|---|---|---|
click | Fires when a grid cell is tapped | index: number | string | - |
ux-grid-item
| Event | Description | Params | Version |
|---|---|---|---|
click | Fires when a grid cell is tapped | index: string | number | - |
Slots
ux-grid
| Slot | Description | Version |
|---|---|---|
default | Place ux-grid-item children here | - |
ux-grid-item
| Slot | Description | Version |
|---|---|---|
default | Cell content (icon, text, etc.) | - |
Notes
ux-grid-itemreads its column count and border from the context injected byux-grid; used standalone it falls back to 3 columns and a visible border, and its click does not bubble up.- Tapping a cell emits the
clickofux-grid-itemfirst and then that ofux-grid(sameindex); listening to both means each fires once. - The
ux-gridcontainer itself draws no lines: each line is drawn by a single cell (every cell draws its right/bottom edge, the first row adds the top, the first column adds the left), keeping adjacent cells at exactly 1px; with a partially filled row or centeredalign, each cell's border still closes into a rectangle on its own. hover-classdefaults toux-grid-item--hover; pass"none"to disable the pressed feedback.colaccepts a number or a string; the component normalizes it to a number internally.