All Products
Search
Document Center

tabBar

Last Updated: Apr 07, 2021

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:

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

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:

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

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:

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

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:

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

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:

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

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

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 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:

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

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

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 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:

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

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:

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

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

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 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:

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

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:

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

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.

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

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.