uni-app 之 设置 tabBar

tabBar 是移动应用中常见的导航模式，uni-app 提供了丰富的 API 来动态控制 tabBar 的外观和行为。

1. uni.setTabBarItem(object)

动态设置 tabBar 某一项的内容

参数说明

属性	类型	默认值	必填	说明
index	number		是	tabBar 的哪一项，从左边算起
text	string		否	tab 上的按钮文字
iconPath	string		否	图片路径，icon 大小限制为 40kb
selectedIconPath	string		否	选中时的图片路径，icon 大小限制为 40kb
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

uni.setTabBarItem({
  index: 0,
  text: "首页",
  iconPath: "/static/icon/home.png",
  selectedIconPath: "/static/icon/home-active.png",
});

2. uni.setTabBarStyle(object)

动态设置 tabBar 的整体样式

参数说明

属性	类型	默认值	必填	说明
color	string		否	tab 上的文字默认颜色
selectedColor	string		否	tab 上的文字选中时的颜色
backgroundColor	string		否	tab 的背景色
borderStyle	string		否	tabBar 上边框的颜色，仅支持 black/white
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

uni.setTabBarStyle({
  color: "#7A7E83",
  selectedColor: "#007AFF",
  backgroundColor: "#F8F8F8",
  borderStyle: "black",
});

3. uni.hideTabBar(object)

隐藏 tabBar

参数说明

属性	类型	默认值	必填	说明
animation	boolean	false	否	是否需要动画效果
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

// 隐藏 tabBar，带动画效果
uni.hideTabBar({
  animation: true,
});

4. uni.showTabBar(object)

显示 tabBar

参数说明

属性	类型	默认值	必填	说明
animation	boolean	false	否	是否需要动画效果
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

// 显示 tabBar，带动画效果
uni.showTabBar({
  animation: true,
});

5. uni.setTabBarBadge(object)

为 tabBar 某一项右上角添加文本

参数说明

属性	类型	默认值	必填	说明
index	number		是	tabBar 的哪一项，从左边算起
text	string		是	显示的文本，超过 4 个字符则显示为 ...
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

// 为第一个 tab 添加 badge
uni.setTabBarBadge({
  index: 0,
  text: "3",
});

6. uni.removeTabBarBadge(object)

移除 tabBar 某一项右上角的文本

参数说明

属性	类型	默认值	必填	说明
index	number		是	tabBar 的哪一项，从左边算起
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

// 移除第一个 tab 的 badge
uni.removeTabBarBadge({
  index: 0,
});

7. uni.showTabBarRedDot(object)

显示 tabBar 某一项的右上角红点

参数说明

属性	类型	默认值	必填	说明
index	number		是	tabBar 的哪一项，从左边算起
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

// 显示第一个 tab 的红点
uni.showTabBarRedDot({
  index: 0,
});

8. uni.hideTabBarRedDot(object)

隐藏 tabBar 某一项的右上角红点

参数说明

属性	类型	默认值	必填	说明
index	number		是	tabBar 的哪一项，从左边算起
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数

示例代码

// 隐藏第一个 tab 的红点
uni.hideTabBarRedDot({
  index: 0,
});

完整示例

export default {
  methods: {
    // 初始化 tabBar 样式
    initTabBar() {
      // 设置 tabBar 整体样式
      uni.setTabBarStyle({
        color: "#7A7E83",
        selectedColor: "#007AFF",
        backgroundColor: "#FFFFFF",
        borderStyle: "black",
      });

      // 设置各 tab 项
      uni.setTabBarItem({
        index: 0,
        text: "首页",
        iconPath: "/static/tabbar/home.png",
        selectedIconPath: "/static/tabbar/home-selected.png",
      });

      uni.setTabBarItem({
        index: 1,
        text: "分类",
        iconPath: "/static/tabbar/category.png",
        selectedIconPath: "/static/tabbar/category-selected.png",
      });

      uni.setTabBarItem({
        index: 2,
        text: "购物车",
        iconPath: "/static/tabbar/cart.png",
        selectedIconPath: "/static/tabbar/cart-selected.png",
      });

      uni.setTabBarItem({
        index: 3,
        text: "我的",
        iconPath: "/static/tabbar/user.png",
        selectedIconPath: "/static/tabbar/user-selected.png",
      });
    },

    // 更新购物车数量显示
    updateCartBadge(count) {
      if (count > 0) {
        uni.setTabBarBadge({
          index: 2,
          text: count.toString(),
        });
      } else {
        uni.removeTabBarBadge({
          index: 2,
        });
      }
    },

    // 显示消息红点
    showMessageDot(show) {
      if (show) {
        uni.showTabBarRedDot({
          index: 3,
        });
      } else {
        uni.hideTabBarRedDot({
          index: 3,
        });
      }
    },

    // 在特定页面隐藏 tabBar
    hideTabBarInPage() {
      uni.hideTabBar({
        animation: true,
      });
    },

    // 返回页面时显示 tabBar
    showTabBarInPage() {
      uni.showTabBar({
        animation: true,
      });
    },
  },

  mounted() {
    this.initTabBar();
  },
};

注意事项

1. 所有 tabBar 相关 API 都需要在 tabBar 已经初始化完成后再调用
2. iconPath 和 selectedIconPath 必须使用本地资源路径
3. badge 文本超过 4 个字符会显示为 ...
4. 红点和 badge 不能同时显示在同一项上
5. 在不同平台上的表现可能会有细微差异
6. 修改 tabBar 样式时建议在应用启动时进行，避免频繁修改影响性能