更新记录

1.0.0（2026-07-15） 下载此版本

• 首发：kex-list + kex-list-item（Vue3 <script setup>）
• 能力：标题/副标题、缩略图/左侧图标、右侧文字、角标、开关、箭头、跳转、插槽
• 无 uni-icons / uni-badge 依赖；样式兼容 App / H5 / 各小程序 / nvue

平台兼容性

uni-app(3.8.0)

kex-list

列表组件（uni-app Vue3 / <script setup>）。
包含 kex-list 容器与 kex-list-item 列表行：缩略图、左侧图标、右侧文字、角标、开关、箭头、跳转、三插槽，兼容多端。

本组件面向 Vue3。无 uni-icons / uni-badge 依赖。

平台兼容

说明：

• H5 / 小程序 / App vue 页：容器为 <view>，页面级滚动
• App nvue 页：容器为原生 <list>，子项包在 <cell> 内，利于长列表回收
• 标准 HTML 没有 <list> 标签，仅 nvue 条件编译启用，其它端不受影响

安装

1. 将插件放入项目 uni_modules/kex-list
2. easycom 自动引入，无需手动 import
3. 组件成对使用：外层 kex-list，内层若干 kex-list-item

基本用法

<template>
  <kex-list>
    <kex-list-item title="基础列表" />
    <kex-list-item title="带副标题" note="这是说明文字" />
    <kex-list-item title="带箭头" show-arrow clickable @click="onClick" />
  </kex-list>
</template>

<script setup>
const onClick = () => {
  uni.showToast({ title: '点击行', icon: 'none' })
}
</script>

默认行为说明：

• kex-list 默认 border=true：有列表外框，子项之间有通栏分割线（首行无顶线）
• kex-list-item 默认不可点；要有点击反馈 / @click，请加 clickable（或配置 link / to）
• 有 showSwitch 时不触发行点击，避免误触开关

详细用法

1. 列表容器：圆角 / 背景 / 边框

<!-- 圆角卡片列表（常用） -->
<kex-list :radius="12" background-color="#ffffff">
  <kex-list-item title="第一项" />
  <kex-list-item title="第二项" />
</kex-list>

<!-- 不要外边框和行分割线 -->
<kex-list :border="false">
  <kex-list-item title="无分割线" :border="false" />
</kex-list>

分割线说明：

• 行为通栏细线（左右贴边）
• 非 nvue 使用 1rpx，nvue 使用 0.5px，尽量各端观感一致
• 首项不画顶部分割线

2. 标题 / 副标题

<kex-list :radius="12">
  <kex-list-item title="仅标题" />
  <kex-list-item title="主标题" note="副标题说明文字" />
</kex-list>

3. 缩略图 thumb

<kex-list :radius="12">
  <!-- 尺寸：sm(20) / base(28) / lg(44)，单位 px -->
  <kex-list-item title="小图" thumb="/static/logo.png" thumb-size="sm" />
  <kex-list-item title="默认" thumb="/static/logo.png" thumb-size="base" />
  <kex-list-item
    title="大图"
    note="适合头像、封面"
    thumb="/static/logo.png"
    thumb-size="lg"
    show-arrow
    clickable
    @click="onClick"
  />
</kex-list>

thumb 有值时优先于 leftIcon，不会同时显示。

4. 左侧图标 leftIcon

支持两种写法：

<!-- 图片路径（本地 / 网络） -->
<kex-list-item
  title="菜单"
  left-icon="/static/logo.png"
  :left-icon-size="22"
  show-arrow
  clickable
/>

<!-- 字符图标 -->
<kex-list-item
  title="收藏"
  left-icon="★"
  left-icon-color="#ff9900"
  :left-icon-size="20"
  note="也可用短文本"
/>

识别规则：路径含 .png/.jpg/...，或以 /、http、data: 开头 → 按图片渲染；否则按文字渲染。

复杂图标（uni-icons 等）请用 #header 插槽。

5. 右侧文字 / 角标 / 箭头

<kex-list :radius="12">
  <!-- 右侧说明文字 + 箭头 -->
  <kex-list-item
    title="手机号"
    right-text="138****0000"
    show-arrow
    clickable
    @click="onClick"
  />

  <!-- 数字角标；超过 99 显示 99+ -->
  <kex-list-item title="消息" :badge="12" show-arrow clickable />

  <!-- 红点 -->
  <kex-list-item title="通知" :badge="true" right-text="未读" />

  <!-- 字符串角标 -->
  <kex-list-item title="活动" badge="新" show-arrow clickable />
</kex-list>

6. 开关 showSwitch

<template>
  <kex-list :radius="12">
    <kex-list-item
      title="消息通知"
      show-switch
      v-model:switch-checked="checked"
      @switchChange="onSwitch"
    />
    <kex-list-item
      title="免打扰"
      show-switch
      :switch-checked="quiet"
      switch-color="#19be6b"
      @update:switchChecked="quiet = $event"
    />
  </kex-list>
</template>

<script setup>
import { ref } from 'vue'

const checked = ref(true)
const quiet = ref(false)

const onSwitch = (detail) => {
  // detail.value 为 boolean
  console.log('switch', detail.value)
}
</script>

注意：

• 推荐 v-model:switch-checked
• 开启 showSwitch 后不会触发 @click，也不会有行 hover
• 开关颜色用 switchColor（各端原生 switch 样式仍可能略有差异）

7. 点击事件（clickable）

默认不触发点击。需要点击时：

<template>
  <kex-list :radius="12">
    <kex-list-item title="点我" clickable @click="onItemClick" />
    <kex-list-item title="带箭头可点" show-arrow clickable @click="onItemClick" />
  </kex-list>
</template>

<script setup>
const onItemClick = () => {
  uni.showToast({ title: 'clicked', icon: 'none' })
}
</script>

clickable / link / to 任一成立且非 disabled、非开关行时：

• 有点击态（hover）
• 会触发 @click（有 to 时逻辑见下一节）

8. 页面跳转（to + link）

<!-- 默认 navigateTo -->
<kex-list-item
  title="去数字框示例"
  show-arrow
  link
  to="/pages/demos/number-box/index"
/>

<!-- 指定跳转 API -->
<kex-list-item
  title="redirectTo"
  show-arrow
  link="redirectTo"
  to="/pages/demos/nav-bar/index"
/>

<kex-list-item
  title="reLaunch 回首页"
  show-arrow
  link="reLaunch"
  to="/pages/index/index"
/>

<!-- Tab 页必须用 switchTab -->
<kex-list-item
  title="switchTab"
  show-arrow
  link="switchTab"
  to="/pages/index/index"
/>

link 可选值：

有 to 时会直接跳转；@click 仍会收到结果：

const onClick = (e) => {
  // 跳转成功：{ type: 'navigate', data }
  // 跳转失败：{ type: 'navigateFail', data }
  console.log(e)
}

9. 禁用 disabled

<kex-list-item title="不可操作" disabled show-arrow />
<kex-list-item title="禁用开关" show-switch disabled :switch-checked="true" />

禁用后：无点击、无跳转、透明度降低。

10. 文本省略 ellipsis

<!-- 0：不省略（默认）；1：单行；2：最多两行 -->
<kex-list-item
  title="这是一段很长很长的标题文字需要省略显示"
  note="副标题同样很长很长很长很长很长"
  :ellipsis="1"
  show-arrow
  clickable
/>

<kex-list-item
  title="两行省略示例标题标题标题标题标题标题标题标题"
  note="两行副标题副标题副标题副标题副标题"
  :ellipsis="2"
/>

非 nvue 使用 CSS 省略；nvue 使用 lines 属性。

11. 纵向布局 direction="column"

适合主内容在上、右侧信息在下：

<kex-list-item
  title="纵向布局"
  note="主内容在上，页脚信息在下"
  right-text="更多信息"
  direction="column"
/>

12. 插槽完全自定义

三个插槽，按需覆盖默认区域：

<template>
  <kex-list :radius="12">
    <kex-list-item clickable @click="onClick">
      <template #header>
        <view class="avatar">K</view>
      </template>

      <template #body>
        <text class="t">自定义中间内容</text>
        <text class="n">可用任意节点拼布局</text>
      </template>

      <template #footer>
        <text class="edit">编辑</text>
      </template>
    </kex-list-item>
  </kex-list>
</template>

<style>
.avatar {
  width: 44px;
  height: 44px;
  margin-right: 12px;
  border-radius: 22px;
  background: #2979ff;
  color: #fff;
  /* #ifndef APP-NVUE */
  display: flex;
  /* #endif */
  align-items: center;
  justify-content: center;
}
.t { font-size: 16px; color: #303133; font-weight: 600; }
.n { margin-top: 4px; font-size: 12px; color: #909399; }
.edit { font-size: 14px; color: #2979ff; }
</style>

只自定义一侧也可以，例如：

<kex-list-item title="只改左侧" note="中间仍用 props">
  <template #header>
    <image src="/static/logo.png" style="width:40px;height:40px;margin-right:12px" />
  </template>
</kex-list-item>

13. 行样式微调

<kex-list-item
  title="自定义行背景"
  background-color="#f0f9eb"
  padding="16px 15px"
  :custom-style="{ borderRadius: '8px' }"
/>

14. 与 v-for 配合

<template>
  <kex-list :radius="12">
    <kex-list-item
      v-for="item in list"
      :key="item.id"
      :title="item.title"
      :note="item.note"
      :badge="item.badge"
      show-arrow
      clickable
      @click="(item)"
    />
  </kex-list>
</template>

<script setup>
import { ref } from 'vue'

const list = ref([
  { id: 1, title: '订单', note: '查看历史订单', badge: 2 },
  { id: 2, title: '地址', note: '收货地址管理' },
  { id: 3, title: '设置', note: '账号与安全' }
])

const  = (item) => {
  console.log(item)
}
</script>

15. 单行控制分割线

<kex-list :border="true">
  <kex-list-item title="第一项" />
  <!-- 强制隐藏本行顶线 -->
  <kex-list-item title="第二项无顶线" :border="false" />
  <kex-list-item title="第三项" />
</kex-list>

16. nvue 长列表（可选）

仅当页面是 .nvue 时，kex-list 会编译为原生 <list>：

<!-- pages/xxx/xxx.nvue -->
<template>
  <kex-list enable-back-to-top @scroll="" @scrolltolower="onLoadMore">
    <kex-list-item
      v-for="item in list"
      :key="item.id"
      :title="item.title"
      clickable
      @click="(item)"
    />
  </kex-list>
</template>

普通 .vue 页面无需关心 <list>，继续用页面滚动即可。

API

kex-list Props

kex-list Events

kex-list Slots

kex-list-item Props

kex-list-item Events

kex-list-item Slots

常见问题

注意事项

1. 外层必须是 kex-list，内层 kex-list-item，以便边框 / 首行分割线上下文生效
2. 需要 @click 时务必加 clickable（除非已设 link / to）
3. showSwitch 与行点击互斥
4. 复杂图标、双按钮等用插槽扩展，不要硬改 props
5. 本组件不含下拉刷新 / 上拉加载，可自行在页面或后续版本组合