更新记录

1.0.1（2025-09-27） 下载此版本

修复readmine文档

1.0.0（2025-09-27） 下载此版本

初次提交

平台兼容性

uni-app(3.6.5)

uni-app x(3.6.5)

其他

Tabs 标签组件使用文档

组件介绍

Tabs 标签组件是一款适配 uni-app 多端（H5、微信小程序、App 及 NVUE 环境）的高性能标签切换组件。支持标签横向滚动、下划线平滑动画、内置徽章（Badge）等核心功能，可根据标签数量自动适配固定 / 滚动布局，激活标签自动居中，满足移动端常见业务场景（如分类切换、页面导航等）。

核心特性

多端兼容：无缝适配 H5、小程序、App（含 NVUE），动画效果自动适配平台特性 内置 Badge：支持数字显示、红点模式、自定义颜色 / 形状，无需依赖外部组件 灵活配置：标签样式、下划线样式、滚动模式均可自定义，满足多样化设计需求 性能优化：DOM 尺寸缓存机制，减少重复查询，切换流畅无卡顿 完整状态：支持标签禁用、点击 / 长按事件、激活状态双向同步

快速上手

vue

组件 API 详解

1. Props（属性配置） 参数名 类型 默认值 说明 list Array [] 必传，标签数据源，每个项为对象（结构见下文 list 数据格式） current Number 0 当前激活标签的索引（支持双向同步，外部修改会触发组件内部更新） scrollable Boolean true 是否允许标签横向滚动（标签超出容器宽度时生效，false 为固定平均布局） keyName String 'name' 从 list 项中读取标签文本的字段名（如配置为 'title' 则读 item.title） lineWidth Number/String 20 下划线宽度（单位：px，支持纯数字或带单位字符串，如 20 或 '20px'） lineHeight Number/String 3 下划线高度（单位：px，格式同 lineWidth） lineColor String '#3c9cff' 下划线颜色（支持十六进制、RGB 等 CSS 颜色格式，如 '#f00' 或 'rgb(255,0,0)'） duration Number 200 下划线切换动画时长（单位：ms，值越大动画越慢） activeTextStyle Object/String { color: '#3c9cff', fontWeight: '500' } 激活标签的文本样式（支持对象或 CSS 字符串，如 { fontSize: '16px' } 或 'font-size:16px;color:red'） inactiveTextStyle Object/String { color: '#606266' } 未激活标签的文本样式（格式同 activeTextStyle） tabItemStyle Object/String { padding: '0 12px', height: '44px' } 单个标签项的基础样式（控制内边距、高度、边框等）

2. list 数据格式 list 为标签数据源，每个数组项为对象，支持以下字段： 字段名 类型 说明
   [keyName] String 标签文本（字段名由 keyName 配置决定，默认读取 item.name）
   disabled Boolean false 是否禁用该标签（禁用后不可点击，样式自动变浅，不触发 change 事件） badge Object - 徽章配置（可选，结构见下文 badge 配置）

3. badge 配置（内置徽章） 通过 list 项中的 badge 字段配置徽章，支持数字、红点、自定义样式等功能： 字段名 类型 默认值 说明 value Number/String '' 徽章显示的数字或文本（如 5、'new'、'99+'） isDot Boolean false 是否显示为红点模式（开启后忽略 value，仅显示小圆点，适合提示未读） max Number 99 数字最大值，超过时自动显示 max+（如 value: 102 会显示 99+） type String 'error' 徽章预设类型（控制背景色），可选值：'error'（红）、'success'（绿）、'warning'（橙）、'info'（灰） showZero Boolean false 当 value 为 0 时是否显示徽章（默认隐藏 0 值） bgColor String - 自定义徽章背景色（优先级高于 type 预设颜色，如 '#ff4444'） color String '#fff' 自定义徽章文本 / 红点颜色（如 '#333'） shape String 'circle' 徽章形状，可选值：'circle'（圆形）、'square'（方形，圆角 2px） inverted Boolean false 是否启用反向模式（透明背景 + 边框，颜色由 type 或 color 控制）

4. Events（事件） 组件通过事件向外传递交互信息，支持以下事件： 事件名 回调参数 说明 change index: Number 标签切换时触发（仅当标签从非激活变为激活时触发），index 为新激活标签的索引 click { item: Object, index: Number } 点击标签时触发（无论是否切换、是否禁用），返回当前标签的 item 数据和 index longpress { item: Object, index: Number } 长按标签时触发（禁用标签不会触发），返回参数同 click

5. Slots（插槽） 组件提供左右两个插槽，用于扩展标签栏功能（如返回按钮、搜索图标等）： 插槽名 说明 left 标签栏左侧插槽（可放置返回按钮、图标等，示例见下文「高级用法」） right 标签栏右侧插槽（可放置搜索按钮、更多图标等，用法同 left） 高级用法示例

6. 禁用标签 + 自定义下划线样式 vue

   :list="[ { name: '全部订单' }, { name: '已完成' }, { name: '待付款', disabled: true }, // 禁用标签 { name: '已取消' } ]" lineWidth="30" // 下划线宽度 30px lineHeight="4" // 下划线高度 4px lineColor="#4cd964" // 绿色下划线 :activeTextStyle="{ color: '#4cd964', fontSize: '16px', fontWeight: 'bold' }" // 激活文本样式 :tabItemStyle="{ padding: '0 16px', height: '50px' }" // 标签项高度 50px />

7. 反向模式徽章 + 方形形状 vue

   :list="[ { name: '消息中心', badge: { value: '99+', shape: 'square', // 方形徽章 inverted: true, // 反向模式（透明背景+边框） type: 'info', // 灰色边框 color: '#86909c' // 边框颜色 } }, { name: '通知', badge: { isDot: true, // 红点模式 color: '#ff7d00' // 橙色红点 } } ]" />

8. 固定标签布局（不滚动） 当标签数量较少（如 3 个以内）时，可设置 scrollable: false 让标签平均分配容器宽度： vue

   :list="[ { name: '首页' }, { name: '分类' }, { name: '我的' } ]" :scrollable="false" // 固定布局，不滚动 :tabItemStyle="{ padding: '0 8px' }" // 减小内边距，避免文本换行 />

9. 结合插槽实现左右功能按钮 vue

   :list="[ { name: '推荐' }, { name: '热点' }, { name: '财经' }, { name: '科技' } ]" :current="activeTab" @change="handleTabChange" > <!-- 左侧插槽：返回按钮 --> <!-- 右侧插槽：搜索 + 更多按钮 -->

注意事项

多端适配细节： NVUE 环境：组件自动使用原生 dom 和 animation 插件，确保动画流畅； 小程序环境：scroll-view 父容器需固定高度（组件默认高度 44px，可通过 tabItemStyle 修改）；

H5 环境：支持鼠标 hover 效果（标签文本颜色轻微变化）。 性能优化建议： 动态修改 list 数据时，组件会自动重新计算布局，无需手动调用方法； 避免频繁修改 list（如每秒多次更新），防止 DOM 频繁重绘； 标签数量较多时（如超过 8 个），建议保持 scrollable: true 确保体验。

样式优先级规则： 自定义 bgColor > type 预设颜色； 内联样式（如 tabItemStyle）> 组件默认样式； activeTextStyle/inactiveTextStyle 会覆盖标签文本的默认颜色和字体。

禁用状态处理： 禁用标签（disabled: true）会触发 click 事件，但不会触发 change 事件； 可在 click 事件中判断 item.disabled 做特殊处理（如提示 “该标签已禁用”）。

常见问题（FAQ） Q1：下划线位置偏移或不显示？ A1：排查以下原因： 确认 list 数据已正确传递，且 current 索引在有效范围内（0 ~ list.length-1）； NVUE 环境下，检查 dom 和 animation 原生插件是否正常引入（uni-app 会自动引入，无需额外配置）； 避免在组件 mounted 前修改 current，建议通过 watch 或 nextTick 同步数据。

Q2：徽章不显示或显示异常？ A2：检查 badge 配置： 确保 badge.show 未设置为 false（默认 true，不配置即可）； 若 value 为 0，需设置 showZero: true 才会显示； 红点模式（isDot: true）无需设置 value，但需确保 badge 对象存在且 show: true； 自定义 bgColor 时，确保颜色值格式正确（如 '#ff0000' 而非 'ff0000'）。

Q3：标签滚动时激活标签未居中？ A3：解决方案： 确认 scrollable 已设置为 true（默认 true，若手动设为 false 则不会滚动）； 检查 tabItemStyle 是否设置了异常的 margin 或 padding（如负边距会导致计算偏差）； 组件会自动计算滚动位置，若仍有偏差，可在 change 事件中手动调用 $refs.tabsRef.updateTabsLayout()（需给组件加 ref="tabsRef"）。

Q4：NVUE 环境下动画不生效？ A4：NVUE 动画依赖原生插件： 确认项目已勾选 “App 原生插件”（uni-app 项目默认勾选）； 重新编译项目（NVUE 环境下，热更新可能不生效，需重新运行）； 检查 duration 是否设置为 0（设为 0 会禁用动画）。