更新记录

1.2.0（2026-11-10） 下载此版本

修复 Vue3 下的兼容问题

修复

• v-model 增加 Vue3 契约：新增 modelValue 属性，同时派发 update:modelValue，Vue2（value / input）与 Vue3 双端可用
• 子项 itemIndex 改为读取容器注册顺序，不再依赖 Vue2 的 $slots.default VNode 数组（Vue3 下所有项索引恒为 0，导致未写 name 时选中态错乱）
• 子项 hasIconSlot / hasDefaultSlot 同时兼容 $slots.x 为数组（Vue2）与函数（Vue3）的两种形态，插槽此前在 Vue3 下永远判定为空
• 子项补齐 beforeUnmount 卸载钩子（原仅 beforeDestroy，Vue3 下不注销，items 泄漏）
• 子项图标 / 默认插槽节点改为始终渲染，小程序端 $slots 探测不到时不再整块丢弃插槽内容；无图标时不再保留 4rpx 间距
• 小程序端补 multipleSlots: true，支持 icon + 默认两个具名插槽

平台兼容性

uni-app(3.8.10)

o-tabbar

底部导航栏组件，由容器 o-tabbar 与子项 o-tabbar-item 组成。

适合自定义 tabBar、页面内二级切换、底部快捷入口等场景。图标复用库内 o-icon 内置字体（332 个图标），无需额外引入 iconfont。

特性

• v-model 双向绑定当前选中项，未传值时默认选中第一项
• 图标支持 o-icon 图标名（如 home）与图片地址，未选中 / 选中可分别指定
• 角标 badge（数字超上限自动显示 99+）、小红点 dot、单项 / 整组禁用
• 默认固定底部，自动生成等高空位（页面内容不被遮挡）并适配 iPhone 底部安全区
• 配色整组下发（bg-color / color / active-color），子项可单独覆盖
• 子项支持 url 跳转，tabBar 页自动走 switchTab，其余走 navigateTo
• icon 作用域插槽，可完全自定义图标（插槽参数 active 表示是否选中）

基本用法

<o-tabbar v-model="active" @change="onChange">
    <o-tabbar-item name="home" text="首页" icon="home" icon-ac="home-filled" />
    <o-tabbar-item name="shop" text="商城" icon="shop" icon-ac="shop-filled" />
    <o-tabbar-item name="cart" text="购物车" icon="cart" icon-ac="cart-filled" />
    <o-tabbar-item name="user" text="我的" icon="user" icon-ac="user-filled" />
</o-tabbar>

export default {
    data() {
        return { active: 'home' }
    },
    methods: {
        onChange(name) {
            console.log('选中：', name)
        }
    }
}

子项未设置 name 时，按默认插槽顺序取索引（从 0 开始），此时 v-model 绑定的值也是索引。

文字与图片图标

<!-- 纯文字：不传 icon -->
<o-tabbar v-model="active">
    <o-tabbar-item name="all" text="全部" />
    <o-tabbar-item name="todo" text="待付款" />
</o-tabbar>

<!-- 图片图标：地址含 . 或 / 时按图片渲染 -->
<o-tabbar v-model="active">
    <o-tabbar-item name="home" text="首页" icon="/static/icon.png" icon-ac="/static/icon_ac.png" />
    <o-tabbar-item name="me" text="我的" icon="/static/me.png" icon-ac="/static/me_ac.png" />
</o-tabbar>

也可以在子项里用默认插槽写文字，等价于 text：

<o-tabbar-item name="home" icon="home">首页</o-tabbar-item>

角标

<o-tabbar v-model="active">
    <o-tabbar-item name="msg" text="消息" icon="chat-bubble" icon-ac="chat-bubble-filled" :badge="128" />
    <o-tabbar-item name="cart" text="购物车" icon="cart" icon-ac="cart-filled" badge="new" badge-color="#409EFF" />
    <o-tabbar-item name="user" text="我的" icon="user" icon-ac="user-filled" dot />
</o-tabbar>

• badge 为纯数字且大于 badge-max（默认 99）时显示 99+
• dot（小红点）与 badge 同时存在时，dot 优先

配色

<!-- 深色 tabbar -->
<o-tabbar v-model="active" bg-color="#1f2329" color="#8f959e" active-color="#ffffff" :border="false">
    <o-tabbar-item name="home" text="首页" icon="home" icon-ac="home-filled" />
    <o-tabbar-item name="shop" text="商城" icon="shop" icon-ac="shop-filled" />
</o-tabbar>

图标颜色跟随文字色（currentColor），实心 / 线性图标都会自动适配，无需单独设置。

禁用

<!-- 单项禁用 -->
<o-tabbar-item name="shop" text="商城" icon="shop" disabled />

<!-- 整组禁用 -->
<o-tabbar v-model="active" disabled> ... </o-tabbar>

固定与安全区

默认 fixed + placeholder + safe-area 全开：组件固定在视口底部，同时在原位置生成一个「高度 + 安全区内边距」的占位块，页面滚动到底时内容不会被导航栏遮挡。

<!-- 嵌在卡片、弹层等局部区域演示时，关掉固定与占位 -->
<o-tabbar v-model="active" :fixed="false" :safe-area="false"> ... </o-tabbar>

自定义图标插槽

用 icon 具名插槽完全自定义图标，选中态跟随 v-model 的值联动（三端一致）：

<o-tabbar v-model="active">
    <o-tabbar-item name="a" text="方形">
        <template #icon>
            <view class="dot" :class="{ 'dot--on': active === 'a' }" />
        </template>
    </o-tabbar-item>
    <o-tabbar-item name="b" text="圆形">
        <template #icon>
            <view class="dot dot--round" :class="{ 'dot--on': active === 'b' }" />
        </template>
    </o-tabbar-item>
</o-tabbar>

组件同时支持作用域插槽写法 <template #icon="{ active }">（H5 / App 可用，微信小程序端插槽作用域能力受限，建议用上面的 v-model 联动方式）。

v-model 兼容

o-tabbar 同时派发 input（Vue2）与 update:modelValue（Vue3）事件，v-model 在 Vue2 / Vue3 下都能正常工作：

<!-- Vue2 / Vue3 写法一致 -->
<o-tabbar v-model="active"> ... </o-tabbar>

<!-- 也可以手动监听 -->
<o-tabbar :value="active" @input="v => active = v" @change="onChange"> ... </o-tabbar>

oTabbar Props

oTabbarItem Props

Events

Slots

平台说明

• 小程序端使用 styleIsolation: 'apply-shared'，页面工具类可作用到组件内部
• 固定定位基于视口，若祖先节点使用了 transform / filter，position: fixed 会相对该祖先定位，此时请改用 :fixed="false" 自行控制布局
• 底部安全区使用 env(safe-area-inset-bottom)，不支持的端自动降级为 0