微信小程式自定義tabBar的踩坑實踐記錄

阿新 • • 發佈：2020-11-06

微信官方文件對自定義 tabBar 的闡述較為潦草，在開發自定義 tabBar 過程中我踩了很多坑，因此在此處做個總結。

我使用 Vant Weapp 作為 UI 元件庫，下面以此元件庫為例。

定義 tabBar

建立自定義 tabBar 檔案

建立一個與 /pages 的同級目錄，命名為 /custom-tab-bar，注意目錄層級與目錄命名問題，不可用其他名稱命名。
在 /custom-tab-bar 下建立四個檔案：

index.js
index.json
index.wxml
index.wxss

index.js

在 index.js 中我們定義相關資料：

active：當前被點選 tab 的索引

list：tab 列表

以及一個切換 tab 時觸發的方法：

function onChange(event)：標籤切換時觸發，修改 active 值，點亮被點選的 tab 並進行頁面跳轉

Component({
 data: {
 // 選中的 tab 
 active: null,// 選單列表
 list: [
  {
  pagePath: '/pages/subscriptions/subscriptions',text: '訂閱',name: 'subscriptions',icon: 'bullhorn-o'
  },{
  pagePath: '/pages/profile/profile',text: '我的',name: 'profile',icon: 'user-o'
  }
 ]
 },methods: {
 // 標籤切換
 onChange: function (event) {
  this.setData({ active: event.detail })
  wx.switchTab({
  url: this.data.list[event.detail].pagePath,})
 }
 }
})

index.json

在 index.json 中，將 component 引數值設為 true，代表這是一個自定義元件：

{
 "component": true
}

因為我使用了Vant Weapp 的 tabBar 標籤欄，所以還需引入額外元件：

{
 "component": true,"usingComponents": {
 "van-tabbar": "@vant/weapp/tabbar/index","van-tabbar-item": "@vant/weapp/tabbar-item/index","van-icon": "@vant/weapp/icon/index"
 }
}

index.wxml

在 index.wxml 中定義元件形態，我在此處使用Vant Weapp 的 tabBar 標籤欄，詳見程式碼，不再贅述。

<van-tabbar active="{{ active }}" bind:change="onChange">
 <van-tabbar-item 
 wx:for="{{list}}" 
 wx:key="index"
 icon="{{item.icon}}" 
 data-path="{{item.pagePath}}">
 {{item.text}}
 </van-tabbar-item>
</van-tabbar>

配置 app.json

在 app.json 中配置如下引數：

usingComponents：僅宣告即可
tabBar：tabBar 元件的具體配置
- custom：設為 true，表示使用自定義元件
- list：tab 頁列表，在列表中的頁面將被設定為 tab 頁，自動載入 tabBar

{
 "usingComponents":{

 },"tabBar":{
  "custom":true,"color":"#000000","selectedColor":"#000000","backgroundColor":"#000000","list":[
   {
    "pagePath":"pages/subscriptions/subscriptions","text":"訂閱列表","iconPath":"","selectedIconPath":""
   },{
    "pagePath":"pages/profile/profile","text":"關於我","selectedIconPath":""
   }
  ]
 }
}

實現 tabBar 選中態

根據微信官方文件描述，每個 tab 頁面 tabBar 的例項是不同的：

每個 tab 頁下的自定義 tabBar 元件例項是不同的，可通過自定義元件下的 getTabBar 介面，獲取當前頁面的自定義 tabBar 元件例項。

顯而易見，每當切換 tab 頁時，我們都需要更新 tabBar 的選中態。關於選中態的實現，官方文件描述如下：

注意：如需實現 tab 選中態，要在當前頁面下，通過 getTabBar 介面獲取元件例項，並呼叫 setData 更新選中態。

我們可以在使用到 tabBar 的頁面中這樣實現：

Page({
 onShow: function () {
 if (typeof this.getTabBar === 'function' && this.getTabBar()) {
  this.getTabBar().setData({
  // 當前頁面的 tabBar 索引
  active: 1
  })
 }
 }
})

至此，一個自定義 tabBar 的實現已全部完成。

踩坑

getTabBar() 方法缺失

在實現 tabBar 選中態時遇到 getTabBar() 方法缺失的問題。在小程式開發工具中跳轉到 getTabBar() 方法的定義，我們可以看到：

/**
 * 返回當前頁面的 custom-tab-bar 的元件例項
 *
 * 最低基礎庫版本：[`2.6.2`](https://developers.weixin.qq.com/miniprogram/dev/framework/compatibility.html)
 **/
getTabBar(): TrivialInstance

該方法的最低基礎版本庫為 2.6.2，我們修改 project.config.json 檔案中的 libVersion 欄位，升級到指定版本庫即可。
升級版本庫後 tabBar 元件報錯

報錯內容如下：