程序员scholar
  • 小程序开发
  • uniapp多端开发
  • 快速入门
scholar
2025-01-28
目录

配置底部导航栏(tabBar)

# 配置底部导航栏(tabBar)

# 一、什么是 TabBar

tabBar 是应用底部的导航栏，用于在多个页面之间快速切换。它通常位于应用程序界面的底部（或顶部，部分平台支持），展示多个可切换的页面入口。例如常见的“首页”、“分类”、“购物车”、“我的”这类底部导航。

在 uni-app 中，你只需要在 pages.json 中通过 tabBar 节点进行配置，就可以实现底部导航栏。系统会自动创建对应的导航按钮与选中/未选中的图标展示。

# 二、在 pages.json 中设置 tabBar

# 2.1 tabBar 配置入口

在 uni-app 项目的根目录下找到 pages.json 文件，打开后你会看到一个 JSON 结构，用于控制页面路由及页面特性。我们可以在同级节点中添加一个 tabBar 对象用于配置底部导航。

代码示例：





 





















{
  "pages": [
    // 其他页面配置 ...
  ],
  "tabBar": {
    "color": "#999999",             // 未选中时的文字颜色
    "selectedColor": "#ff0000",     // 选中时的文字颜色
    "backgroundColor": "#ffffff",   // tabBar 背景颜色
    "borderStyle": "black",         // tabBar 上边框颜色，可选 black / white
    "list": [
      {
        "pagePath": "pages/index/index", // 首页路径
        "text": "首页",                   // 首页 Tab 上显示的文字
        "iconPath": "static/images/home.png", // 首页未选中时的图标
        "selectedIconPath": "static/images/home_selected.png" // 首页选中时的图标
      },
      {
        "pagePath": "pages/about/about", // 关于页面路径
        "text": "关于",
        "iconPath": "static/images/about.png",
        "selectedIconPath": "static/images/about_selected.png"
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
  • 在上述示例中，我们配置了两个 tab，分别为“首页”和“关于我们”页面。每个 tab 都有未选中和选中时不同的图标和文字颜色。
  • 当你点击底部导航时，页面会在 pages/index/index 与 pages/about/about 之间切换，文字和图标也会随之改变颜色。

演示效果：当点击不同的 tab 时，会看到图标与文字的高亮切换。文字和图标颜色都会发生变化。

recording

# 2.2 tabBar 基础属性说明

以下为 tabBar 最常用的几个属性：

属性 类型 必填 默认值 描述 平台差异说明
color HexColor 是 -- 未选中时 tab 上文字的颜色
selectedColor HexColor 是 -- 选中时 tab 上文字的颜色
backgroundColor HexColor 是 -- tabBar 的背景色
borderStyle String 否 black tabBar 上边框的颜色，可选 black / white App 2.3.4+、H5 3.0.0+
list Array 是 -- tab 的列表信息，最少 2 个，最多 5 个，见下方说明
position String 否 bottom tabBar 的位置，支持 bottom / top 顶部仅微信小程序支持

提示

  1. 如果设置 position 为 top，则不会显示 icon。
  2. list 数组至少 2 个元素，最多 5 个，并按照数组顺序显示。
  3. 在小程序平台上切换 tabBar 页面时，由于页面在后台保留，只会触发 onShow 钩子，不会再次触发 onLoad。
  4. 如果希望每次切换时都执行特定逻辑，可以在 onShow 钩子中实现，而不是在 onLoad 中。
  5. 顶部 tabBar 目前仅微信小程序支持。其他平台暂不支持或仅以底部导航形式呈现。

# 2.3 list 属性说明

list 是一个数组，存储了各个 tab 的页面信息，每个对象都包含以下字段：

属性 类型 必填 说明
pagePath String 是 页面路径，必须在 pages 中定义（包含 pages.json 中声明的路径）
text String 是 tab 上的文字（App 和 H5 平台可以设置为空，但一般建议填写）
iconPath String 否 未选中时的图标路径，最大40KB，建议尺寸 81px * 81px，不支持网络图片
selectedIconPath String 否 选中时的图标路径，建议尺寸 81px * 81px

如果只配置了文字，而未配置图标，那么该 tab 只会显示文本。

# 三、配置底部中间按钮

除了常规的 list 数组，还可以通过 midButton 属性来实现中间按钮凸起等更炫酷的效果。目前该功能仅支持 App 和 H5 平台，并不支持小程序。如果你需要在小程序端也实现此效果，往往需要自定义 tabBar 来完成。

# 3.1 midButton 属性说明

midButton 用于配置一个位于底部导航正中间的特殊按钮，常见于一些社交或电商 App 的“+”号按钮。

属性 类型 必填 默认值 描述 平台差异说明
width String 否 80px 中间按钮的宽度，默认与其他 tab 项平分宽度 App 2.3.4+、H5 3.0.0+
height String 否 50px 中间按钮的高度，可以设置大于 tabBar 高度，形成凸起效果
text String 否 -- 中间按钮的文字
iconPath String 否 -- 中间按钮的图标路径
iconWidth String 否 24px 中间按钮图标的宽度，图片高度等比例缩放
backgroundImage String 否 -- 中间按钮的背景图片路径，比如一些圆形或半透明底图
iconfont Object 否 -- 字体图标配置，优先级高于 iconPath

# 3.2 midButton 案例

下面的案例演示了如何在 pages.json 中为 tabBar 添加中间按钮，并设置自定义图标大小、背景图、凸起高度等：

{
  "tabBar": {
    "color": "#999999",
    "selectedColor": "#ff0000",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/images/home.png",
        "selectedIconPath": "static/images/home_selected.png"
      },
      {
        "pagePath": "pages/about/about",
        "text": "关于",
        "iconPath": "static/images/about.png",
        "selectedIconPath": "static/images/about_selected.png"
      }
    ],
    "midButton": {
      "iconPath": "static/images/plus.png",          // 中间按钮的图标
      "iconWidth": "50px",                          // 图标宽度
      "height": "60px",                             // 按钮高度，可大于 tabBar 本身高度，形成凸起
      "backgroundImage": "static/images/mid_button_bg.png" // 中间按钮背景图
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 3.3 演示效果

当中间按钮高度大于其他 tab 的高度时，就能形成突出效果。如果再给它添加一个圆形背景图，则能实现更炫酷的视觉呈现：

个性化设置效果

中间按钮的图标在 tabBar 中凸显出来，看起来更有层次感。

个性化按钮效果
个性化按钮

小程序不支持

midButton 仅支持 App 和 H5 平台。若你想在小程序中使用中间按钮，可以选择隐藏原生 tabBar，然后自定义一个底部导航栏来实现凸起等更多特效。

# 四、在页面间切换

# 4.1 切换至 TabBar 页面

如果一个页面已配置在 tabBar 中，那么需要使用 uni.switchTab 来跳转，示例：

uni.switchTab({
  url: '/pages/index/index'  // 对应 tabBar 中的 pagePath
});
1
2
3
  • 不可以使用 uni.navigateTo 等方式来跳转 tabBar 页面，否则会在部分平台或小程序中报错或无法跳转。

# 4.2 切换至非 TabBar 页面

如果要从某个 tabBar 页面跳转到非 tabBar 页面，可以使用 uni.navigateTo、uni.redirectTo、uni.reLaunch 等跳转方式。具体选择可参考以下：

  1. uni.navigateTo：保留当前页面，创建新页面，可返回。
  2. uni.redirectTo：关闭当前页面，跳转到新页面，不能返回。
  3. uni.reLaunch：关闭所有页面，直接重启到新页面。
  4. uni.switchTab：专门用于跳转至 tabBar 配置的页面。

# 五、常见问题

  1. 图标尺寸和格式
    • iconPath 与 selectedIconPath 一般建议尺寸为 81x81，格式常用 .png 或 .jpg，最大 40KB。
    • 如果需要更清晰的图标，可使用矢量格式或 svg，但需要将其转换成 .png。
  2. 为何页面不触发 onLoad？
    • 当切换 tabBar 时，uni-app 会在后台保留上一个页面状态；因此只会执行 onShow，不会重新执行 onLoad。这与普通页面 navigateTo 不同。
  3. 不支持网络图片
    • 小程序平台对 tabBar 图标有较为严格的限制，iconPath / selectedIconPath 不支持网络图片，必须使用本地资源。
  4. 顶部导航栏（position=top）
    • 仅微信小程序支持 tabBar 在顶部显示，其他平台仍只会显示在底部。
    • 如需在多平台实现顶部导航，更常见的做法是自定义一个导航栏组件（或使用插件）。
  5. 平台差异：midButton
    • midButton 仅支持 App 和 H5 平台。
    • 如果要在小程序上做类“中间凸起”的功能，可以通过“自定义 tabBar”方案实现，这需要手动隐藏原生 tabBar，并自行在页面上布局按钮，监听点击事件后切换页面。
  6. 中间按钮点击事件
    • 原生的 midButton 无法直接绑跳转，需要手动在前端逻辑里监听中间按钮点击，然后通过 JS 代码执行跳转。
    • 例如在 App.vue 或底部导航的相应逻辑文件中，监听事件后调用 uni.navigateTo 或 uni.switchTab。
  7. 定制化需求
编辑此页 (opens new window)
创建新页面和页面路由跳转
文本和图标组件

← 文本和图标组件→

Theme by Vdoing | Copyright © 2019-2025 程序员scholar