1. 为什么放着原生 tabBar 不用，非要自己造轮子
做微信小程序开发这几年，tabBar 是我见过被吐槽最多的原生组件之一。很多人第一次接触自定义 tabBar，都是因为设计稿里那个“中间凸起的发布按钮”——原生 tabBar 根本做不出来。但等我真正把项目里的 tabBar 全部改成自定义之后才意识到，凸起按钮只是冰山一角，自定义 tabBar 能解决的问题远比想象中多。
先聊聊原生 tabBar 的三大痛点，你在决定要不要自定义之前，先对照一下自己的需求。
痛点一：样式定制极其受限。原生 tabBar 的 icon 只认图片，不支持字体图标；选中态和未选中态只能各给一张图；文字颜色只能配两种（selectedColor 和 color）；背景色只能填纯色，想加个渐变、加个阴影、加个毛玻璃效果，全部没戏。如果你的设计稿里 tabBar 稍微“花”一点，原生方案基本就宣告死亡了。
痛点二：特殊交互无法实现。除了中间凸起按钮，还有一类常见需求：tabBar 上的某个入口，点击之后不是切页面，而是弹出一个半屏弹窗、调起某个自定义面板，甚至是根据登录状态决定跳转到哪一页。原生 tabBar 的点击行为完全交给框架内部处理，开发者无法拦截，这类需求只能靠自定义 tabBar 来做。
痛点三：多端表现不一致。同样是原生 tabBar，iOS 和 Android 的渲染细节存在差异，比如安全区适配、毛玻璃效果的还原度、图标大小和文字的间距等。设计师拿 iOS 效果图跟你对安卓真机，那画面我经历过太多次了。自定义 tabBar 之后，所有端的表现都由你的代码统一控制，反而更好交代。
不过话说回来，我也见过不少项目属于“为了自定义而自定义”。如果你的 tabBar 就是四个普通图标加文字，颜色、样式都没什么特殊要求，那我劝你老老实实用原生。原生 tabBar 的性能和稳定性是经过海量用户验证的，没必要给自己找活干。
1.1 自定义 tabBar 的本质是什么
理解自定义 tabBar，先要跳出“tabBar 是一个组件”这个思维定式。在小程序里，tabBar 本质上就是固定在页面底部的、与当前页面路由联动的一组导航按钮。原生的实现只是把这套机制内置到了框架里；自定义实现则是你自己用视图组件把这个“底部导航栏”画出来，再手动维护它的选中状态。
搞清楚这个本质之后，你会发现自定义 tabBar 其实没有那么神秘，它要解决的核心问题只有三个：
- 第一，布局问题：如何让一个自定义视图稳定地固定在每个 tab 页面的底部，并且不遮挡页面内容。
- 第二，状态同步问题：当用户在 tab 页面之间切换（包括通过
wx.switchTab切换、通过navigateBack返回）时，底部导航栏的选中态如何与当前页面保持一致。 - 第三，交互问题：点击某个 tab 按钮时，如何准确切换到对应的页面，或者在切换之前执行自定义逻辑。
后面我会逐一拆解这三个问题的解决方案。你只要把这三个问题想明白了，自定义 tabBar 的任何变种玩法（凸起按钮、动态隐藏、角标提醒）都能自己写出来。
1.2 什么情况下才值得自定义
根据我自己的项目经验，以下四种情况属于“不得不自定义”的典型场景，你可以对照判断：
| 场景 | 原生 tabBar 的表现 | 自定义后的效果 |
|---|---|---|
| 设计稿要求中间凸起按钮 | 无法实现 | 完全可控，想凸起多少像素都行 |
| 需要毛玻璃、渐变、阴影等复杂样式 | 基本无法实现 | CSS 随便写，不受限制 |
| tab 点击后需要拦截并执行自定义逻辑 | 无法拦截 | 在 bindtap 里随意处理 |
| 需要根据登录态动态显示/隐藏部分 tab | 无法实现 | setData 控制显隐即可 |
如果只是想要“选中图标大一点”“文字加粗一点”这类微调，我建议你先试试原生 tabBar 的iconPath换图大法——把选中和未选中的图标做成不同尺寸，配合selectedColor调整文字颜色，很多时候并不需要走到自定义这一步。
2. 自定义 tabBar 的两条技术路线怎么选
聊到具体实现，自定义 tabBar 其实有两条完全不同的路线：纯自定义方案和半自定义方案。这两条路线我在不同项目里都踩过，各有适用场景。
2.1 纯自定义方案：整个 tab 栏都是你的
纯自定义方案的意思是，在app.json里完全不配置tabBar字段，所有 tab 页面就是普通页面。在每个 tab 页面的 wxml 底部，引入你自己写好的底部导航组件，并传入当前页面的选中索引。
这个方案的优点非常明显：
- 完全不受原生 tabBar 的任何约束，样式、布局、交互全部自由发挥。
- 组件的显示隐藏完全由页面控制，方便实现“某些页面不显示 tabBar”的需求。
- 没有原生 tabBar 的“切换缓存”黑盒行为，页面生命周期完全可控。
缺点也很直接：
- 每个 tab 页面都要手动引用组件、手动传入 selected 值，代码重复度较高。
- 如果团队里有同事新接手项目，很容易出现“某个页面忘加组件”的低级错误。
- 路由切换时如果处理不当，可能出现 tabBar 和页面内容过渡不自然的问题。
纯自定义方案比较适合 tab 页面数量少、且每个 tab 页面的结构差异较大的项目。比如“首页 + 发布 + 我的”这种三 tab 结构，中间发布页甚至不需要底部导航显示，用纯自定义方案就非常灵活。
2.2 半自定义方案：custom-tab-bar 组件机制
半自定义方案就是官方文档里说的“自定义 tabBar”标准做法。它的大体流程是：
- 在
app.json的tabBar字段中，照常声明list数组（每个 tab 的页面路径和文字），同时新增"custom": true。 - 在根目录下新建
custom-tab-bar/目录，里面放置index.js、index.json、index.wxml、index.wxss四个文件，实现一个自定义组件。 - 当用户点击 tabBar 的某个图标时，框架会把对应页面的路径与
app.json中配置的list进行匹配，并自动切换页面。选中态的维护则需要你手动处理。
这个方案的精髓在于：tab 页面仍然是原生 tabBar 体系内的“原生页面”，wx.switchTab、wx.navigateBack等路由行为依然有效，框架在切换页面时不会出现“页面上没有底部导航”的尴尬情况。而底部导航栏的样式、交互、状态则完全由你的组件接管。
我在实际项目里用的最多的就是半自定义方案，尤其是当一个项目从原生 tabBar 迁移过来时，改动量最小——app.json只需要加一个"custom": true，然后在根目录加一套组件代码即可。
2.3 方案对比与我的选型建议
| 对比维度 | 纯自定义方案 | 半自定义方案 |
|---|---|---|
| 实现复杂度 | 中等，每个页面都要引入组件 | 较低，全局配置一次即可 |
| 路由联动 | 手动维护 | 框架自动联动，状态手动同步 |
| 样式自由度 | 最高 | 很高 |
| 页面缓存 | 与普通页面一致 | 与原生 tabBar 一致 |
| 适合场景 | 少量 tab、特殊布局需求 | 常规 3~5 个 tab 的标准结构 |
我的选型逻辑很简单：如果你的 tab 页面都是普通的标准页面，就用半自定义方案；如果你有某个 tab 页面不想显示底部导航，或者 tab 数量极少且有特殊布局，再用纯自定义方案。大多数情况下，半自定义方案是投资回报率最高的选择。下面的实操部分，我主要以半自定义方案为主线，结合一个电商小程序的真实改造案例来讲。
3. 核心细节拆解：从配置到组件实现
明确了方案之后，接下来就是把每个环节的细节抠清楚。这一节我会从配置、组件内部实现、状态同步、安全区适配四个维度做拆解，每一块都有可以直接抄的代码和背后的原理解释。
3.1 app.json 配置与组件目录结构
先看app.json里的配置。假设我们的电商小程序有四个 tab：首页、分类、购物车、我的。原来的配置长这样：
{ "pages": [ "pages/index/index", "pages/category/index", "pages/cart/index", "pages/mine/index" ], "tabBar": { "color": "#999999", "selectedColor": "#ff5000", "backgroundColor": "#ffffff", "list": [ { "pagePath": "pages/index/index", "text": "首页" }, { "pagePath": "pages/category/index", "text": "分类" }, { "pagePath": "pages/cart/index", "text": "购物车" }, { "pagePath": "pages/mine/index", "text": "我的" } ] } }改成自定义 tabBar 之后，只需要增加一行"custom": true，其他字段可以保留（color、selectedColor 这些也可以去掉，但保留下来不影响）：
{ "pages": [ "pages/index/index", "pages/category/index", "pages/cart/index", "pages/mine/index" ], "tabBar": { "custom": true, "color": "#999999", "selectedColor": "#ff5000", "backgroundColor": "#ffffff", "list": [ { "pagePath": "pages/index/index", "text": "首页" }, { "pagePath": "pages/category/index", "text": "分类" }, { "pagePath": "pages/cart/index", "text": "购物车" }, { "pagePath": "pages/mine/index", "text": "我的" } ] } }这里有个关键点：加了custom: true之后，框架不会自动渲染原生 tabBar，但list数组依然参与路由匹配。也就是说，wx.switchTab跳转到的页面路径必须在这个 list 里，否则无法匹配。从这一点你也能看出，“半自定义”的半，就体现在路由体系依然是原生的那套。
组件目录结构也有讲究。官方要求必须放在项目根目录下的custom-tab-bar文件夹里，组件名固定为index，而且index.json里要声明"component": true：
├── app.js ├── app.json ├── app.wxss ├── custom-tab-bar │ ├── index.js │ ├── index.json │ ├── index.wxml │ └── index.wxss为什么必须是这个路径和这个名字？因为框架在渲染自定义 tabBar 时，会按照custom-tab-bar/index这个固定路径去查找组件。如果你改了文件夹名或者组件文件名，真机上会出现底部导航栏直接消失的现象，而且开发者工具里往往不报错。
3.2 组件内部结构与 selected 状态同步
自定义 tabBar 组件内部的核心逻辑是：从tabBar的配置列表生成按钮数据，根据当前页面路径计算选中索引，并渲染选中态样式。
先看组件的index.js，这里我用的是最常见的Component写法：
Component({ data: { selected: 0, list: [] }, lifetimes: { attached() { // 从全局配置中读取 tabBar 列表 const tabBarList = getApp().globalData.tabBarList || []; this.setData({ list: tabBarList }); } }, methods: { switchTab(e) { const { index, path } = e.currentTarget.dataset; // 这里可以插入自定义逻辑，比如登录校验、埋点上报等 wx.switchTab({ url: path }); } } });这里我引用了一个全局数据getApp().globalData.tabBarList，目的是让组件和app.json的配置保持单一数据源。你可以在app.js里初始化这个数据：
// app.js App({ globalData: { tabBarList: [ { pagePath: "/pages/index/index", text: "首页", iconPath: "/assets/tab/home.png", selectedIconPath: "/assets/tab/home-active.png" }, { pagePath: "/pages/category/index", text: "分类", iconPath: "/assets/tab/category.png", selectedIconPath: "/assets/tab/category-active.png" }, { pagePath: "/pages/cart/index", text: "购物车", iconPath: "/assets/tab/cart.png", selectedIconPath: "/assets/tab/cart-active.png" }, { pagePath: "/pages/mine/index", text: "我的", iconPath: "/assets/tab/mine.png", selectedIconPath: "/assets/tab/mine-active.png" } ] } });组件模板部分，注意小程序自定义组件里如果要使用图片和文本，推荐用cover-view而不是view。虽然普通 view 在大多数情况下也能正常显示，但cover-view可以覆盖在小程序的原生组件（如 map、video、canvas）之上，避免出现原生组件把 tabBar 顶开的诡异问题。我的习惯是直接全部用cover-view，一劳永逸：
<cover-view class="tab-bar"> <cover-view class="tab-bar-item {{selected === index ? 'active' : ''}}" wx:for="{{list}}" wx:key="pagePath" >// pages/index/index.js Page({ onShow() { if (typeof this.getTabBar === 'function' && this.getTabBar()) { this.getTabBar().setData({ selected: 0 }); } } });四个页面分别把selected设置为 0、1、2、3。有人可能会问：能不能在onLoad里同步？不行。因为onLoad只在页面首次加载时触发一次，而 tab 页面之间切换时会触发onShow但不会重新触发onLoad，所以必须在onShow里同步，否则从“首页”切到“我的”再切回“首页”，底部导航的选中态会停留在“我的”。
3.3 中间凸起按钮与安全区适配
讲完常规结构，再来看两个高频需求：中间凸起按钮和安全区适配。这两个需求也是很多团队决定放弃原生 tabBar 的直接原因。
中间凸起按钮的实现思路其实不复杂：在list数据里把某个按钮标记为特殊类型，例如加一个isSpecial: true字段，然后在模板里针对这个按钮做定位偏移。下面是一个带“发布”凸起按钮的简化例子：
// app.js 里定义带特殊按钮的 tab 列表 globalData: { tabBarList: [ { pagePath: "/pages/index/index", text: "首页", iconPath: "...", selectedIconPath: "..." }, { pagePath: "/pages/release/index", text: "发布", iconPath: "/assets/tab/release.png", selectedIconPath: "/assets/tab/release.png", isSpecial: true }, { pagePath: "/pages/mine/index", text: "我的", iconPath: "...", selectedIconPath: "..." } ] }模板里判断isSpecial，给中间按钮加一个向上偏移的类名：
<cover-view class="tab-bar-item {{item.isSpecial ? 'special' : ''}} {{selected === index ? 'active' : ''}}" wx:for="{{list}}" wx:key="pagePath" >.tab-bar-item.special { transform: translateY(-20rpx); }这里要提醒一句：transform在小程序的 cover-view 上有兼容性问题，尤其是真机。更稳妥的做法是直接给特殊按钮加margin-top: -20rpx或者调整padding-top，而不要依赖transform做位移。我最早在 iOS 真机上遇到过translateY对cover-image不生效的坑，后来全部改成margin方案才稳定下来。
安全区适配则是另一个大坑。iPhone 全面屏的底部有一条 home indicator 横条区域，如果你的 tabBar 高度算错了，会出现两种情况：第一种是 tabBar 被横条区域遮挡一部分；第二种是 tabBar 距离底部太远，看起来悬空了。正确做法是让 tabBar 预留出安全区的高度。
小程序里可以用wx.getWindowInfo()（旧版是wx.getSystemInfoSync()）拿到safeArea数据，然后动态计算 tabBar 的整体高度：
const systemInfo = wx.getWindowInfo(); const safeArea = systemInfo.safeArea; // 底部安全距离 = 屏幕高度 - safeArea.bottom const bottomSafeHeight = systemInfo.screenHeight - safeArea.bottom;拿到bottomSafeHeight后，把它设置到 tabBar 的 padding-bottom 上。如果bottomSafeHeight大于 0，说明是全面屏，需要额外加安全距离；如果等于 0，说明是普通屏，不需要额外处理。这个值也可以用env(safe-area-inset-bottom)在 CSS 里处理，但动态设置 JS 计算值更可控。
4. 实操过程：从一个电商小程序的 tabBar 改造说起
理论说够了，来一个完整的实操案例。我用一个四 tab 的电商小程序作为背景，走一遍从原始需求到最终落地的全过程。这个案例我前阵子刚做完，踩了不少坑，把关键节点全部记录下来供参考。
4.1 改造前的问题定义
需求方拿过来的设计稿里有三个明确要求：
- 第一，tabBar 背景要毛玻璃效果，原生 tabBar 做不到，必须自定义。
- 第二，购物车 tab 要带一个数字角标，且角标数量由后端返回，需要动态更新。
- 第三，首页 tab 的图标是当前城市的天气图标，不同城市显示不同的图标组合。
这三个需求单拎出来，任何一个都够原生 tabBar 喝一壶的。所以项目启动时我就确定了半自定义方案的路线。
改造前的页面结构是标准的四 tab 结构，app.json已经配置好了原生 tabBar。改造的第一步，就是在app.json里加上"custom": true，然后按前面的说明在根目录建custom-tab-bar组件。
这个时候有个需要注意的现象：在开发者工具里，加了 custom 之后，底部原生 tabBar 会立即消失，但你的 custom-tab-bar 组件还没写，所以预览时底部会一片空白。这是正常的，不要慌，继续往下走。
4.2 完整代码落地与联调
我把这次改造过程中真正落到生产环境的代码按文件整理出来，供你参考。组件 JS 完整逻辑如下：
// custom-tab-bar/index.js Component({ data: { selected: 0, list: [], // 购物车角标数量，初始为 0 cartCount: 0 }, lifetimes: { attached() { const tabBarList = getApp().globalData.tabBarList || []; this.setData({ list: tabBarList }); } }, methods: { switchTab(e) { const { index, path } = e.currentTarget.dataset; // 如果是购物车 tab，并且用户未登录，先跳登录页 if (index === 2 && !getApp().globalData.isLogin) { wx.navigateTo({ url: '/pages/login/index' }); return; } // 埋点上报 if (typeof wx.reportEvent === 'function') { wx.reportEvent('tab_click', { tab_index: index }); } wx.switchTab({ url: path }); }, // 对外暴露的方法：更新购物车角标 updateCartCount(count) { this.setData({ cartCount: count }); } } });模板里把角标渲染出来：
<cover-view class="tab-bar"> <cover-view class="tab-bar-item {{selected === index ? 'active' : ''}}" wx:for="{{list}}" wx:key="pagePath" >// pages/cart/index.js Page({ onShow() { if (typeof this.getTabBar === 'function' && this.getTabBar()) { this.getTabBar().setData({ selected: 2 }); } this.refreshCartBadge(); }, refreshCartBadge() { const count = this.data.cartGoods.length; if (typeof this.getTabBar === 'function' && this.getTabBar()) { this.getTabBar().updateCartCount(count); } } });这套联调逻辑跑通之后，毛玻璃背景的处理也简单了，直接在index.wxss里对容器加背景模糊即可：
.tab-bar { position: fixed; bottom: 0; left: 0; right: 0; display: flex; background: rgba(255, 255, 255, 0.9); backdrop-filter: blur(20px); padding-bottom: env(safe-area-inset-bottom); z-index: 999; }这里用到了position: fixed来固定底部导航栏，同时给页面内容预留出底部空间。预留的方式有两种：一种是每个页面最外层容器的padding-bottom固定写死一个值；另一种是给页面容器加padding-bottom: calc(100rpx + env(safe-area-inset-bottom))。我个人推荐后一种，因为安全区高度在不同设备上不一致，写死值很容易在小屏幕上导致内容被遮挡。
4.3 与页面列表“加载更多”、导航栏高度的兼容处理
一个电商小程序的 tab 页面，十有八九是有列表的，而列表又必然涉及“加载更多”的分页逻辑。自定义 tabBar 之后，最容易出现的问题就是：列表最后一条数据被底部 tabBar 挡住了。
这个问题我在改造后第一版就遇到了。首页推荐列表滚动到底部，最后一张商品卡片有一半被 tabBar 遮住，用户点不到“加入购物车”按钮。排查下来，原因是页面容器只设置了常规的 padding-bottom，而 tabBar 的实际高度比预想的高——因为我加了安全区 padding 和角标的动态高度。
解决办法是统一提炼一个页面容器的底部安全类名，在全局样式里定义好：
/* app.wxss */ .page-container { padding-bottom: calc(140rpx + env(safe-area-inset-bottom)); }所有 tab 页面的最外层容器都挂上这个类。同时，“加载更多”触底判断也需要配合调整。如果你用的是onReachBottom生命周期，这个逻辑不受影响，因为触底判断是基于页面滚动位置，而不是基于可视区域。但如果你是自己监听滚动事件来判断“是否加载更多”，那就要注意：判断距离底部的值要加上 tabBar 的高度，否则会提前触发加载。
另外一个小细节是顶部导航栏高度。很多人自定义 tabBar 时会顺便把自定义导航栏也做了，这时候页面顶部会多出一块状态栏高度。获取导航栏高度最稳妥的方式是使用胶囊按钮的位置信息：
const menuButtonInfo = wx.getMenuButtonBoundingClientRect(); const statusBarHeight = systemInfo.statusBarHeight; // 导航栏高度 = (胶囊顶部 - 状态栏高度) * 2 + 胶囊高度 const navBarHeight = (menuButtonInfo.top - statusBarHeight) * 2 + menuButtonInfo.height;这个公式是我实测过的，比任何“机型判断”都靠谱。如果你的页面里有吸顶组件或者横向滚动的 tab 切换条，使用这个动态计算的高度能保证不同机型下的表现完全一致。
5. 常见问题与排查技巧实录
自定义 tabBar 写多了之后，你会发现大部分问题都是重复出现的。我把这些年碰到的典型问题整理成一个速查清单，每个问题都附上排查思路和解决方案，方便你直接定位。
5.1 图标不显示或显示为空白占位
这个问题的出现频率最高。排查步骤按顺序来：
- 第一，检查图片路径是否以
/开头。cover-image的 src 要求使用绝对路径，assets/tab/home.png这种相对路径在开发者工具里可能正常，但真机上会加载失败。 - 第二，检查图片格式。部分低版本基础库对 webp 格式支持不好，建议统一使用 png 或 jpg。
- 第三，检查
list数据有没有正常从app.js传递到组件。在attached生命周期里加一个console.log，确认数据是否为空。 - 第四，检查
index.json里是否声明了"component": true。漏掉这个声明，组件无法正常注册，整个 tabBar 会不渲染。
5.2 tab 切换后选中态不同步
症状是：点击 tab 跳到对应页面了，但底部导航的高亮状态还停留在上一个 tab。原因几乎都是忘了在onShow里同步selected。
这里有个疏漏值得特别提醒：很多人只在onShow里同步了 selected，却忘了处理wx.switchTab之外的返回场景。假设用户从“首页”跳到一个普通详情页，再从详情页navigateBack返回首页，首页的onShow会触发，selected 会同步为 0，这没问题。但如果用户从“首页”switchTab到“分类”，再在分类页里navigateBack想返回首页，你会发现navigateBack根本回不去——因为 tab 页面之间的切换是平级的，switchTab无法通过navigateBack回退。这个机制容易让人误以为选中态同步逻辑写错了，实际上只是路由行为不符合预期。
5.3 输入法弹起把 tabBar 顶上去
这个问题在安卓机上特别常见。页面里有输入框（比如搜索框、评论框），聚焦输入时系统键盘弹起，把position: fixed的底部 tabBar 一起顶到了键盘上方，看起来非常滑稽。
解决方案有两种思路：
- 第一种：监听页面的
onKeyboardHeightChange事件，当键盘高度大于 0 时，通过setData把 tabBar 整体隐藏或者往下平移到屏幕外。 - 第二种：输入框所在的页面如果不需要 tabBar，可以在该页面的配置里单独关闭。
我实际生产环境用的就是第一种思路，实现起来很简单：
// 页面 JS 里 onKeyboardHeightChange(res) { if (typeof this.getTabBar === 'function' && this.getTabBar()) { this.getTabBar().setData({ hideTabBar: res.height > 0 }); } }然后在 tabBar 容器上根据hideTabBar控制显隐：
<cover-view class="tab-bar {{hideTabBar ? 'hidden' : ''}}">隐藏动画加一个transition即可，体验上不会很突兀。
5.4 真机下组件闪烁或点击不灵敏
自定义 tabBar 在开发者工具里一切正常，一上真机就出问题，这是最常见也最让人头疼的情况。归纳起来主要有三类表现：
- 表现一：切换页面时 tabBar 闪一下白屏。这通常是
cover-view和页面其他cover-view层级冲突导致的。解决方法是把 tabBar 的z-index提到最高，同时检查页面里是否有原生组件（map、video）的cover-view层级覆盖了 tabBar。 - 表现二：点击反应迟钝，偶尔要点两次才生效。如果 tabBar 里嵌套了
cover-view和cover-image的复杂层级，事件响应会有延迟。我试过把点击事件从bindtap改成catchtap并阻止事件冒泡，情况好了一些，但根治方法还是简化嵌套层级。 - 表现三：低端安卓机渲染错位。部分低端机的
cover-view渲染性能不佳，复杂的 CSS 效果（比如backdrop-filter: blur()）可能会导致整个 tabBar 区域白屏。遇到这种问题，可以做一个降级方案：通过wx.getDeviceInfo()判断设备等级，低端机降级为纯色背景，去掉毛玻璃效果。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| tabBar 整体不显示 | custom-tab-bar 目录或组件名错误 | 检查目录是否为根目录下的custom-tab-bar/index |
| 图标不显示 | cover-image src 使用了相对路径 | 改用以/开头的绝对路径 |
| 选中态不同步 | 未在 onShow 中同步 selected | 在页面 onShow 中调用 getTabBar().setData |
| tabBar 被键盘顶起 | 页面有输入框聚焦 | 监听 onKeyboardHeightChange 隐藏 tabBar |
| 安卓低端机白屏 | cover-view 渲染压力过大 | 降级去除毛玻璃等复杂滤镜 |
| 页面内容被遮挡 | padding-bottom 未预留 tabBar 高度 | 使用calc(140rpx + env(safe-area-inset-bottom)) |
| 点击事件不生效 | 组件层级被原生组件覆盖 | 提高 z-index 或改用 cover-view 容器 |
这套速查表是我每次接手新项目的自查清单，基本能覆盖 90% 以上的自定义 tabBar 问题。剩下的 10%，大概率是基础库版本差异导致的个例，一般升级到最新版本基础库就能解决。
最后分享一个我个人的实操习惯：写完自定义 tabBar 之后，一定要在 iOS 全面屏、Android 全面屏、Android 普通屏三台设备上各跑一遍。不是危言耸听，安全区计算、毛玻璃效果、底部手势条遮挡这几个问题，在开发者工具里永远模拟不出来。你可以在项目里内置一个调试开关，快速切换模拟设备类型，这样每次改完布局都能自测一遍，能省下不少联调时间。
