自定义tabBar
| 名称 | 类型 | 兼容性 | 描述 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| direction | string | 选项的排列方向 | ||||||||||
| ||||||||||||
| show-icon | boolean | 是否显示icon | ||||||||||
| selected | number | 选中的tabBar选项索引值 | ||||||||||
| @onTabItemTap | (event: OnTabItemTapOption) => void | 点击自定义 tabBar 触发事件,detail = {index, pagePath, text} | ||||||||||
本页介绍的 <custom-tab-bar> 组件仅支持 Web,微信小程序、支付宝小程序提供的平台自定义 tabBar 能力与本组件不同,本页的组件属性和事件不适用于这些平台。
在 uni-app x 项目中,可通过 pages.json 配置启用对应平台的自定义 tabBar,并在项目根目录下添加该平台约定的 tabBar 组件目录。
├─custom-tab-bar/ // 微信小程序自定义 tabBar
│ ├─index.js // 组件数据及交互逻辑
│ ├─index.json // 组件配置
│ ├─index.wxml // 组件布局
│ └─index.wxss // 组件样式
├─customize-tab-bar/ // 支付宝小程序自定义 tabBar
│ ├─index.js
│ ├─index.json
│ ├─index.axml
│ └─index.acss
├─pages/
│ ├─index/
│ │ └─index.uvue
│ └─mine/
│ └─mine.uvue
├─App.uvue
├─main.ts
├─manifest.json
└─pages.json
编译器会将对应平台的 tabBar 目录复制到小程序产物中。这两个目录中的文件需按照对应小程序的自定义组件规范编写,不支持使用 .uvue 文件。
通过条件编译,分别为微信小程序配置 custom: true、支付宝小程序配置 customize: true:
{
"pages": [
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "首页"
}
},
{
"path": "pages/mine/mine",
"style": {
"navigationBarTitleText": "我的"
}
}
],
"globalStyle": {
"usingComponents": {}
},
"tabBar": {
// #ifdef MP-WEIXIN
"custom": true,
// #endif
// #ifdef MP-ALIPAY
"customize": true,
// #endif
"color": "#666666",
"selectedColor": "#007aff",
"backgroundColor": "#ffffff",
"list": [
{
"pagePath": "pages/index/index",
"text": "首页"
},
{
"pagePath": "pages/mine/mine",
"text": "我的"
}
]
}
}
两个平台的 tabBar 组件 index.json 均需声明:
{
"component": true
}
组件的布局、样式和点击切换逻辑需按照对应平台的规范实现。例如,可在组件的 data 中维护 selected 字段表示选中项索引,根据该字段渲染选中样式;点击选项时,分别通过 wx.switchTab 或 my.switchTab 切换页面。
注意,这两个特殊目录会直接复制到小程序产物中,其中的代码不会作为 .uvue 组件编译,应使用对应平台的 API。
每个 tabBar 页面的自定义 tabBar 组件实例相互独立。页面显示时,应获取当前页面的 tabBar 实例并更新选中态,避免切换页面后高亮状态不一致。
下面约定 tabBar 组件的 data 中已声明 selected 字段。页面使用 <script setup>,在 setup 阶段获取页面实例,在每次 onShow 时将选中态更新为 0:
<!-- pages/index/index.uvue -->
<template>
<view>
<text>首页</text>
</view>
</template>
<script setup lang="ts">
const instance = getCurrentInstance()
function syncTabBar() {
// #ifdef MP-WEIXIN || MP-ALIPAY
const scope = (instance?.proxy as any)?.$scope
if (scope == null || typeof scope.getTabBar !== 'function') {
return
}
const tabBar = scope.getTabBar()
if (tabBar != null) {
tabBar.setData({ selected: 0 })
}
// #endif
}
onShow(() => {
syncTabBar()
})
</script>
pages/mine/mine.uvue 使用相同的处理方式,将 selected 更新为 1。页面中无需手动放置 <custom-tab-bar> 组件。
tabBar 配置,用于识别 tabBar 页面及兼容低版本。这些配置不参与自定义 tabBar 的渲染,外观需由自定义组件实现。wx.setTabBarItem 等与 tabBar 样式相关的接口失效,需通过自定义组件控制显示效果。tabBar 配置。customize,目录名为 customize-tab-bar,与微信小程序不同。my.hideTabBar 等与 tabBar 样式相关的接口失效,需通过自定义组件控制显示效果。