基于uniapp的微信小程序自定义tabBar开发指南

作者：袖梨 2026-05-28

本文将详细介绍如何在uniapp vue3项目中实现微信小程序自定义tabBar功能，通过具体代码示例帮助开发者快速掌握核心配置要点。

配置 pages.json

首先需要在项目配置文件pages.json中进行tabBar的基础配置。以下是一个完整的配置示例，包含页面路径、图标设置和样式定义。

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/mine/index",
      "style": {
        "navigationBarTitleText": "我的"
      }
    },
    {
      "path": "pages/detail/index",
      "style": {
        "navigationBarTitleText": "详情"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "custom": true,
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/icon_component.png",
        "selectedIconPath": "static/icon_component_HL.png",
        "text": "首页"
      },
      {
        "pagePath": "pages/mine/index",
        "iconPath": "static/icon_API.png",
        "selectedIconPath": "static/icon_API_HL.png",
        "text": "我的"
      },
      {
        "pagePath": "pages/detail/index",
        "iconPath": "static/icon_API.png",
        "selectedIconPath": "static/icon_API_HL.png",
        "text": "详情"
      }
    ]
  }
}

添加 custom-tab-bar

在项目根目录创建custom-tab-bar文件夹，其中需要编写原生小程序组件。核心文件index.js包含tab切换逻辑和状态管理。

Component({
    data: {
        selected: 0,
        color: "#7A7E83",
        selectedColor: "#3cc51f",
        list: [{
            pagePath: "/pages/index/index",
            iconPath: "/static/icon_component.png",
            selectedIconPath: "/static/icon_component_HL.png",
            text: "组件"
        }, {
            pagePath: "/pages/mine/index",
            iconPath: "/static/icon_API.png",
            selectedIconPath: "/static/icon_API_HL.png",
            text: "接口"
        }, {
            pagePath: "/pages/detail/index",
            iconPath: "/static/icon_API.png",
            selectedIconPath: "/static/icon_API_HL.png",
            text: "详情"
        }]
    },
    attached() {},
    methods: {
        switchTab(e) {
            const data = e.currentTarget.dataset
            const url = data.path
            wx.switchTab({
                url
            })
            this.setData({
                selected: data.index
            })
        }
    }
})

特别注意：list数组中的配置必须与pages.json文件中的tabBar配置保持完全一致。

添加页面

以首页为例，展示如何在页面中控制tabBar的选中状态。通过生命周期钩子和tabBar实例方法实现状态同步。

<template>
  <view>
    <text>首页text>
  view>
template><script setup>
import { getCurrentInstance } from "vue";
import { onShow } from "@dcloudio/uni-app";const instance = getCurrentInstance();onShow(() => {
  const tabBar = instance?.proxy?.$scope?.getTabBar?.();
  if (tabBar) {
    // 这里的 `0` 对应具体的 tabbar 的下标
    tabBar.setData({
      selected: 0,
    });
  }
});
script>