uView Pro X

简体中文

English

简体中文

English

主题

Cell 单元格 ​

17:06

说明 ​

由分组容器 ux-cell-group 与单元格 ux-cell-item 组合而成。ux-cell-group 负责整组外观：可选分组标题 title 与上下外边框 border，并把子项排成一列；ux-cell-item 负责单个单元格的左侧图标/标题/描述、右侧内容与箭头，以及点击反馈与 click 事件。ux-cell-item 需放在 ux-cell-group 内使用。

兼容性 ​

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

示例 ​

基础用法 ​

使用 ux-cell-group 包裹 ux-cell-item，title 为左侧标题，value 为右侧内容。

查看源码
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>

分组标题 ​

通过 ux-cell-group 的 title 属性设置分组标题。

查看源码
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 属性设置左侧图标，只支持内置图标。

查看源码
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>

描述信息 ​

通过 label 属性设置标题下方的描述信息。

查看源码
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 属性在左侧显示必填星号。

查看源码
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 设置箭头方向，arrow=false 隐藏箭头。

查看源码
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>

自定义标题宽度 ​

通过 title-width 设置标题宽度，单位px。

查看源码
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>

边框控制 ​

ux-cell-group 的 border 控制分组外边框，ux-cell-item 的 border-top/border-bottom 控制单项边框。

查看源码
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>

外观定制 ​

center 控制垂直居中，bg-color 控制背景色，title-style/value-style/label-style 控制各区域样式，hover-class 设为 none 可关闭点击反馈。

查看源码
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>

点击事件 ​

点击 cell 触发 click 事件，index 标识点击的是第几个。

查看源码
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>

自定义 hoverClass ​

通过 hover-class 自定义按压反馈类名，类样式须定义在使用方（页面/全局）且带 !important；设为 none 可关闭反馈。

查看源码
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>

自定义内容 ​

通过默认插槽自定义右侧内容，通过 icon 插槽自定义左侧图标。

查看源码
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 ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
title分组标题string''-
border是否显示分组list上下边框booleantrue-
titleStyle分组标题的样式UTSJSONObject--

ux-cell-item ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
icon左侧图标名称string''-
title左侧标题string | number''-
value右侧内容string | number''-
label标题下方的描述信息string | number''-
borderBottom是否显示下边框booleantrue-
borderTop是否显示上边框booleanfalse-
hoverClass是否开启点击反馈string'ux-cell--hover'-
arrow是否显示右侧箭头booleantrue-
center内容是否垂直居中booleanfalse-
required是否显示左边表示必填的星号booleanfalse-
titleWidth标题的宽度，单位pxnumber | string''-
arrowDirection右侧箭头方向CellItemArrowDirection'right'-
titleStyle控制标题的样式UTSJSONObject--
valueStyle右侧显示内容的样式UTSJSONObject--
labelStyle描述信息的样式UTSJSONObject--
bgColor背景颜色string'transparent'-
iconSize左边图标的大小number | string17-
iconStyle左边图标的样式UTSJSONObject--

Events ​

ux-cell-item ​

事件名说明回调参数版本
click点击单元格时触发event: UniEvent-

Slots ​

ux-cell-group ​

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

ux-cell-item ​

插槽名说明版本
icon自定义左侧图标（未传 icon prop 时生效）-
title自定义标题内容（title 为空时生效）-
label自定义标题下方描述（label 为空时生效）-
default自定义右侧内容（value 为空时生效）-
right-icon自定义右侧箭头区域内容-

注意事项 ​

  1. ux-cell-item 需放在 ux-cell-group 内使用：group 提供整组背景、上下外边框与分组标题，并通过父子通信把边框信息下发给 item；单独使用会缺少分组外壳与分组标题。
  2. border（group，默认 true）为 true 时，最后一项的下边框与 group 底边框重叠会被自动隐藏（该项 border-bottom 失效）；设为 border=false 后各项按自身 border-top / border-bottom 显示。
  3. arrow 默认 true，arrow-direction 通过旋转实现（up 转 -90deg、down 转 90deg、right 不转）；arrow=false 隐藏箭头。
  4. hover-class 默认 ux-cell--hover（浅灰按压）；自定义类名须定义在使用方且带 !important，否则会被根节点内联背景（bgColor 默认 transparent）覆盖；设为 none 关闭反馈。
  5. required 星号为绝对定位在标题左侧（left: 8px），依赖 overflow: visible（组件已声明）；标题过长或自定义 title-style 时可能与其重叠。
  6. icon 只支持 uView 内置图标名（内部走 ux-icon）；要放自定义图标改用 #icon 插槽。
  7. title-width 单位为 px，不传时标题宽度为 auto；固定宽度后配合 title-style 可做背景色块。
  8. click 回传的是 UniEvent；如需区分点击的是第几项，在绑定处自行传参（演示即用 @click="onClick('1')"）。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5