Cell

17:06

Description

A pair of components: the group container ux-cell-group and the cell ux-cell-item. ux-cell-group handles the group appearance — an optional group title (title) and the top/bottom outer borders (border) — and lays its children out in a column; ux-cell-item renders a single row with the left icon/title/description, the right content and arrow, plus the press feedback and click event. Place ux-cell-item inside ux-cell-group.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Wrap ux-cell-item with ux-cell-group; title is the left label and value is the right content.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item title="用户信息" value="内容"></ux-cell-item>
        <ux-cell-item title="会员等级" value="新版本"></ux-cell-item>
        <ux-cell-item title="收货地址" value="北京"></ux-cell-item>
    </ux-cell-group>
</template>

Group Title

Set the group title via the title prop of ux-cell-group.

View source

vue

<template>
    <ux-cell-group title="分组标题" :title-style="groupTitleStyle">
        <ux-cell-item title="用户信息" value="内容"></ux-cell-item>
        <ux-cell-item title="会员等级" value="新版本"></ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="uts">
import { createStyle } from '@/uni_modules/uview-pro-x';

const groupTitleStyle = computed((): UTSJSONObject => {
    const style = createStyle();
    style['color'] = '#303133';
    style['font-weight'] = 'bold';
    return style;
});

</script>

Icon

Set the left icon via the icon prop; only built-in icons are supported.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item icon="setting" icon-size="22" :icon-style="iconStyle" title="设置"></ux-cell-item>
        <ux-cell-item icon="star" title="收藏"></ux-cell-item>
        <ux-cell-item icon="integral" title="积分"></ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="uts">
import { createStyle } from '@/uni_modules/uview-pro-x';

const iconStyle = computed((): UTSJSONObject => {
    const style = createStyle();
    style['color'] = '#2979ff';
    return style;
});

</script>

Description

Set the description below the title via the label prop.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item icon="file-text" title="用户协议" label="点击查看协议详情"></ux-cell-item>
        <ux-cell-item icon="lock" title="隐私政策" label="点击查看隐私政策详情"></ux-cell-item>
    </ux-cell-group>
</template>

Required

Show a required asterisk on the left via the required prop.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item title="姓名" required value="张三"></ux-cell-item>
        <ux-cell-item title="手机号" required value="138****8888"></ux-cell-item>
    </ux-cell-group>
</template>

Arrow Direction

Set the arrow direction via arrow-direction; arrow=false hides the arrow.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item title="箭头向右" arrow-direction="right"></ux-cell-item>
        <ux-cell-item title="箭头向上" arrow-direction="up"></ux-cell-item>
        <ux-cell-item title="箭头向下" arrow-direction="down"></ux-cell-item>
        <ux-cell-item title="无箭头" :arrow="false"></ux-cell-item>
    </ux-cell-group>
</template>

Custom Title Width

Set the title width via title-width in px.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item title="标题" title-width="100" :title-style="titleWidthBg" value="内容"></ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="uts">
import { createStyle } from '@/uni_modules/uview-pro-x';

const titleWidthBg = computed((): UTSJSONObject => {
    const style = createStyle();
    style['background-color'] = '#f5f5f5';
    return style;
});

</script>

Border Control

border of ux-cell-group controls the group outer border; border-top/border-bottom of ux-cell-item control per-item borders.

View source

vue

<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="无分组外边框" border-top value="border-top"></ux-cell-item>
        <ux-cell-item title="无下边框" :border-bottom="false" value="border-bottom=false"></ux-cell-item>
        <ux-cell-item title="默认下边框" value="默认"></ux-cell-item>
    </ux-cell-group>
</template>

Custom Appearance

center controls vertical centering, bg-color sets the background, title-style/value-style/label-style style each area, and hover-class set to none disables the click feedback.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item
            title="自定义样式"
            label="描述文字"
            value="内容"
            center
            bg-color="#f7f8fa"
            :title-style="titleStyle"
            :value-style="valueStyle"
            :label-style="labelStyle"
            hover-class="none"
        ></ux-cell-item>
    </ux-cell-group>
</template>

<script setup lang="uts">
import { createStyle } from '@/uni_modules/uview-pro-x';

const titleStyle = computed((): UTSJSONObject => {
    const style = createStyle();
    style['color'] = '#2979ff';
    return style;
});

const valueStyle = computed((): UTSJSONObject => {
    const style = createStyle();
    style['color'] = '#fa3534';
    return style;
});

const labelStyle = computed((): UTSJSONObject => {
    const style = createStyle();
    style['fontSize'] = '12px';
    return style;
});

</script>

Click Event

Clicking a cell triggers the click event; index identifies which cell was clicked.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item title="点击我" @click="onClick('1')"></ux-cell-item>
        <ux-cell-item title="点击我" @click="onClick('2')"></ux-cell-item>
    </ux-cell-group>
    <text class="result">点击结果: {{ result }}</text>
</template>

<script setup lang="uts">
const result = ref<string>('');

function onClick(index: string): void {
    result.value = index;
}
</script>

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

Custom hoverClass

Customize the press feedback class via hover-class; the class must be defined by the consumer (page/global) with !important. Set to none to disable feedback.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item hover-class="custom-hover" title="自定义按压背景" value="点击试试"></ux-cell-item>
        <ux-cell-item hover-class="none" title="无按压反馈" value="hover-class=none"></ux-cell-item>
    </ux-cell-group>
</template>

<style lang="scss">
/* 自定义 hoverClass 反馈类：须定义在使用方（页面/全局非 scoped 位置），
   且带 !important 覆盖根节点内联背景（bgColor 默认 transparent） */
.custom-hover {
    background-color: $u-type-primary-light !important;
}
</style>

Custom Content

Customize the right content via the default slot and the left icon via the icon slot.

View source

vue

<template>
    <ux-cell-group>
        <ux-cell-item title="自定义右侧">
            <text class="slot-text">自定义内容</text>
        </ux-cell-item>
        <ux-cell-item title="自定义图标">
            <template #icon>
                <ux-icon name="star" size="17" color="#fa3534" />
            </template>
        </ux-cell-item>
    </ux-cell-group>
</template>

<style scoped>
.slot-text {
    font-size: 13px;
    color: #2979ff;
}
</style>

API

Props

ux-cell-group

Property	Description	Type	Default	Version
`customStyle`	Custom root element style	`string \| UTSJSONObject`	`-`	-
`customClass`	Custom root element style class	`string`	`''`	-
`title`	Group title	`string`	`''`	-
`border`	Whether to show the group's top/bottom borders	`boolean`	`true`	-
`titleStyle`	Style of the group title	`UTSJSONObject`	`-`	-

ux-cell-item

Property	Description	Type	Default	Version
`customStyle`	Custom root element style	`string \| UTSJSONObject`	`-`	-
`customClass`	Custom root element style class	`string`	`''`	-
`icon`	Left icon name (built-in uView icons only)	`string`	`''`	-
`title`	Left title	`string \| number`	`''`	-
`value`	Right content	`string \| number`	`''`	-
`label`	Description below the title	`string \| number`	`''`	-
`borderBottom`	Whether to show the bottom border	`boolean`	`true`	-
`borderTop`	Whether to show the top border	`boolean`	`false`	-
`hoverClass`	Click feedback class; `none` disables it	`string`	`'ux-cell--hover'`	-
`arrow`	Whether to show the right arrow	`boolean`	`true`	-
`center`	Whether to vertically center the content	`boolean`	`false`	-
`required`	Whether to show the required asterisk on the left	`boolean`	`false`	-
`titleWidth`	Title width, in px	`number \| string`	`''`	-
`arrowDirection`	Right arrow direction: `right` / `up` / `down`	`CellItemArrowDirection`	`'right'`	-
`titleStyle`	Style of the title	`UTSJSONObject`	`-`	-
`valueStyle`	Style of the right content	`UTSJSONObject`	`-`	-
`labelStyle`	Style of the description	`UTSJSONObject`	`-`	-
`bgColor`	Background color	`string`	`'transparent'`	-
`iconSize`	Left icon size, in px	`number \| string`	`17`	-
`iconStyle`	Style of the left icon	`UTSJSONObject`	`-`	-

Events

ux-cell-item

Event	Description	Params	Version
`click`	Emitted when the cell is clicked	`event: UniEvent`	-

Slots

ux-cell-group

Slot	Description	Version
`default`	Place `ux-cell-item` children	-

ux-cell-item

Slot	Description	Version
`icon`	Custom left icon (used when `icon` is not set)	-
`title`	Custom title content (used when `title` is empty)	-
`label`	Custom description below the title (used when `label` is empty)	-
`default`	Custom right content (used when `value` is empty)	-
`right-icon`	Custom content for the right arrow area	-

Notes

Place ux-cell-item inside ux-cell-group: the group provides the group background, top/bottom outer borders, and the group title, and passes border information down to the items via parent-child communication; used alone, an item loses the group shell and group title.
When border on the group is true (default), the last item's bottom border is automatically hidden because it overlaps the group's bottom border (that item's border-bottom is ignored); with border=false, each item shows its own border-top / border-bottom.
arrow is true by default; arrow-direction is implemented by rotation (up rotates -90deg, down 90deg, right none); arrow=false hides the arrow.
hover-class defaults to ux-cell--hover (light-gray press feedback); a custom class must be defined by the consumer with !important, otherwise it is overridden by the root's inline background (bgColor defaults to transparent); set it to none to disable feedback.
The required asterisk is absolutely positioned at the left of the title (left: 8px) and relies on overflow: visible (already declared); a long title or a custom title-style may overlap it.
icon only accepts built-in uView icon names (it goes through ux-icon internally); use the #icon slot for a custom icon.
title-width is in px; when omitted the title width is auto. Once a fixed width is set, combine it with title-style to build a colored block.
click emits a UniEvent; to tell which row was clicked, pass your own argument at the binding site (the demo uses @click="onClick('1')").

Cell ​

Description ​

Compatibility ​

Examples ​

Basic Usage ​

Group Title ​

Icon ​

Description ​

Required ​

Arrow Direction ​

Custom Title Width ​

Border Control ​

Custom Appearance ​

Click Event ​

Custom hoverClass ​

Custom Content ​

API ​

Props ​

ux-cell-group ​

ux-cell-item ​

Events ​

ux-cell-item ​

Slots ​

ux-cell-group ​

ux-cell-item ​

Notes ​

Cell

Description

Compatibility

Examples

Basic Usage

Group Title

Icon

Description

Required

Arrow Direction

Custom Title Width

Border Control

Custom Appearance

Click Event

Custom hoverClass

Custom Content

API

Props

ux-cell-group

ux-cell-item

Events

ux-cell-item

Slots

ux-cell-group

ux-cell-item

Notes