全部产品

tabBar

更新时间:2020-07-07 19:42:04

tabBar 使用说明

多 tab 小程序(小程序的底部栏可以切换页面)可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。

说明
  • 通过页面跳转(my.navigateTo)或者页面重定向(my.redirectTo)所到达的页面,即使它是定义在 tabBar 配置中的页面,也不会显示底部的 tab 栏。
  • tabBar 的第一个页面必须是首页。

tabBar 配置

属性 类型 必填 描述
textColor HexColor 文字颜色。
selectedColor HexColor 选中文字颜色。
backgroundColor HexColor 背景色。
items Array 每个 tab 的配置。单个 item 的配置属性见下表。

item 配置

属性 类型 必填 描述
pagePath String 设置页面路径。
name String 名称。
icon String 平常图标路径。icon 推荐图片尺寸为 60×60px ,系统会对任意传入的图片非等比拉伸/缩放。
activeIcon String 高亮图标路径。

代码示例

  1. {
  2. "tabBar": {
  3. "textColor": "#dddddd",
  4. "selectedColor": "#49a9ee",
  5. "backgroundColor": "#ffffff",
  6. "items": [
  7. {
  8. "pagePath": "pages/index/index",
  9. "name": "首页" },
  10. {
  11. "pagePath": "pages/logs/logs",
  12. "name": "日志" }
  13. ]
  14. }
  15. }

my.hideTabBar

版本要求:基础库版本 1.11.0 或更高版本,低版本需要做 兼容处理

该接口用于隐藏标签页(tabbar)。
相关问题请参见 tabBar 常见问题

代码示例

  1. my.hideTabBar({
  2. animation: true
  3. })

入参

入参为 Object 类型,属性如下:

属性 类型 必填 说明
animation Boolean 是否需要动画效果,默认无。
success Function 接口调用成功的回调函数。
fail Function 接口调用失败的回调函数。
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)。

my.hideTabBarRedDot

版本要求:基础库 1.11.0 或更高版本,若版本较低,建议做 兼容处理
注意:IDE 暂不支持模拟,请以真机调试效果为准。

该接口用于隐藏标签页(tabbar)某一项右上角的红点。
相关问题请参见 tabBar 常见问题

效果示例

代码示例

  1. my.hideTabBarRedDot({
  2. index: 0
  3. })

入参

Object 类型,属性如下:

属性 类型 必填 说明
index Number 标签页的项数序号,从左边计数。
success Function 接口调用成功的回调函数。
fail Function 接口调用失败的回调函数。
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)。

my.removeTabBarBadge

版本要求:基础库 1.11.0 或更高版本,若版本较低,建议做 兼容处理
注意:IDE 暂不支持模拟,请以真机调试效果为准。

该接口用于移除标签页(tabbar) 某一项右上角的文本。
相关问题请参见 tabBar 常见问题

效果示例

代码示例

  1. my.removeTabBarBadge({
  2. index: 0
  3. })

入参

Object 类型,属性如下:

属性 类型 必填 说明
index Number 标签页的项数序号,从左边开始计数。
success Function 接口调用成功的回调函数。
fail Function 接口调用失败的回调函数。
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)。

my.setTabBarBadge

版本要求:基础库 1.11.0 及以上版本。
注意:IDE 暂不支持模拟,请以真机调试效果为准。

该接口用于为标签页(tabbar)某一项的右上角添加文本。可用于设置消息条数的红点提醒。
相关问题请参见 tabBar 常见问题

效果示例

代码示例

  1. my.setTabBarBadge({
  2. index: 0,
  3. text: '42'
  4. })

入参

Object 类型,属性如下:

属性 类型 必填 描述
index Number 标签页的项数序号,从左边开始计数。
text String 显示的文本,超过三个字符则显示成前两个字符+“…”,例如:“支付宝”显示“支付宝”,“蚂蚁金服”显示“蚂蚁…”。
success Function 接口调用成功的回调函数。
fail Function 接口调用失败的回调函数。
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)。

my.setTabBarItem

版本要求:基础库 1.11.0 或更高版本,若版本较低,建议做 兼容处理
注意:IDE 暂不支持模拟,请以真机调试效果为准。

该接口用于动态设置标签页(tabbar)某一项的内容。
相关问题请参见 tabBar 常见问题

代码示例

  1. my.setTabBarItem({
  2. index: 0,
  3. text: 'text',
  4. iconPath: '/image/iconPath',
  5. selectedIconPath: '/image/selectedIconPath'
  6. })

入参

Object 类型,属性如下:

属性 类型 必填 说明
index Number 标签页的项数序号,从左边开始计数。
text String 标签页按钮上的文字。
iconPath String 图片路径,建议尺寸为 81px * 81px,支持 png/jpeg/jpg/gif 图片格式,支持网络图片。
selectedIconPath String 选中时的图片路径,建议尺寸为 81px * 81px,支持 png/jpeg/jpg/gif 图片格式,支持网络图片。
success Function 接口调用成功的回调函数。
fail Function 接口调用失败的回调函数。
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)。

my.setTabBarStyle

版本要求:基础库 1.11.0 或更高版本,若版本较低,建议做 兼容处理
注意:IDE 暂不支持模拟,请以真机调试效果为准。

该接口用于动态设置标签页(tabbar)的整体样式,如文字颜色、标签背景色、标签边框颜色等。
相关问题请参见 tabBar 常见问题

代码示例

  1. my.setTabBarStyle({
  2. color: '#FF0000',
  3. selectedColor: '#00FF00',
  4. backgroundColor: '#0000FF',
  5. borderStyle: 'white'
  6. })

入参

Object 类型,属性如下:

属性 类型 必填 说明
color HexColor 标签(tab)上的文字默认颜色
selectedColor HexColor 标签(tab)上的文字选中时的颜色
backgroundColor HexColor 标签(tab)的背景色
borderStyle String 标签页(tabbar)上边框的颜色, 仅支持 blackwhite
success Function 接口调用成功的回调函数。
fail Function 接口调用失败的回调函数。
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)。

my.showTabBar

版本要求:基础库 1.11.0 或更高版本,若版本较低,建议做 兼容处理

该接口用于显示标签页(tabbar)。
相关问题请参见 tabBar 常见问题

代码示例

  1. my.showTabBar({
  2. animation: true
  3. })

入参

Object 类型,属性如下:

属性 类型 必填 说明
animation Boolean 是否需要动画效果,默认无。
success Function 接口调用成功的回调函数。
fail Function 接口调用失败的回调函数。
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)。

my.showTabBarRedDot

版本要求:基础库 1.11.0 或更高版本,若版本较低,建议做 兼容处理
注意:IDE 暂不支持模拟,请以真机调试效果为准。

该接口用于显示标签页(tabbar)某一项的右上角的红点。
相关问题请参见 tabBar 常见问题

代码示例

  1. my.showTabBarRedDot({
  2. index: 0
  3. })

入参

Object 类型,属性如下:

属性 类型 必填 说明
index Number 标签页的项数序号,从左边开始计数。
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

onTabItemTap

版本要求:基础库 1.11.0 或更高版本,若版本较低,建议做 兼容处理

该接口用于点击标签(tab)时触发,可用于监听 tabBar 点击事件。
相关问题请参见 tabBar 常见问题

代码示例

  1. //.js
  2. Page({
  3. onTabItemTap(item) {
  4. console.log(item.index)
  5. console.log(item.pagePath)
  6. console.log(item.text)
  7. }
  8. })

tabBar 常见问题

功能支持类问题

  • Q:tabBar 页面是否支持带参数跳转?
    A:支持。

  • Q:如何监听 tabBar 点击事件?
    A:在小程序页面中用 onTabItemTap 即可监听 tabBar 点击事件。

  • Q:tabBar 的 icon 图标是否支持 svg 格式?
    A:不支持 svg 格式,只支持 png/jpeg/jpg/gif 图片格式。

  • Q:如何设置 tab 的样式?
    A:可以在 JSON 文件中直接设置样式(代码示例如下所示),或者调用 my.setTabBarStyle API 进行设置。

  1. "tabBar": {
  2. "textColor": "#404040",
  3. "selectedColor": "#108ee9",
  4. "backgroundColor": "#F5F5F9"
  5. }

请求异常类问题

  • Q:切换 tabBar 时报错“Cannot read property ‘getCurrentPages’ of undefined”,如何处理?
    A:tabBar 路径错误导致,请检查 tabBar 路径。

  • Q:跳转页面后,为何不显示 tabBar?
    A:通过页面跳转(my.navigateTo)或者页面重定向(my.redirectTo)所到达的页面,不会显示底部的 tab 栏。另外,tabBar 的第一个页面必须是首页。

  • Q:tabBar 页面不支持带参数跳转吗?
    A:tabBar 页面目前不支持带参数跳转,建议跳转传参使用缓存或者全局变量。

  • Q:小程序进入 tabBar 页面,如何获取上一级页面路径?
    A:在进入页面的时候将当前页面路径存入全局,在切换 tabBar 页面的时候拿全局的地址属性即可获取上一级页面路径。

  • Q:在 IDE 中调试,为何 tabBar 切换时 onshow、onload 生命周期函数不执行?
    A:tabBar 切换需要在真机上测试,IDE 中调试时不触发。