微信小程序自定义 tabBar

微信小程序的自定义 tabBar 功能可以让你摆脱默认样式的限制，打造更贴合小程序风格、更具交互性的底部导航栏。下面我将为你梳理实现自定义 tabBar 的要点、步骤、注意事项以及一些进阶技巧。

🛠️ 微信小程序自定义 tabBar 指南

✨ 核心优势与注意事项

自定义 tabBar 是指你可以用一个自定义组件来完全控制小程序底部导航栏的渲染和交互。这意味着你不再受限于原生 tabBar 的样式和功能，可以实现比如中间凸起的按钮、融入品牌特色的动效、更复杂的交互提示（如精细的红点计数）等。

实现自定义 tabBar 前，请注意以下几点：

基础库要求：确保小程序基础库版本在 2.5.0 及以上。
目录结构：必须在根目录创建名为 custom-tab-bar 的文件夹，并且其中的组件文件必须命名为 index（即 custom-tab-bar/index.js、custom-tab-bar/index.wxml 等）。
配置一致性：即使在自定义模式下，app.json 中 tabBar 的 list 数组仍需完整定义所有 tab 页，且自定义组件中 list 数组的数量和顺序必须与 app.json 中的 list 保持一致。
样式隔离：如果在自定义 tabBar 中使用了第三方 UI 库（如 Vant Weapp），可能需要通过在自定义组件的 .js 文件中设置 options: { styleIsolation: 'shared' } 来修改第三方组件的默认样式。

📝 实现步骤

1. 配置 app.json

在 app.json 的 tabBar 项中设置 "custom": true，并保留原有的 list 配置（用于定义 tab 页和低版本兼容）。

{"tabBar": {"custom": true,"list": [{"pagePath": "pages/index/index","text": "首页","iconPath": "images/tab-home.png","selectedIconPath": "images/tab-home-active.png"},{"pagePath": "pages/my/my","text": "我的","iconPath": "images/tab-my.png","selectedIconPath": "images/tab-my-active.png"}]},"usingComponents": {}
}

2. 创建自定义 tabBar 组件

在根目录创建 custom-tab-bar 文件夹及其下的 index.js, index.json, index.wxml, index.wxss 文件。

custom-tab-bar/index.json 中声明为自定义组件：

{"component": true,"usingComponents": {}
}

custom-tab-bar/index.wxml 中编写组件结构（示例使用了高斯模糊背景）：

<view class="tabbar"><block wx:for="{{list}}" wx:key="index"><view class="tabbar-item" data-path="{{item.pagePath}}" data-index="{{index}}" bindtap="switchTab"><image class="tabbar-item-image" src="{{selected === index ? item.selectedIconPath : item.iconPath}}"></image><text class="tabbar-item-text" style="{{selected === index ? 'color: ' + selectedColor : 'color: ' + color}}">{{item.text}}</text><!-- 徽标提示 --><view wx:if="{{item.info > 0}}" class="tabbar-badge">{{item.info > 99 ? '99+' : item.info}}</view><view wx:if="{{item.dot}}" class="tabbar-dot"></view></view></block>
</view>

custom-tab-bar/index.wxss 中定义样式（示例包含了高斯模糊和安全区适配）：

.tabbar {width: 100%;height: 100rpx; /* 一般高度 */display: flex;position: fixed;bottom: 0;backdrop-filter: blur(10px); /* 高斯模糊效果 */background-color: rgba(255, 255, 255, 0.9); /* 半透明背景 */z-index: 9999;padding-bottom: env(safe-area-inset-bottom); /* 适配异形屏（如iPhone X）底部安全区 */
}.tabbar-item {flex: 1;display: flex;flex-direction: column;justify-content: center;align-items: center;position: relative;
}.tabbar-item-image {width: 50rpx;height: 50rpx;
}.tabbar-item-text {font-size: 24rpx;margin-top: 4rpx;
}/* 徽标和红点的样式 */
.tabbar-badge {position: absolute;top: 6rpx;right: 33rpx;min-width: 28rpx;height: 28rpx;line-height: 28rpx;border-radius: 14rpx;background-color: #ff5c5c;color: #ffffff;font-size: 20rpx;text-align: center;padding: 0 8rpx;
}.tabbar-dot {position: absolute;top: 10rpx;right: 36rpx;width: 16rpx;height: 16rpx;border-radius: 50%;background-color: #ff5c5c;
}

custom-tab-bar/index.js 中定义组件逻辑：

const app = getApp()Component({data: {selected: 0, // 当前选中的 tab 索引color: "#7c7c7c", // 默认文字颜色selectedColor: "#33a3dc", // 选中时的文字颜色list: [ // 此处的 list 需与 app.json 中的 list 保持一致{pagePath: "/pages/index/index",iconPath: "/images/tab-home.png",selectedIconPath: "/images/tab-home-active.png",text: "首页",info: 0, // 数字徽章dot: false // 是否显示小红点},{pagePath: "/pages/my/my",iconPath: "/images/tab-my.png",selectedIconPath: "/images/tab-my-active.png",text: "我的",info: 0,dot: false}]},methods: {switchTab(e) {const dataset = e.currentTarget.datasetconst index = dataset.indexconst path = dataset.path// 切换 tabwx.switchTab({url: path,})// 更新选中状态this.setData({selected: index})}}
})

3. 在 Tab 页中更新选中状态

必须在每个 tab 页面对应的 .js 文件中的 onShow 生命周期函数里，通过 getTabBar 方法更新自定义 tabBar 的选中状态。

// pages/index/index.js 或 pages/my/my.js
const app = getApp()Page({onShow() {if (typeof this.getTabBar === 'function' && this.getTabBar()) {// 通过全局变量或页面路由判断当前索引// 假设全局变量 globalData.tabBarIndex 在切换时已更新this.getTabBar().setData({selected: app.globalData.tabBarIndex// 或者根据页面路径计算索引// selected: 计算出的索引值})}}
})

你可以通过在 app.js 的 globalData 中定义一个 tabBarIndex 并在切换 tab 时更新它，或者在每个页面的 onShow 中根据页面路由判断当前应选中的索引。

🚀 进阶使用技巧

特殊功能按钮：你可以在 tabBar 中放置非跳转页面的功能按钮，如“发布”按钮。这时，可以为该按钮设置一个特殊的 jumpType（如 navigateTo 或空），并在点击事件中做特殊判断，执行相应的功能（如调用扫码 API），注意为其配置一个空白页面路径。

// 在 switchTab 方法中
if (item.jumpType === 'function') {// 执行功能，如扫码wx.scanCode({success: (res) => {console.log(res)}})return // 阻止页面跳转
}

动态更新徽标：可以通过获取自定义 tabBar 组件实例，调用 setData 来动态更新某个 tab 的 info 或 dot 值。

// 在页面中更新购物车 tab 的数字
const tabBar = this.getTabBar()
if (tabBar) {tabBar.setData({'list[1].info': newCartCount // 更新第二个tab的徽标数字})
}

使用 UI 库：可以引入 Vant Weapp 等 UI 库来快速构建 tabBar。只需在 custom-tab-bar/index.json 中引入组件，并在 WXML 中使用即可，同时别忘记处理样式隔离问题。

// custom-tab-bar/index.json
{"component": true,"usingComponents": {"van-tabbar": "@vant/weapp/tabbar/index","van-tabbar-item": "@vant/weapp/tabbar-item/index"}
}

Skyline 渲染模式适配：如果你的小程序使用了 Skyline 渲染引擎，需要注意：

给 tabBar 根组件添加 pointer-events: auto 和 position: absolute 样式。
getTabBar 接口变为异步回调模式。

// Skyline 下获取 tabBar 实例
if (typeof this.getTabBar === 'function') {this.getTabBar((tabBar) => {tabBar.setData({ selected: 0 })})
}

⚠️ 常见问题与解决方案

下面是一些你可能遇到的问题及解决方法：

问题现象	可能原因	解决方案
自定义 tabBar 不显示或错位	1. `custom-tab-bar` 目录未在根目录或文件名错误 2. WXSS 中定位方式或高度问题 3. 未正确设置 `env(safe-area-inset-bottom)`	检查目录结构、检查样式设置、适配安全区
切换 Tab 后选中状态未更新	未在 tab 页的 `onShow` 生命周期中调用 `getTabBar().setData()`	在每个 tab 页的 `onShow` 中正确设置选中索引
图标显示为空白或路径错误	图片路径未使用绝对路径（以 `/` 开头）	确保 `iconPath` 和 `selectedIconPath` 为绝对路径
使用 Vant 等库样式不生效	自定义组件样式隔离	在组件 JS 中设置 `options: { styleIsolation: 'shared' }`
点击 tabBar 项无反应	`switchTab` 的 URL 与 `app.json` 中定义的 `pagePath` 不一致	确保 `switchTab` 的 URL 与 `app.json` 中 `list` 内的 `pagePath` 完全一致

💎 总结

自定义 tabBar 的核心步骤是：配置 app.json → 创建 custom-tab-bar 组件 → 在各 Tab 页的 onShow 中更新选中状态。实现的关键在于保持 app.json 与自定义组件中 list 配置的一致性，以及正确地在页面生命周期中处理选中态。