TabBar 标签栏

17:06

说明

底部导航栏，通过 list 配置各项的图标、文字、角标与凸起按钮（midButton），默认用 v-model 绑定当前索引。某项配置 pagePath 后点击改为 uni.switchTab 跳转，激活态按当前页面路由（getCurrentPages）判定、v-model 不再联动；可用 beforeSwitch 拦截切换。

兼容性

平台	支持情况
App	✅ 支持（`gap` 不生效，图标与文字间距为固定值）
H5	✅ 支持
微信小程序	✅ 支持

示例

选择演示场景

底部标签栏固定于屏幕底部，切换下方场景查看不同配置。

Example 2

API

Props

属性	说明	类型	默认值	版本
`show`	是否展示	`boolean`	`true`	-
`modelValue`	v-model 绑定值	`number`	`0`	-
`bgColor`	背景颜色	`string`	`''`	-
`height`	高度	`string`	`'50px'`	-
`iconSize`	图标大小	`string`	`DEFAULT_ICON_SIZE`	-
`midButtonSize`	中间按钮大小	`string`	`DEFAULT_MID_BUTTON_SIZE`	-
`activeColor`	激活颜色	`string`	`''`	-
`inactiveColor`	未激活颜色	`string`	`''`	-
`midButton`	是否显示中间凸起按钮	`boolean`	`false`	-
`list`	tab 列表	`TabbarItem[]`	`-`	-
`zIndex`	z-index	`string`	`''`	-
`beforeSwitch`	切换前回调	`(index: number) => boolean \| Promise<boolean>`	`-`	-
`borderTop`	是否显示顶部边框	`boolean`	`true`	-
`hideTabBar`	是否隐藏原生 tabbar	`boolean`	`true`	-
`gap`	图标和文字间距	`string`	`'2px'`	-
`textSize`	文字大小	`string`	`DEFAULT_TEXT_SIZE`	-
`customClass`	自定义类名	`string`	`''`	-
`customStyle`	自定义样式	`string`	`''`	-

Events

事件名	说明	回调参数	版本
`change`	点击 tab 时触发，回调为被点击的 tab 索引	`index: number`	-

Slots

ux-tabbar 无插槽。

注意事项

hide-tab-bar 默认 true，挂载时会调用 uni.hideTabBar()；在非 tabBar 页面（如演示页）使用会报 hideTabBar:fail not TabBar page，需显式传 hide-tab-bar="false"。
某项配置 pagePath 后，点击走 uni.switchTab 跳转，激活态按当前页面路由（getCurrentPages）判定，v-model 与 change 不再联动该项；未配置 pagePath 时才由 v-model 维护索引。
beforeSwitch 返回 false（或 Promise resolve false）会阻止本次切换。
凸起按钮需同时满足全局 mid-button 与该项 midButton: true。
gap 仅 H5 / 微信小程序生效，App 端图标与文字间距为固定值。