tabBar - Mobile Platform as a Service - Alibaba Cloud Documentation Center

tabBar usage

For a mini program that has multiple pages, you can configure tabBar and the corresponding pages. tabBar is used to switch among the pages.

Note:

If a page appears after the my.navigateTo or my.redirectTo operation is performed, tabBar does not appear at the bottom even if the page is defined in tabBar.
The default page of tabBar must be the homepage of the mini program.

Configurations of tabBar

Attribute	Type	Required	Description
textColor	HexColor	No	The text color of a tab icon when the icon is not selected.
selectedColor	HexColor	No	The text color of a tab icon when the icon is selected.
backgroundColor	HexColor	No	The background color.
items	Array	No	The configurations of each tab in tabBar. The following table describes the detailed configurations of each tab.

Sub parameters of items

Attribute	Type	Required	Description
pagePath	String	Yes	The URL of the page that corresponds to the tab.
name	String	Yes	The name of the tab.
icon	String	No	The URL of the tab icon when the corresponding page is not displayed. We recommend that you choose an image of 60 × 60 pixels. Images of other sizes will automatically be adjusted to this size in a non-proportional manner.
activeIcon	String	No	The URL of the highlighted tab icon when the corresponding page is displayed.

Sample code

The following is the sample code of tabBar:

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

my.hideTabBar

Version requirement: Base library V1.11.0 or later versions. For earlier versions, you must first handle the incompatibility. For more information, see Compatibility processing.

This interface allows you to hide tabBar. If you have any problems, see FAQ.

Sample code

The following is the sample code of my.hideTabBar:

my.hideTabBar({
    animation: true
})

Parameters

The input parameters are in Object type and have the following attributes:

Parameter	Type	Required	Description
animation	Boolean	No	Specifies whether to enable animation. Default value: No.
success	Function	No	The callback method that indicates a successful call.
fail	Function	No	The callback method that indicates a failed call.
complete	Function	No	The callback method that indicates the call is completed (this will be executed regardless of whether the call succeeds or fails).

my.hideTabBarRedDot

Version requirement: Base library V1.11.0 or later versions. For earlier versions, you must first handle the incompatibility. For more information, see Compatibility processing.

Note: IDEs do not support commissioning. Use a physical device for commissioning.

This interface allows you to hide the red dot in the upper-right corner of a tab icon in tabBar. If you have any problems, see FAQ.

Effect

Sample code

The following is the sample code of my.hideTabBarRedDot:

my.hideTabBarRedDot({
  index: 0
})

Parameters

The parameters are in object type and have the following properties:

Parameter	Type	Required	Description
index	Number	Required	The serial number of the tab icon, counting from the left.
success	Function	No	The callback method that indicates a successful call.
fail	Function	No	The callback method that indicates a failed call.
complete	Function	No	The callback method that indicates the call is completed (this will be executed regardless of whether the call succeeds or fails).

my.removeTabBarBadge

Version requirement: Base library V1.11.0 or later versions. For earlier versions, you must first handle the incompatibility. For more information, see Compatibility processing.
Note: IDEs do not support commissioning. Use a physical device for commissioning.

This interface allows you to remove the text from the upper-right corner of a tab icon. If you have any problems, see FAQ.

Effect

Sample code

The following is the sample code of my.removeTabBarBadge:

my.removeTabBarBadge({
  index: 0
})

Parameters

The parameters are in object type and have the following properties:

Parameter	Type	Required	Description
index	Number	Required	The serial number of the tab icon, counting from the left.
success	Function	No	The callback method that indicates a successful call.
fail	Function	No	The callback method that indicates a failed call.
complete	Function	No	The callback method that indicates the call is completed (this will be executed regardless of whether the call succeeds or fails).

my.setTabBarBadge

Version requirement: Base library V1.11.0 or later versions.
Note: IDEs do not support commissioning. Use a physical device for commissioning.

This interface allows you to add a badge to the upper-right corner of a tab icon. You can use red dot reminder to set the number of messages. If you have any problems, see FAQ.

Effect

Sample code

The following is the sample code of my.setTabBarBadge:

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

Parameters

The parameters are in object type and have the following properties:

Parameter	Type	Required	Description
index	Number	Required	The serial number of the tab icon, counting from the left.
text	String	Required	The text to display. If the text exceeds four characters, the text is displayed as the first four characters + “…”. For example, if the text is “Ant Group”, the text is displayed as “Ant …”.
success	Function	No	The callback method that indicates a successful call.
fail	Function	No	The callback method that indicates a failed call.
complete	Function	No	The callback method that indicates the call is completed (this will be executed regardless of whether the call succeeds or fails).

my.setTabBarItem

This interface allows you to dynamically set the text of a tab icon in tabBar. If you have any problems, see FAQ.

Sample code

The following is the sample code of my.setTabBarItem:

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

Parameters

The parameters are in object type and have the following properties:

Parameter	Type	Required	Description
index	Number	Required	The serial number of the tab icon, counting from the left.
text	String	Required	The text on the tab icon.
iconPath	String	Required	The URL of the tab icon when the corresponding page is not displayed. We recommend that you choose an image of 81 × 81 pixels in the PNG, JPEG, JPG. or GIF format. Images from the Internet are supported.
selectedIconPath	String	Required	The URL of the tab icon when the corresponding page is displayed. We recommend that you choose an image of 81 × 81 pixels in the PNG, JPEG, JPG. or GIF format. Images from the Internet are supported.
success	Function	No	The callback method that indicates a successful call.
fail	Function	No	The callback method that indicates a failed call.
complete	Function	No	The callback method that indicates the call is completed (this will be executed regardless of whether the call succeeds or fails).

my.setTabBarStyle

This interface allows you to dynamically set the overall style of tabBar, including the font color and the background color and border color of tab icons. If you have any problems, see FAQ.

Sample code

The following is the sample code of my.setTabBarStyle:

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

Parameters

The parameters are in object type and have the following properties:

Parameter	Type	Required	Description
color	HexColor	Required	The text color of the tab when the tab is not selected.
selectedColor	HexColor	Required	The text color of the tab when the tab is selected.
backgroundColor	HexColor	Required	The background color of the tab.
borderStyle	String	Required	The color of the top border of tabBar. Valid values: `black` and `white`.
success	Function	No	The callback method that indicates a successful call.
fail	Function	No	The callback method that indicates a failed call.
complete	Function	No	The callback method that indicates the call is completed (this will be executed regardless of whether the call succeeds or fails).

my.showTabBar

Version requirement: Base library V1.11.0 or later versions. For earlier versions, you must first handle the incompatibility. For more information, see Compatibility processing.

This interface allows you to show tabBar. If you have any problems, see FAQ.

Sample code

The following is the sample code of my.showTabBar:

my.showTabBar({
    animation: true
})

Parameters

The parameters are in object type and have the following properties:

Parameter	Type	Required	Description
animation	Boolean	No	Specifies whether to enable animation. Default value: No.
success	Function	No	The callback method that indicates a successful call.
fail	Function	No	The callback method that indicates a failed call.
complete	Function	No	The callback method that indicates the call is completed (this will be executed regardless of whether the call succeeds or fails).

my.showTabBarRedDot

This interface allows you to show the red dot in the upper-right corner of a tab icon in tabBar. If you have any problems, see FAQ.

Sample code

The following is the sample code of my.showTabBarRedDot:

my.showTabBarRedDot({
  index: 0
})

Parameters

The parameters are in object type and have the following properties:

Parameter	Type	Required	Description
index	Number	Required	The serial number of the tab icon, counting from the left.
success	Function	No	The callback function that indicates a successful operation.
fail	Function	No	The callback function that indicates a failed operation.
complete	Function	No	The callback function that indicates the operation is completed. This function is executed regardless of whether the operation succeeds or fails.

onTabItemTap

Version requirement: Base library V1.11.0 or later versions. For earlier versions, you must first handle the incompatibility. For more information, see Compatibility processing.

This interface allows you to listen to the tapping events of tabBar. If you have any problems, see FAQ.

Sample code

The following is the sample code of onTabItemTap:

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

FAQ

Questions about supported features

Q: Can I use input parameters to redirect pages that are defined in tabBar?
A: Yes.
Q: How do I listen to the tapping events of tabBar?
A: You can call the onTabItemTap to listen to the tapping events of tabBar in the mini program.
Q: Can I use an image in the SVG format as a tab icon in tabBar?
A: No. You cannot use images in the SVG format but use the PNG, JPEG, JPG, or GIF format only.
Q: How do I configure the style for a tab?
A: You can configure the style in the JSON file, as shown in the following code snippet. Alternatively, perform the my.setTabBarStyle to configure the style.
```
  "tabBar": {
      "textColor": "#404040",
      "selectedColor": "#108ee9",
      "backgroundColor": "#F5F5F9"
    }
```

Questions about request exceptions

Q: What do I do if the error message “Cannot read property ‘getCurrentPages’ of undefined” appears when I try to switch to a page in tabBar?
A: This error occurs because the specified URL of tabBar is wrong. Please check the URL of tabBar.
Q: Why does tabBar disappear after I redirect to a page?
A: If a page appears after the my.navigateTo or my.redirectTo is performed, tabBar does not appear at the bottom of the page. In addition, the default page of tabBar must be the homepage of the mini program.
Q: Can I redirect pages in tabBar with input parameters?
A: tabBar does not support redirecting tabs with input parameters. We recommend that you use cache or global variables to redirect with input parameters.
Q: After I go to a page of tabBar, how do I obtain the URL of the upper-level page?
A: After you go to a page, the URL of the current page is stored globally. When you switch among the tabs in tabBar, you can use the URL property to obtain the global URL of the upper-level page.
Q: During commissioning in an IDE, why are the life cycle functions onshow and onload not executed when I switch among tabs in tabBar?
A: You must use a physical device to test page switching in tabBar. Life cycle functions are not triggered if you perform commissioning in an IDE.