tabBar

How to use the tab bar

In a multi-tab miniapp, you can add a tab bar at the bottom of the screen. Use the `tabBar` configuration item to define the appearance of the tab bar and the page that is displayed when a tab is selected.

tabBar configuration

Item configuration

Code example

The following code provides an example of a `tabBar` configuration:

{
  "tabBar": {
    "textColor": "#dddddd",
    "selectedColor": "#49a9ee",
    "backgroundColor": "#ffffff",
    "items": [
      {
        "pagePath": "pages/index/index",
        "name": "Homepage"      },
      {
        "pagePath": "pages/logs/logs",
        "name": "Logs"      }
    ]
  }
}

my.hideTabBar

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

Hides the tab bar. For more information, see the tabBar FAQ.

Code example

The following code provides an example of `my.hideTabBar`:

my.hideTabBar({
    animation: true
})

Input parameters

The input parameter is an Object. Its properties are as follows:

my.hideTabBarRedDot

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

Hides the red dot in the upper-right corner of a specific tab bar item. For more information, see the tabBar FAQ.

Example

Code example

The following code provides an example of `my.hideTabBarRedDot`:

my.hideTabBarRedDot({
  index: 0
})

Input parameters

The input parameter is an Object. Its properties are as follows:

my.removeTabBarBadge

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

Removes the text from the upper-right corner of a specific tab bar item. For more information, see the tabBar FAQ.

Example

Code example

The following code provides an example of `my.removeTabBarBadge`:

my.removeTabBarBadge({
  index: 0
})

Input parameters

An object with the following properties:

my.setTabBarBadge

Prerequisites: Base library 1.11.0 or later.

Adds text to the upper-right corner of a specific tab bar item. For example, you can use this feature to display the number of unread messages. For more information, see the tabBar FAQ.

Example

Code example

The following code provides an example of `my.setTabBarBadge`:

my.setTabBarBadge({
  index: 0,
  text: '42'
})

Input parameters

The input parameter is an Object. Its properties are as follows:

my.setTabBarItem

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

Dynamically sets the content of a specific tab bar item. For more information, see the tabBar FAQ.

Code example

The following code provides an example of `my.setTabBarItem`:

my.setTabBarItem({
    index: 0,
    text: 'text',
    iconPath: '/image/iconPath',
    selectedIconPath: '/image/selectedIconPath'
})

Input parameters

The type is Object and has the following properties:

my.setTabBarStyle

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

Dynamically sets the overall style of the tab bar, such as text color, background color, and border color. For more information, see the tabBar FAQ.

Code example

The following code provides an example of `my.setTabBarStyle`:

my.setTabBarStyle({
    color: '#FF0000',
    selectedColor: '#00FF00',
    backgroundColor: '#0000FF',
    borderStyle: 'white'
})

Input parameters

The data type is an object containing the following properties:

my.showTabBar

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

Shows the tab bar. For more information, see the tabBar FAQ.

Code example

The following code provides an example of `my.showTabBar`:

my.showTabBar({
    animation: true
})

Input parameters

The input parameter is an Object. Its properties are as follows:

my.showTabBarRedDot

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

Shows the red dot in the upper-right corner of a specific tab bar item. For more information, see the tabBar FAQ.

Code example

The following code provides an example of `my.showTabBarRedDot`:

my.showTabBarRedDot({
  index: 0
})

Input parameters

An object with the following properties:

onTabItemTap

Prerequisites: Base library 1.11.0 or later. For earlier versions, you must ensure compatibility.

This API is called when a user taps a tab. You can use this API to listen for tab bar tap events. For more information, see the tabBar FAQ.

Code example

The following code provides an example of `onTabItemTap`:

//.js
Page({
  onTabItemTap(item) {
    console.log(item.index)
    console.log(item.pagePath)
    console.log(item.text)
  }
})

tabBar FAQ

Feature support questions

• Q: Do tab bar pages support navigation with parameters?

  A: Yes, they do.

• Q: How do I listen for tab bar tap events?

  A: You can use the onTabItemTap API on the miniapp page.

• Q: Does the tab bar icon support the SVG format?

  A: No, it does not. Only the PNG, JPEG, JPG, and GIF formats are supported.

• Q: How do I set the style of a tab?

  A: You can set the style directly in the JSON file, as shown in the code example below, or by calling the my.setTabBarStyle API.

  "tabBar": {
    "textColor": "#404040",
    "selectedColor": "#108ee9",
    "backgroundColor": "#F5F5F9"
  }

Request exception questions

• Q: How do I fix the "Cannot read property ‘getCurrentPages’ of undefined" error that occurs when switching a tabBar? A: This error is caused by an incorrect tabBar path. Verify that the path is correct.

  A

• Q: Why is the tab bar not displayed after I navigate to a page?

  A: The bottom tab bar does not appear on pages that you navigate to using the my.navigateTo or my.redirectTo APIs. Additionally, ensure that the first page in the `tabBar` configuration is the home page.

• Q: Why don't tab bar pages support navigation with parameters?

  A: Tab bar pages do not support navigation with parameters. We recommend that you use the cache or global variables to pass parameters.

• Q: When a miniapp enters a tab bar page, how can I retrieve the path of the previous page?

  A: Before navigating away from a page, store its path in a global property. When you switch to a tab bar page, you can then retrieve the path of the previous page from that global property.

• Q: When I debug in the IDE, why are the `onShow` and `onLoad` lifecycle functions not executed when I switch tabs?

  A: The tabBar switching function is not triggered when you debug in an IDE, so it must be tested on a real device.