更新记录

1.0.6（2026-09-06） 下载此版本

1. 【优化】canvas 凹口观感，解决非纯色背景（渐变/图片/深色）下 concave 伪类实现“光圈须与页面背景同色”的局限

1.0.5（2026-07-26） 下载此版本

1. 【新增】v-model:current 受控选中，支持外部设置初始选中项与程序化切换
2. 【新增】item 级角标系统：badge（数字/文本，支持 badgeMax 上限显示 99+）、dot（红点）
3. 【新增】beforeChange 切换守卫，支持返回 Promise，可用于登录拦截等场景
4. 【新增】autoRoute 路由联动：item 配置 pagePath + switchMode 后点击自动跳转；配套 useTabBar 组合式函数实现多页面选中态同步
5. 【新增】字体图标支持：item 配置 iconType: 'font' 后 icon/active 传字体图标 class
6. 【新增】样式配置：background、textColor、activeTextColor、fontSize、height、zIndex、duration、fixed、placeholder
7. 【新增】item 支持 disabled 禁用；组件暴露 switchTo(index) 编程式切换方法
8. 【优化】布局改为百分比自适应，修复宽屏/iPad/折叠屏下 750rpx 硬编码导致的错位
9. 【优化】角标锚定图标右上角并随选中图标一同浮入圆钮，自带底栏同色描边；修复 tab 数量变化时角标偏移；图片图标增加 aspectFit 与默认尺寸
10. 【修复】移除生产环境调试日志与无效样式；data 为空时的除零保护
11. 【兼容】旧版 corner + cornerMark 用法与 change 事件的 currenIndex 字段继续可用（已标记废弃，建议迁移）

1.0.3（2025-12-02） 下载此版本

1.更新角标功能 2.简化示例

平台兼容性

uni-app(4.02)

sk-tab-bar

组件形式的镂空弧形 tabBar，选中项自动上浮进入圆形按钮，凹槽随切换平滑移动。默认 mode="concave"（伪类凹陷弧形，光圈需与页面背景同色）；页面背景为图片/渐变等复杂背景、无法与光圈同色时，建议显式设 mode="plain"（实心栏、不依赖背景色），

• ✅ v-model:current 受控选中，支持外部设置初始项与程序化切换
• ✅ item 级角标（数字 / 红点 / 99+ 上限）
• ✅ beforeChange 切换守卫（支持异步，可做登录拦截）
• ✅ autoRoute 路由联动 + useTabBar 多页面选中态同步
• ✅ 作用域插槽完全自定义 tab 内容
• ✅ 图片图标 / 字体图标双模式
• ✅ 主题样式全量可配，百分比布局自适应宽屏
• ✅ TypeScript 类型导出

扫码体验

基础用法

组件形式 tabBar 不依赖 pages.json 的原生 tabBar 配置；如需页面跳转请使用 autoRoute 或在 change 回调中自行处理。

<template>
    <sk-tab-bar v-model:current="current" :data="list" @change="onChange" />
</template>

<script lang="ts" setup>
    import { ref } from 'vue'
    import type { SkTabBarItem, SkTabBarChangeEvent } from '@/uni_modules/sk-tab-bar/components/sk-tab-bar/sk-tab-bar.type'
    import icon1 from '@/static/66.png'
    import icon1Active from '@/static/icon1.png'
    import icon2 from '@/static/77.png'
    import icon2Active from '@/static/icon2.png'

    const current = ref(0)
    const list = ref<SkTabBarItem[]>([
        { text: '首页', icon: icon1, active: icon1Active },
        { text: '资源列表', icon: icon2, active: icon2Active }
    ])

    const onChange = (e: SkTabBarChangeEvent) => {
        console.log('切换到：', e.currentIndex, e.text)
    }
</script>

角标 / 红点

角标配置在每个 item 上，互不影响；数字超过 badgeMax（默认 99）显示 99+，为 0 或空时自动隐藏。

<sk-tab-bar :data="list" :badge-max="99" />

const list = ref<SkTabBarItem[]>([
    { text: '首页', icon: icon1, active: icon1Active },
    { text: '消息', icon: icon2, active: icon2Active, badge: 128 }, // 显示 99+
    { text: '我的', icon: icon3, active: icon3Active, dot: true }   // 红点
])

切换拦截（beforeChange）

返回 false 或 Promise<false> 时阻止切换，常用于登录校验：

<sk-tab-bar :data="list" :before-change="beforeChange" />

const beforeChange = async (index: number, item: SkTabBarItem) => {
    if (index === 2 && !isLogin.value) {
        uni.navigateTo({ url: '/pages/login/index' })
        return false
    }
    return true
}

路由联动（autoRoute）

item 配置 pagePath 后点击自动跳转；多页面场景配合 useTabBar 同步选中态：

<sk-tab-bar auto-route v-model:current="current" :data="items" @change="e => setCurrent(e.currentIndex)" />

import { useTabBar } from '@/uni_modules/sk-tab-bar/components/sk-tab-bar/use-tab-bar'

// 每个页面调用同一份共享状态
const { current, items, setCurrent } = useTabBar([
    { text: '首页', icon: icon1, active: icon1Active, pagePath: '/pages/home/index', switchMode: 'reLaunch' },
    { text: '我的', icon: icon2, active: icon2Active, pagePath: '/pages/mine/index', switchMode: 'reLaunch' }
])

自定义内容（插槽）

通过 item 作用域插槽完全接管 tab 渲染：

<sk-tab-bar :data="list">
    <template #item="{ item, index, active }">
        <image :src="active ? item.active : item.icon" style="width: 40px; height: 40px" />
        <text v-if="!active">{{ item.text }}</text>
    </template>
</sk-tab-bar>

字体图标

const list = ref<SkTabBarItem[]>([
    // icon/active 传字体图标 class，width 作为字号
    { text: '首页', iconType: 'font', icon: 'iconfont icon-home', active: 'iconfont icon-home-fill', width: '48rpx' }
])

主题定制

<sk-tab-bar
    :data="list"
    background="#1f1f1f"
    text-color="#999"
    active-text-color="#fff"
    icon-background-color="#07c160"
    outer-aperture-border-color="#141414"
    height="130rpx"
    :duration="300"
    placeholder
/>

形态（mode）与内凹实现流派

GitHub 上「凹陷弧形 tabBar」主要有三种实现流派：①伪类 + box-shadow、②CSS filter(blur+contrast)、③clip-path / 径向渐变切割。本组件采用①（concave），另以④画布自绘（canvas）补齐"任意背景 + 内凹观感"这一①②③都给不了的组合，并提供无内凹的 plain（② filter 融合为内部保留形态，暂不开放）；第③派（clip-path 真实镂空）经评估与 plain 观感过于接近，已移除。

canvas 模式限制

• 微信小程序需 canvas 2d（基础库 ≥2.9.0）；H5 / App-vue 通过 createSelectorQuery().fields({node:true}) 取节点。
• nvue 页面不支持（无 DOM canvas / SelectorQuery node）。
• 开发者工具模拟器不支持 canvas 同层渲染（画布恒盖在 view 之上，会遮住 tab 项，只剩选中图标从凹口透出），组件检测到 platform === 'devtools' 会自动降级为 plain 观感并 console.warn 提示，真机不受影响；canvas 形态的实际观感请以真机为准。
• background 在 canvas 模式下仅支持纯色（hex/rgb/rgba），传渐变字符串在小程序端会静默失败。
• 取节点失败 / 尺寸未就绪 / 绘制异常时自动降级为 plain 观感（实心栏），并 console.warn 提示，任何端都不会出现整条 tabBar 消失。
• 切换动画的缓动已对齐 __bump 的 CSS ease，避免深色钮与画布轮廓中途错位；窗口 resize / 旋转 / height、data 变化会自动重建重绘。
• 小程序真机需抽测：低端 Android 同层渲染是否盖层或吞点击、iOS 橡皮筋滚动、从二级页返回画布是否空白。开发者工具模拟器不代表真机。

页面背景为图片/渐变等复杂背景、又想要内凹观感时，推荐 mode="canvas"（真透明 + 内凹）；只想要极简则用 plain。三种形态在纯色 / 深色 / 渐变 / 图片背景下的直观对比见 demo 页 pages/tabBarDemo/filter。

API

Props

SkTabBarItem

Events

Slots

Methods（ref 调用）

从旧版本迁移

1.0.5 完全兼容旧版用法，以下 API 已标记废弃，建议迁移：

1.1.0 起组件默认形态为 concave（伪类光圈，需 outerApertureBorderColor 与页面背景同色），并新增可选形态 filter（blur+contrast 融合内凹，曲线更平滑）；页面背景为图片/渐变等无法与光圈同色的复杂背景时，可显式设 mode="plain"（实心栏、不依赖背景色）。若此前显式使用过某一形态，升级后请按需保留对应的 mode 传参；各形态取舍详见上文「形态（mode）与内凹实现流派」。