xtf-cell

组件说明

xtf-cell 是单元格组件，用于在列表中展示一条信息，左侧可放图标/缩略图，中间显示标题和描述，右侧显示值、标签、徽标、开关或箭头。支持色调强调、分割线、必填标记、导航跳转和开关切换，是设置页、表单列表和信息展示的基础组件。

---

基础用法

1. 最简示例

通过 title 设置标题，value 设置右侧值：

<template>
  <xtf-cell-group title="基本信息">
    <xtf-cell title="用户名" value="张三" />
    <xtf-cell title="手机号" value="138****8888" />
    <xtf-cell title="地址" value="北京市朝阳区" />
  </xtf-cell-group>
</template>

2. 图标与描述

通过 icon 设置左侧图标，desc 设置标题下方描述，eyebrow 设置标题上方眉标：

<template>
  <xtf-cell-group title="功能列表">
    <xtf-cell title="通知设置" desc="管理消息推送" icon="notifications" arrow />
    <xtf-cell title="隐私设置" desc="控制数据访问" icon="lock" arrow />
    <xtf-cell title="账号安全" eyebrow="安全中心" desc="密码与验证" icon="shield" arrow />
  </xtf-cell-group>
</template>

3. 右侧标签与徽标

通过 valueTag 显示标签，通过 badge / badgeText 显示徽标，通过 extra 显示辅助文字：

<template>
  <xtf-cell-group title="消息中心">
    <xtf-cell title="系统通知" value-tag="新消息" :badge="{ value: 3 }" arrow />
    <xtf-cell title="互动消息" badge-text="2" arrow />
    <xtf-cell title="订单消息" extra="3分钟前" arrow />
    <xtf-cell
      title="活动通知"
      :value-tag="{ text: '限时', theme: 'danger', variant: 'solid' }"
      arrow
    />
  </xtf-cell-group>
</template>

4. 开关与导航

通过 switchable 启用开关，通过 url 和 arrow 实现点击导航：

<template>
  <xtf-cell-group title="偏好设置">
    <xtf-cell title="推送通知" :checked="notifyEnabled" switchable @change="onNotifyChange" />
    <xtf-cell title="深色模式" :checked="darkMode" switchable @change="onDarkModeChange" />
    <xtf-cell title="关于我们" url="/pages/about/index" arrow />
    <xtf-cell title="帮助中心" url="/pages/help/index" open-type="navigateTo" arrow />
  </xtf-cell-group>
</template>

<script>
export default {
  data() {
    return {
      notifyEnabled: true,
      darkMode: false
    }
  },
  methods: {
    onNotifyChange(val) {
      this.notifyEnabled = val
      console.log('推送通知:', val)
    },
    onDarkModeChange(val) {
      this.darkMode = val
      console.log('深色模式:', val)
    }
  }
}
</script>

5. 色调强调与变体

通过 tone 设置色调（影响背景和边框），通过 accent 显示左侧强调线，通过 variant 切换视觉风格：

<template>
  <xtf-cell-group title="订单状态">
    <xtf-cell title="待付款" tone="warning" accent value-tag="待处理" />
    <xtf-cell title="已发货" tone="success" accent value-tag="运输中" />
    <xtf-cell title="已取消" tone="danger" accent value-tag="已关闭" />
    <xtf-cell title="已完成" tone="info" accent value-tag="已完成" />
  </xtf-cell-group>
</template>

---

全部属性

属性	类型	默认值	作用描述	适用范围
title	String	''	标题文字	设置标题
eyebrow	String	''	标题上方眉标文字	分组标签
eyebrowColor	String	'caption'	眉标颜色	自定义眉标色
desc	String	''	标题下方描述文字	补充说明
value	String	''	右侧值文字	显示值
extra	String	''	右侧辅助文字	辅助信息
note	String	''	底部备注文字	底部说明
noteColor	String	'caption'	备注文字颜色	自定义备注色
icon	String	''	左侧图标名	添加图标
thumb	String	''	左侧缩略图地址	添加缩略图
thumbSize	String | Number	72	缩略图尺寸（rpx）	控制缩略图大小
thumbRadius	String | Number	20	缩略图圆角（rpx）	控制缩略图圆角
thumbShape	String	''	缩略图形状：'circle' / 'round' / 'square'	快捷设置形状
thumbRing	Boolean	false	缩略图是否显示光环	缩略图光环
iconTheme	String	''	图标主题	自定义图标主题
iconVariant	String	'soft'	图标变体	自定义图标变体
iconSize	String | Number	'sm'	图标大小	自定义图标大小
rightIcon	String	''	右侧自定义图标名	自定义右侧图标
badge	Object	null	徽标配置，支持 { value, text, theme, variant, dot }	显示徽标
badgeText	String	''	徽标文字（简写）	简易徽标
theme	String	'primary'	主题色	切换主题色
variant	String	'surface'	视觉变体：'surface' / 'soft' / 'card' / 'glass'	切换视觉风格
size	String	'md'	尺寸：'sm' / 'md' / 'lg'	控制行高
valueColor	String	'secondary'	值文字颜色	自定义值色
descColor	String	'secondary'	描述文字颜色	自定义描述色
extraColor	String	'secondary'	辅助文字颜色	自定义辅助色
valueBold	Boolean	false	值文字是否加粗	值加粗
titleBold	Boolean	false	标题是否加粗	标题加粗
required	Boolean	false	是否显示必填星号	表单必填
selected	Boolean	false	是否选中态	选中状态
checked	Boolean	false	开关是否选中，支持 v-model:checked	开关状态
switchable	Boolean	false	是否显示开关	开关切换
switchColor	String	'var(--xtf-color-primary)'	开关颜色	自定义开关色
arrow	Boolean	false	是否显示右侧箭头	导航箭头
url	String	''	点击跳转地址	导航跳转
openType	String	'navigateTo'	跳转方式：'navigateTo' / 'redirectTo' / 'switchTab' / 'reLaunch'	控制跳转方式
clickable	Boolean	false	是否可点击	可交互
disabled	Boolean	false	是否禁用	禁用交互
center	Boolean	false	是否垂直居中	居中对齐
divider	Boolean	false	是否显示底部分割线	分割线
inset	String | Number	0	分割线缩进（rpx）	分割线缩进
sideAlign	String	'center'	右侧对齐：'start' / 'center' / 'end'	右侧对齐方式
tone	String	''	色调：'primary' / 'success' / 'warning' / 'danger' / 'info'	色调强调
accent	Boolean	false	是否显示左侧强调线	左侧强调
accentColor	String	''	自定义强调线颜色	自定义强调色
valueTag	String | Object	null	值标签，字符串或 { text, theme, variant, shape, color }	显示标签
rightText	String	''	右侧文字（箭头左侧）	右侧辅助文字
rightTextColor	String	'secondary'	右侧文字颜色	自定义右侧文字色
arrowTheme	String	'secondary'	箭头图标主题	自定义箭头色
arrowIcon	String	'chevron_right'	箭头图标名	自定义箭头图标
radius	String | Number	28	圆角（rpx）	控制圆角
paddingX	String | Number	24	水平内边距（rpx）	控制水平间距
paddingY	String | Number	''	垂直内边距（rpx），默认按 size 自动计算	控制垂直间距
titleWidth	String | Number	''	标题区域宽度（rpx）	控制标题宽度
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
click	点击单元格时触发（disabled 不触发）	(event)	原生点击事件对象
cell-click	同 click	(event)	原生点击事件对象
update:checked	v-model:checked 值变更时触发	(value: Boolean)	新的开关状态
change	开关状态变更时触发	(value: Boolean)	新的开关状态
switch-change	同 change	(value: Boolean)	新的开关状态

事件使用示例

<template>
  <xtf-cell
    v-model:checked="enabled"
    title="消息通知"
    switchable
    @click="onClick"
    @change="onChange"
    @switch-change="onSwitchChange"
  />
</template>

<script>
export default {
  data() {
    return { enabled: false }
  },
  methods: {
    onClick() {
      console.log('单元格点击')
    },
    onChange(value) {
      console.log('开关状态', value)
    },
    onSwitchChange(value) {
      uni.showToast({ title: value ? '已开启' : '已关闭', icon: 'none' })
    }
  }
}
</script>

---

插槽

插槽名	说明
thumb / icon	替换左侧缩略图或图标。
title / desc	替换标题和描述区域。
value / extra / value-tag / badge / right	替换右侧信息区域。
footer	替换底部备注区域。

<template>
  <xtf-cell title="账户余额" clickable @click="showBalance">
    <template #value><xtf-text level="body" bold text="128.00 元" /></template>
    <template #right><xtf-icon name="chevron_right" theme="secondary" size="sm" /></template>
    <template #footer>
      <xtf-text level="caption" color="secondary" text="余额可用于支付订单"
    /></template>
  </xtf-cell>
</template>

<script>
export default {
  methods: {
    showBalance() {
      uni.showToast({ title: '余额详情', icon: 'none' })
    }
  }
}
</script>

---

方法

方法名	参数	说明
toggleSwitch()	无	切换 switchable 单元格的状态，并触发 update:checked、change、switch-change。

---

主题说明

• surface 变体背景使用 var(--xtf-color-surface)
• soft 变体背景使用 var(--xtf-color-surface-muted)
• card 变体背景使用 var(--xtf-card-bg)，边框使用 var(--xtf-card-border)
• glass 变体背景使用 var(--xtf-popup-bg)，阴影使用 var(--xtf-shadow-glass)
• 色调背景使用 var(--xtf-cell-tone-soft)，边框使用 var(--xtf-cell-tone-border)
• 强调线颜色使用 var(--xtf-cell-tone-accent)
• 分割线缩进使用 var(--xtf-cell-divider-inset)
• 点击缩放使用 var(--xtf-motion-active-scale)

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。