支付寶小程序API TabBar

tabBar 使用說明

多 tab 小程序（小程序的底部欄可以切換頁面）可以通過tabBar配置項指定 tab 欄的表現(xiàn)，以及 tab 切換時顯示的對應(yīng)頁面。

注意：

• 通過頁面跳轉(zhuǎn)（my.navigateTo）或者頁面重定向（my.redirectTo）所到達的頁面，即使它是定義在 tabBar 配置中的頁面，也不會顯示底部的 tab 欄。
• tabBar 的第一個頁面必須是首頁。
• tabBar 的 icon 暫不支持 gif 動畫。

tabBar 配置

屬性	類型	必填	描述
textColor	HexColor	否	文字顏色。
selectedColor	HexColor	否	選中文字顏色。
backgroundColor	HexColor	否	背景色。
items	Array	是	每個 tab 的配置。單個 item 的配置屬性見下表。

item 配置

屬性	類型	必填	描述
pagePath	String	是	設(shè)置頁面路徑。
name	String	是	名稱。
icon	String	否	平常圖標路徑。icon 推薦圖片尺寸為 60*60px ，系統(tǒng)會對任意傳入的圖片非等比拉伸/縮放。
activeIcon	String	否	高亮圖標路徑。

示例代碼

{
  "tabBar": {
    "textColor": "#dddddd",
    "selectedColor": "#49a9ee",
    "backgroundColor": "#ffffff",
    "items": [
      {
        "pagePath": "pages/index/index",
        "name": "首頁"      },
      {
        "pagePath": "pages/logs/logs",
        "name": "日志"      }
    ]
  }
}

my.hideTabBar

簡介

my.hideTabBar 是隱藏標簽頁（tabbar）的 API。

相關(guān)問題請參見tabBar常見問題。

使用限制

基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。

示例代碼

// .js
my.hideTabBar({
    animation: true
})

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
animation	Boolean	否	是否需要動畫效果，默認為無動畫效果。
success	Function	否	接口調(diào)用成功的回調(diào)函數(shù)。
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)。
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）。

my.hideTabBarRedDot

簡介

my.hideTabBarRedDot 是隱藏標簽頁（tabbar）某一項右上角的紅點的 API。

相關(guān)問題請參見tabBar 常見問題。

使用限制

• 基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。
• IDE 模擬器 1.13 及以上版本支持該接口調(diào)用。

接口調(diào)用

示例代碼

// .js
my.hideTabBarRedDot({
  index: 0
})

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
index	Number	是	標簽頁的項數(shù)序號，從左邊開始計數(shù)。
success	Function	否	接口調(diào)用成功的回調(diào)函數(shù)。
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)。
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）。

my.removeTabBarBadge

簡介

my.removeTabBarBadge 是移除標簽頁（tabbar）某一項右上角的文本的 API。

相關(guān)問題請參見 tabBar 常見問題。

使用限制

• 基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。
• IDE 模擬器 1.13 及以上版本支持該接口調(diào)用。

接口調(diào)用

示例代碼

// .js
my.removeTabBarBadge({
  index: 0
})

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
index	Number	是	標簽頁的項數(shù)序號，從左邊開始計數(shù)。
success	Function	否	接口調(diào)用成功的回調(diào)函數(shù)。
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)。
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）。

my.setTabBarBadge

簡介

my.setTabBarBadge 是為標簽頁（tabbar）某一項的右上角添加文本的 API?？捎糜谠O(shè)置消息條數(shù)的紅點提醒。

相關(guān)問題請參見 tabBar 常見問題。

使用限制

• 基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。
• IDE 模擬器 1.13 及以上版本支持該接口調(diào)用。

效果示例

接口調(diào)用

示例代碼

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

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
index	Number	是	標簽頁的項數(shù)序號，從左邊開始計數(shù)。
text	String	是	顯示的文本，超過三個字符則顯示前兩個字符+“…”。例如：“支付寶”顯示“支付寶”，“螞蟻金服”顯示“螞蟻…”。
success	Function	否	調(diào)用成功的回調(diào)函數(shù)。
fail	Function	否	調(diào)用失敗的回調(diào)函數(shù)。
complete	Function	否	調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）。

my.setTabBarItem

簡介

my.setTabBarItem 是動態(tài)設(shè)置標簽頁（tabbar）某一項的內(nèi)容的 API。

相關(guān)問題請參見tabBar 常見問題

使用限制

• 基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。
• IDE 模擬器 1.13 及以上版本支持該接口調(diào)用。

接口調(diào)用

示例代碼

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

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
index	Number	是	標簽頁的項數(shù)序號，從左邊開始計數(shù)。
text	String	是	標簽頁按鈕上的文字。
iconPath	String	是	圖片路徑，建議尺寸為 81px * 81px，支持 png/jpeg/jpg/gif 圖片格式，支持網(wǎng)絡(luò)圖片。
selectedIconPath	String	是	選中時的圖片路徑，建議尺寸為 81px * 81px，支持 png/jpeg/jpg/gif 圖片格式，支持網(wǎng)絡(luò)圖片。
success	Function	否	接口調(diào)用成功的回調(diào)函數(shù)。
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)。
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）。

my.setTabBarStyle

簡介

my.setTabBarStyle 是動態(tài)設(shè)置標簽頁（tabbar）的整體樣式的 API，如文字顏色、標簽背景色、標簽邊框顏色等。

相關(guān)問題請參見 tabBar 常見問題。

使用限制

• 基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。
• IDE 模擬器 1.13 及以上版本支持該接口調(diào)用。

接口調(diào)用

示例代碼

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

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
color	HexColor	是	標簽（tab）上的文字默認顏色。
selectedColor	HexColor	是	標簽（tab）上的文字選中時的顏色。
backgroundColor	HexColor	是	標簽（tab）的背景色。
borderStyle	String	是	標簽頁（tabbar）上邊框的顏色， 僅支持 black 、 white 。
success	Function	否	接口調(diào)用成功的回調(diào)函數(shù)。
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)。
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）。

my.showTabBar

簡介

my.showTabBar 是顯示標簽頁（tabbar）的 API。

相關(guān)問題請參見 tabBar 常見問題。

使用限制

基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。

接口調(diào)用

示例代碼

// .js
my.showTabBar({
    animation: true
})

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
animation	Boolean	否	是否需要動畫效果，默認為無動畫效果。
success	Function	否	調(diào)用成功的回調(diào)函數(shù)。
fail	Function	否	調(diào)用失敗的回調(diào)函數(shù)。
complete	Function	否	調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）。

my.showTabBarRedDot

簡介

my.showTabBarRedDot 是顯示標簽頁（tabbar）某一項右上角的紅點的 API。

相關(guān)問題請參見 tabBar 常見問題。

使用限制

• 基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。
• IDE 模擬器 1.13 及以上版本支持該接口調(diào)用。

接口調(diào)用

示例代碼

// .js
my.showTabBarRedDot({
  index: 0
})

入?yún)?/h4>

Object 類型，屬性如下：

屬性	類型	必填	描述
index	Number	是	標簽頁的項數(shù)序號，從左邊開始計數(shù)。
success	Function	否	調(diào)用成功的回調(diào)函數(shù)
fail	Function	否	調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

onTabItemTap

簡介

onTabItemTap 是點擊標簽（tab）時觸發(fā)，可用于監(jiān)聽 tabBar 的點擊事件。

相關(guān)問題請參見 tabBar 常見問題。

使用限制

基礎(chǔ)庫 1.11.0 或更高版本；支付寶客戶端 10.1.32 或更高版本，若版本較低，建議采取 兼容處理。

接口調(diào)用

示例代碼

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

tabBar 常見問題

功能支持類 FAQ

Q：tabBar 的位置是否支持設(shè)置成頂部？

A：tabBar 的位置暫不支持自定義設(shè)置。

Q：如何監(jiān)聽 tabBar 點擊事件？

A：在小程序頁面中用 onTabItemTap 即可監(jiān)聽 tabBar 點擊事件。

Q：tabBar 的 icon 圖標是否支持 svg 格式？

A：不支持 svg 格式，只支持 png/jpeg/jpg/gif 圖片格式。

Q：如何設(shè)置 tab 的樣式？

A：可以在 JSON 文件中直接設(shè)置樣式（示例代碼如下所示），或者調(diào)用 my.setTabBarStyle API 進行設(shè)置。

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

請求異常類 FAQ

Q：切換 tabBar 時報錯“Cannot read property 'getCurrentPages' of undefined”，如何處理？

A：tabBar 路徑錯誤導(dǎo)致，請檢查 tabBar 路徑。

Q：跳轉(zhuǎn)頁面后，為何不顯示 tabBar 呢？

A：通過頁面跳轉(zhuǎn)（my.navigateTo）或者頁面重定向（my.redirectTo）所到達的頁面，不會顯示底部的 tab 欄。另外，tabBar 的第一個頁面必須是首頁。

Q：小程序進入 tabBar 頁面，如何獲取上一級頁面路徑呢？

A：在進入頁面的時候?qū)斍绊撁媛窂酱嫒肴?，在切換 tabBar 頁面的時候拿全局的地址屬性即可獲取上一級頁面路徑。