Uniapp自定义TabBar组件全封装实践与疑难问题解决方案

news2025/4/25 22:02:35

前言

在当前公司小程序项目中，我们遇到了一个具有挑战性的需求：根据不同用户身份动态展示差异化的底部导航栏（TabBar） 。这种多角色场景下的UI适配需求，在提升用户体验和实现精细化运营方面具有重要意义。

在技术调研阶段，我们发现Uniapp原生的TabBar组件虽然简单易用，但在动态配置、样式扩展以及多身份适配等方面存在明显局限。通过查阅大量技术文档和社区解决方案，我们最终决定采用完全自定义的方案来实现这一需求。

在组件封装过程中，我们遇到了包括渲染闪烁、路由同步、状态管理等一系列典型问题。本文不仅会分享最终的实现方案，还将详细总结开发过程中踩过的"坑"以及对应的解决方案，希望能为遇到类似需求的开发者提供有价值的参考。

本文内容涵盖：

多身份TabBar的架构设计思路
动态渲染的性能优化方案
实际开发中的典型问题及解决方法
针对不同业务场景的扩展建议

通过这次实践，我们不仅成功实现了业务需求，还沉淀出一套可复用的组件化方案，为后续类似需求的开发奠定了良好基础。

实现方案（本文采用第一种方案实现）

方案一：完全自定义TabBar组件

核心优势

高度兼容性：完美适配各类用户身份体系，不受原生组件限制
样式自由定制：支持复杂UI设计，可集成特殊交互功能（如浮动按钮、动画效果等）
动态响应：通过Vue响应式机制实时更新导航状态，实现无缝切换

技术实现

// 动态身份检测与TabBar渲染
computed: {
  currentTabConfig() {
    return this.tabConfigs[this.userInfo.role] || this.tabConfigs.default
  }
}

适用场景

多身份体系（≥3种角色类型）
需要复杂UI表现的场景
要求特殊交互功能的项目

方案二：原生TabBar动态配置方案

技术特点

代码简洁：基于uni.setTabBarItem API实现，改造量小
性能优势：直接使用原生组件，渲染效率更高
维护成本低：遵循官方标准实现方式

实现示例

// 根据身份动态更新TabBar
updateTabBarByRole(role) {
  const config = this.getRoleConfig(role)
  config.forEach((item, index) => {
    uni.setTabBarItem({
      index,
      text: item.text,
      iconPath: item.icon,
      selectedIconPath: item.activeIcon
    })
  })
}

局限性

数量差异处理复杂：当不同身份Tab项数量不等时，需配合uni.removeTabBarItem进行动态增减
样式限制：无法突破原生组件的样式约束
身份兼容性：在多身份复杂场景下维护成本较高

核心实现逻辑详解

1. 在page.json文件的tabbar属性中添加custom属性，设置为true隐藏原生tabbar

"tabBar": {
		"custom": true,  // 自定义tabbar只对小程序生效
		"list": .... // 注意list需要写入初始身份tabbar，不然切换tabbar会有问题
	},

2. 在根目录中新建一个文件夹，叫做 components，存放公共组件

不完成文件夹结构

|- pages
|- components

3. 需要在store文件夹中定义一个tabbarIndex变量作为当前tabbar索引

注意！注意！注意！需要在store中定义tabbar的索引否则会有页面和组件渲染机制问题，会导致点击后的tabbar icon没有高亮。

import Vue from "vue";
import Vuex from "vuex";

Vue.use(Vuex); //vue插件机制

const store = new Vuex.Store({
  state: {
    tabbarIndex: 0,
  },
  mutations: {
    setTabIndex(tabIndex) {
      store.state.tabbarIndex = tabIndex;
    },
  },
});

export default store;

4. 在components文件夹中新增tabbar.vue文件

完整代码

<template>
	<view class="tab-bar">
		<view v-for="(item,index) in list" :key="index" class="tab-bar-item" @click="switchTab(item, index)">
			<image class="tab_img" :src="currentIndex == index ? item.selectedIconPath : item.iconPath"></image>
			<view class="tab_text" :style="{color: currentIndex == index ? selectedColor : color}">{{item.text}}</view>
		</view>
	</view>
</template>

<script>
	import store from '../../store'
	export default {
		computed: {
			currentIndex() {
				return store.state.tabbarIndex
			}
		},
		data() {
			return {
				color: "#666666",
				selectedColor: "#ff6600",
				list: [],
				activeIndex: 0
			}
		},
		created() {
			var _this = this

			if (true) {
				// 身份1
				_this.list = [] // ...
			} else {
				// 身份2
				_this.list = [] // ...
			}
		},
		methods: {
			switchTab(item, index) {
				this.activeIndex = index
				store.state.tabbarIndex = index
				let url = item.pagePath;
				uni.switchTab({
					url: url,
				})
			}
		}
	}
</script>

<style lang="scss">
	.tab-bar {
		position: fixed;
		bottom: 0;
		left: 0;
		right: 0;
		height: 100rpx;
		background: white;
		display: flex;
		justify-content: center;
		align-items: center;
		padding-bottom: env(safe-area-inset-bottom); // 适配iphoneX的底部

		.tab-bar-item {
			flex: 1;
			text-align: center;
			display: flex;
			justify-content: center;
			align-items: center;
			flex-direction: column;

			.tab_img {
				width: 37rpx;
				height: 41rpx;
			}

			.tab_text {
				font-size: 20rpx;
				margin-top: 9rpx;
			}
		}
	}
</style>

5. 在main.js中全局注册tabbar组件

import tabBar from "components/tabbar/index.vue"

Vue.component('tabBar',tabBar)

这里仅演示 home 页面的引入

6. 去每个 tabbar 页面（tabbar 页面就是在 tabbar.vue 组件中list配置的那些页面）

这里仅演示 home 页面的引入

<template> 
    <view class="home">
        <!-- 业务代码 -->
        <!-- 业务代码 -->
        
        <!-- tabbar 组件 -->
        <tab-bar /> 
    </view>
 </template>

效果图

身份1

在这里插入图片描述

身份2

在这里插入图片描述

`避雷区！！！`

1. 初始化编译小程序后出现闪烁问题

检查page.json文件中tabbar中的custom属性是否添加并且设置为true

"tabBar": {
		"custom": true,  // 自定义tabbar只对小程序生效
	},

2. 正序点击tabbar的icon路径和高亮正常效果，逆序点击会出现路径和高亮icon不一致情况

注意！注意！注意！需要在store中定义tabbar的索引否则会有页面和组件渲染机制问题，会导致点击后的tabbar icon没有高亮。

import Vue from "vue";
import Vuex from "vuex";

Vue.use(Vuex); //vue插件机制

const store = new Vuex.Store({
  state: {
    tabbarIndex: 0,
  },
  mutations: {
    setTabIndex(tabIndex) {
      store.state.tabbarIndex = tabIndex;
    },
  },
});

export default store;

tabbar.vue文件中使用computed计算属性获取tabbarIndex索引, 并且点击tabbar触发跳转事件给全局tabbarIndex赋值

<script>
	import store from '../../store'
	export default {
		computed: {
			currentIndex() {
				return store.state.tabbarIndex
			}
		},
		methods: {
			switchTab(item, index) {
				this.activeIndex = index
				store.state.tabbarIndex = index
				let url = item.pagePath;
				uni.switchTab({
					url: url,
				})
			}
		}
	}
</script>