uni-app x uni-tabBar UTS 插件深度解析动态设置 TabBar 样式、徽标与中间按钮的完整实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-tabBar 是 uni-app / uni-app x 仓库中一个基于 UTS 技术实现的 uni_modules 插件核心能力是实现设置 TabBar 样式功能把uni.setTabBarBadge、uni.setTabBarItem、uni.setTabBarStyle等 9 个 TabBar 动态操作 API 的跨端实现沉淀为可复用插件。本文以仓库中的插件文档 src/uni_modules/uni-tabBar/readme.md 为骨架结合其源码实现与官方示例组件完整讲解 UTS 语言与 UTS 插件机制、全部 API 的参数语义与平台支持矩阵、Android/HarmonyOS 双端底层调用链以及可直接复制的实战代码。读完你既能熟练使用这套 API 完成 TabBar 的运行时定制角标、红点、显隐、换肤、中间凸起按钮也能理解一个标准 UTS 插件从类型声明到分平台实现的完整工程结构。一、插件定位一个封装 TabBar 动态 API的 UTS 插件在 uni-app x 中TabBar 的静态配置页面路径、图标、颜色等通过 pages.json 中的tabBar字段声明而运行时的动态调整添加数字角标、显示红点、切换样式、隐藏某个 tab则由uni.xxx系列 API 完成。uni-tabBar 插件正是这些动态 API 的统一载体。从插件元信息 package.json 可以看到插件 ID 为uni-tabBartype为uts即一个纯 UTS 插件engines.HBuilderX要求^3.6.8说明该插件适用于 HBuilderX 3.6.8 及以上版本在uni_modules.uni-ext-api.uni段中声明了 9 个扩展 APIshowTabBarRedDot、hideTabBarRedDot、setTabBarBadge、removeTabBarBadge、setTabBarItem、setTabBarStyle、showTabBar、hideTabBar、onTabBarMidButtonTapplatforms段声明了插件在 Vue2/Vue3、AppAndroid/iOS、H5、各主流小程序微信、阿里、百度、字节跳动、QQ、钉钉、快手、飞书、京东以及快应用等客户端环境中的可用性。也就是说插件安装后这些 API 会以uni.setTabBarBadge()的形式直接注入全局uni对象开发者无需关心底层是 Kotlin、Swift 还是 ArkTS。二、UTS 语言与 UTS 插件机制插件的技术底座uni-tabBar 之所以能一套代码覆盖多端依赖于其背后的 UTS 语言与 UTS 插件规范。以下内容摘自插件文档并结合作者视角展开。2.1 UTS可编译为多端原生语言的强类型语言UTSuni type script是一门跨平台、高性能、强类型的现代编程语言它最大的特点是按目标平台编译为对应的原生语言| 目标平台 | 编译产物语言 | | -- | -- | | Android | Kotlin | | iOS | Swift | | HarmonyOS鸿蒙 | ArkTS | | Web / 小程序 | JavaScript |UTS 采用了与 TypeScript 基本一致的语法规范并支持绝大部分 ES6 API。但为了跨端统一UTS 做出了一些约束并针对特定平台进行了增补过去在 JS 引擎下运行的语法大部分在 UTS 处理后可以平滑迁移到 Kotlin 和 Swift 中但仍有部分语法无法抹平差异此时需要借助条件编译——和 uni-app 的条件编译类似UTS 同样支持条件编译写在条件编译分支里的代码可以调用平台特有的扩展语法。仓库内 UTS 相关的完整介绍可参考 docs/uts/README.mdUTS 与 TS 的具体差异见 docs/uts/uts_diff_ts.md。2.2 UTS 插件用 UTS 封装原生 API 的标准形态UTS 插件是一种特定的 uni_modules 插件其核心目的是允许 uni-app / uni-app x 开发者使用 UTS 语法调用扩展 API封装原生系统的 API 或三方 SDK。UTS 插件的实现代码主要位于utssdk目录下并按平台分离组织插件文档给出了如下目录约定| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |utssdk/app-android| Android | UTS, Kotlin, Java | 存放 UTS 插件在 Android 平台上的具体实现源码 | |utssdk/app-ios| iOS | UTS, Swift | 存放 UTS 插件在 iOS 平台上的具体实现源码 | |utssdk/app-harmony| HarmonyOS鸿蒙 | UTS, ArkTS | 存放 UTS 插件在 HarmonyOS 平台上的具体实现源码 | |utssdk/*.uts| 多平台共用 | UTS | 存放使用 UTS 语言编写的、可供所有平台共用的实现源码 |uni-tabBar 插件严格遵循了这一结构。查看仓库中的 src/uni_modules/uni-tabBar/utssdk 目录utssdk/ ├── app-android/ │ └── index.uts # Android 平台实现 ├── app-harmony/ │ └── index.uts # HarmonyOS 平台实现 ├── interface.uts # 多平台共用全部 API 的类型声明跨端共用 ├── protocol.uts # 多平台共用API 名称常量与参数协议校验表 └── unierror.uts # 多平台共用统一错误类其中app-android/index.uts与app-harmony/index.uts是平台专属实现其余三个文件为跨平台共享逻辑。UTS 插件的整体开发规范可参考 docs/plugin/uts-plugin.md如需在插件中混编原生语言见 docs/plugin/uts-plugin-hybrid.md各平台的注意事项分别见 docs/plugin/uts-for-android.md、docs/plugin/uts-for-ios.md 与 docs/plugin/uts-for-harmony.md。三、九个 API 的完整参数语义与类型定义插件对外暴露的能力全部收敛在跨平台类型声明文件 interface.uts 中该文件同时定义了参数类型、回调类型、错误码与Uni接口扩展声明。下面按功能分组逐一拆解。3.1 角标BadgesetTabBarBadge / removeTabBarBadgesetTabBarBadge用于为 TabBar 某一项的右上角添加文本角标其参数类型SetTabBarBadgeOptions定义如下见 interface.uts| 字段 | 类型 | 必填 | 说明 | | -- | -- | -- | -- | |index| number | 是 | tabBar 的哪一项从左边算起索引从 0 开始 | |text| string | 是 | 显示的文本不超过 3 个半角字符 | |success| (result) void | 否 | 接口调用成功的回调 | |fail| (result) void | 否 | 接口调用失败的回调 | |complete| (result) void | 否 | 接口调用结束的回调成功、失败都会执行 |removeTabBarBadge用于移除角标参数RemoveTabBarBadgeOptions只需必填的index语义同上。两个 API 均返回Promise... | null因此既可写回调也可await。在 protocol.uts 中两者的参数协议同样约束为indexnumber、必填、textstring、必填。也就是说运行时若缺少index或text会在参数校验阶段直接失败而不会进入原生调用。3.2 红点showTabBarRedDot / hideTabBarRedDotshowTabBarRedDot用于在 TabBar 某一项的右上角显示红点hideTabBarRedDot用于隐藏。两者的ShowTabBarRedDotOptions/HideTabBarRedDotOptions均只有必填的index配合success/fail/complete回调。协议文件对两者都声明了indexnumber、必填与角标 API 保持一致。3.3 单项内容setTabBarItemsetTabBarItem用于动态设置 TabBar 某一项的内容是日常定制最常用的 API 之一参数类型SetTabBarItemOptions包含| 字段 | 类型 | 必填 | 说明 | | -- | -- | -- | -- | |index| number | 是 | tabBar 的哪一项从左边算起索引从 0 开始 | |text| string | 否 | tab 上按钮文字 | |iconPath| string | 否 | 图片路径 | |selectedIconPath| string | 否 | 选中时的图片路径 | |pagePath| string | 否 | 页面绝对路径 | |iconfont| SetTabBarItemIconFontOptions | 否 | 字体图标优先级高于iconPath| |visible| boolean | 否 | tab 是否显示 | |success/fail/complete| 回调 | 否 | 标准回调三件套 |其中SetTabBarItemIconFontOptions结构为text字库 Unicode 码、selectedText选中后字库 Unicode 码、fontSize字体图标字号单位 px、color字体图标颜色、selectedColor字体图标选中颜色。值得注意的细节pagePath字段带有uniPlatform标注在 AppAndroid/iOS/HarmonyOS各端标注为uniVer: x而 Web 端为√说明该字段的能力覆盖存在平台差异跨端使用时需要留意具体以目标端实际支持为准iconfont的优先级高于iconPath即同时传入时以字体图标为准。3.4 整体样式setTabBarStylesetTabBarStyle用于动态设置 TabBar 的整体样式参数SetTabBarStyleOptions字段如下| 字段 | 类型 | 必填 | 说明 | | -- | -- | -- | -- | |color| string | string.ColorString | 否 | tab 上文字默认颜色 | |selectedColor| string | string.ColorString | 否 | tab 上文字选中时的颜色 | |backgroundColor| string | string.ColorString | 否 | tab 的背景色 | |backgroundImage| string | 否 | 图片背景 | |backgroundRepeat| repeat | repeat-x | repeat-y | no-repeat | 否 | 背景图平铺方式分别为垂直水平平铺、水平平铺垂直拉伸、垂直平铺水平拉伸、双向拉伸 | |borderColor| string | string.ColorString | 否 | tabbar 上边框颜色优先级高于 borderStyle | |borderStyle| black | white | 否 | tabbar 上边框颜色黑/白二选一 | |midButton| MidButtonOptions | 否 | tabbar 中间按钮仅在 list 项为偶数时有效内部能力 | |success/fail/complete| 回调 | 否 | 标准回调三件套 |其中MidButtonOptions用于实现类似中间凸起的发布按钮效果参数为width中间按钮宽度默认 80pxtabBar 其它项为减去此宽度后平分、height中间按钮高度默认 50px可大于 tabBar 高度实现中间凸起效果、text中间按钮文字、iconPath中间按钮图片路径、iconWidth图片宽度高度等比例缩放默认 24px、backgroundImage中间按钮背景图片路径、iconfont字体图标优先级高于iconPath。borderColor与borderStyle的关系在源码中有明确体现Android 实现中会先判断borderColor是否为字符串若是则直接以borderColor覆盖borderStyle详见下文第四节这与类型注释优先级高于 borderStyle完全一致。3.5 显隐控制showTabBar / hideTabBarshowTabBar与hideTabBar用于控制整个 TabBar 的显示与隐藏参数ShowTabBarOptions/HideTabBarOptions仅有一个可选字段animation是否需要动画效果加上标准回调。两者的参数类型声明允许传入nulloptions?: ShowTabBarOptions | null即可以直接uni.hideTabBar()无参调用。3.6 中间按钮事件onTabBarMidButtonTaponTabBarMidButtonTap(callback)用于监听中间按钮的点击事件回调OnTabBarMidButtonTapCallback无参数。从 interface.uts 的uniPlatform标注看该 API 在 AppAndroid/iOS的 uni-app 体系中为√而在 uni-app x 各端多为 xWeb 端 uniVer 为 √即该能力更多面向传统 uni-app 运行时具体以目标平台实际支持为准。3.7 统一错误码与错误对象插件定义了两个错误码见 interface.uts 与 unierror.uts| errCode | 含义 | | -- | -- | | 100 | TabBar 不存在tabBar is not exist | | 200 | 参数错误 |所有 API 的失败对象SetTabBarFail都继承自IUniError并携带errCode实现类SetTabBarFailImpl构造函数签名(errMsg: string, errCode: SetTabBarErrorCode 100)即默认错误码为 100。开发者在fail回调中可通过errCode精确区分失败原因。四、源码级实现剖析一条 API 从调用到原生执行的完整链路uni-tabBar 的共享逻辑与平台实现分离下面分别剖析 Android 与 HarmonyOS 的实现帮助你理解 UTS 插件的内部运作。4.1 Android 平台defineAsyncApi getTabBarAndroid 实现位于 app-android/index.uts其模式可归纳为三步定义异步 API通过defineAsyncApiOptions, Success(apiName, handler)声明例如setTabBarBadge的定义为defineAsyncApiSetTabBarBadgeOptions, SetTabBarBadgeSuccess(setTabBarBadge, ...)获取 TabBar 实例从dcloudio/uni-runtime导入getTabBar()若返回null则res.reject(new SetTabBarFailImpl(tabBar is not exist))并以错误码 100 结束组装参数并调用原生方法将 UTS 对象参数转换为Mapstring, any后调用tabBar.setTabBarBadge(map)成功则res.resolve(null)。以setTabBarItem为例参数组装会把text、iconPath、selectedIconPath、pagePath、visible放入 Map并在iconfont非空时追加一个嵌套的iconfontMap含text/selectedText/fontSize/color/selectedColor。setTabBarStyle的实现则展示了两个值得关注的细节通过isString(options.borderColor)判断优先使用borderColor作为上边框颜色否则使用getTabBarBorderStyle(options.borderStyle)将black | white转换为平台所需格式midButton非空时将width/height/iconPath/text/iconWidth/backgroundImage及嵌套iconfont组装为midButtonMap。onTabBarMidButtonTap在 Android 侧通过defineOnApi(onTabBarMidButtonTap, ...)注册为事件监听 API当前实现为 noop 占位事件响应由原生侧完成。4.2 HarmonyOS 平台协议校验 参数直传HarmonyOS 实现位于 app-harmony/index.uts与 Android 的主要差异在于API 名称使用常量如API_SET_TAB_BAR_BADGE、API_SHOW_TAB_BAR_RED_DOT等这些常量统一定义在 protocol.uts 中如export const API_SET_TAB_BAR_BADGE setTabBarBadge避免字符串散落各处携带参数协议defineAsyncApi的第三个参数传入协议表如SetTabBarBadgeApiProtocol由框架在进入实现前完成参数类型与必填校验校验失败即exec.reject无需在每个方法内重复判断参数直传对象与 Android 的 Map 组装不同Harmony 端将 UTS 对象直接传给原生ITabBar接口hideTabBar/showTabBar无参调用文件同时以export { ... }方式导出了全部 Options/Success 类型供其他模块引用。协议表SetTabBarStyleApiProtocol声明了color/selectedColor/backgroundColor/backgroundImage/backgroundRepeat/borderStyle/borderColor七个可选 string 参数SetTabBarItemApiProtocol声明index必填、其余text/iconPath/selectedIconPath/pagePath/visible/iconfont可选。4.3 双端一致性小结| 环节 | Androidapp-android/index.uts | HarmonyOSapp-harmony/index.uts | | -- | -- | -- | | API 定义 |defineAsyncApi(xxx, handler)|defineAsyncApi(API_XXX, handler, Protocol)| | TabBar 获取 |getTabBar()来自 dcloudio/uni-runtime |getTabBar()并断言为ITabBar| | 空实例处理 |reject(new SetTabBarFailImpl(tabBar is not exist))|reject(tabBar is not exist)| | 参数传递 | 组装Mapstring, any| 直接传递 UTS 对象 | | 参数校验 | 由业务/原生侧处理 | 框架层协议表校验 |从源码结构看插件把跨端共用的类型与协议与平台专属的调用细节严格隔离这正是标准 UTS 插件的推荐组织方式。五、官方示例api-set-tabbar 组件实战演示仓库在 src/components/api-set-tabbar/api-set-tabbar.vue 中提供了覆盖全部 API 的官方演示组件页面标题tababr脚本语言为languts是学习这套 API 的最佳范本。5.1 角标与红点的互斥切换演示组件用两个状态hasSetTabBarBadge与hasShownTabBarRedDot控制并保证两者互斥设置角标前先隐藏红点显示红点前先移除角标避免角标与红点叠加const setTabBarBadge () { if (hasShownTabBarRedDot.value) { uni.hideTabBarRedDot({ index: 1 }) hasShownTabBarRedDot.value !hasShownTabBarRedDot.value } if (!hasSetTabBarBadge.value) { uni.setTabBarBadge({ index: 1, text: 1 }) } else { uni.removeTabBarBadge({ index: 1 }) } hasSetTabBarBadge.value !hasSetTabBarBadge.value } const showTabBarRedDot () { if (hasSetTabBarBadge.value) { uni.removeTabBarBadge({ index: 1 }) hasSetTabBarBadge.value !hasSetTabBarBadge.value } if (!hasShownTabBarRedDot.value) { uni.showTabBarRedDot({ index: 1 }) } else { uni.hideTabBarRedDot({ index: 1 }) } hasShownTabBarRedDot.value !hasShownTabBarRedDot.value }5.2 样式与单项的动态定制customStyle在默认配色与自定义配色间切换完整展示了setTabBarStyle的color、selectedColor、backgroundColor、borderStyle用法并注释提示可追加borderColor优先级更高uni.setTabBarStyle({ color: #FFF, selectedColor: #007AFF, backgroundColor: #000000, borderStyle: black, })customItem/setTabBarTitle/hideTabBarItem则演示了setTabBarItem的三类玩法更换文字text: API、设置超长标题同时清空iconPath/selectedIconPath、通过visible: false隐藏某项。其中图标使用仓库静态资源 src/static/api.png 与 src/static/apiHL.pnglet tabBarOptions { index: 1, text: 接口, iconPath: /static/api.png, selectedIconPath: /static/apiHL.png } as SetTabBarItemOptions uni.setTabBarItem(tabBarOptions)5.3 显隐控制与条件编译hideTabBar通过uni.hideTabBar()/uni.showTabBar()切换整条 TabBar。值得注意的是示例对setTabBarItem相关能力使用了条件编译在APP-HARMONY平台通过uni.showToast({ title: 暂不支持 })提示其余平台走完整逻辑#ifdef APP-HARMONY/#ifndef APP-HARMONY。这印证了 UTS 条件编译在实际项目中的典型用法——对平台差异能力做降级处理。5.4 组件卸载时的状态恢复示例在onUnmounted中根据各状态标记逐个还原 TabBar移除角标、隐藏红点、恢复样式、恢复 item 文本与图标、恢复visible最后uni.showTabBar()。这一写法是页面级 TabBar 定制必须养成的习惯——避免组件销毁后 TabBar 残留被修改的状态。六、API 平台支持矩阵与使用注意事项结合 interface.uts 中各 API 的uniPlatform标注可将主要 API 的支持情况归纳如下√ 表示支持x 表示不支持数字表示引入该能力的 uni-app x 版本此为仓库源码标注实际以目标端版本为准| API | App-Android (unixVer) | App-iOS (unixVer) | App-Harmony (unixVer) | 微信小程序 (unixVer) | Web (unixVer) | | -- | -- | -- | -- | -- | -- | | setTabBarBadge / removeTabBarBadge | 3.91 | 4.11 | 4.61 | 4.41 | 4.0 | | setTabBarItem | 3.91 | 4.11 | 4.61 | 4.41 | 4.0 | | setTabBarStyle | 3.91 | 4.11 | xuniVer 4.23 | 4.41 | 4.0 | | showTabBar / hideTabBar | 3.91 | 4.11 | 4.61 | 4.41 | 4.0 | | showTabBarRedDot / hideTabBarRedDot | 3.91 | 4.11 | 4.61 | 4.41 | 4.0 | | onTabBarMidButtonTap | unixVer xuniVer √ | unixVer xuniVer √ | x | x | 4.0 |使用时的关键注意事项index是硬性必填参数从 0 开始计数越界或缺失会在协议校验/原生调用阶段报错角标text不超过 3 个半角字符且角标与红点语义互斥切换前需先移除另一者官方示例即按此处理borderColor优先级高于borderStyle且borderStyle仅接受black | whiteiconfont优先级高于iconPathmidButton中间按钮仅在 tabBar list 项为偶数时有效并可通过height大于 TabBar 高度实现中间凸起需要监听中间按钮点击时使用uni.onTabBarMidButtonTap(callback)对应 API 文档见 docs/api/on-tab-bar-mid-button-tap.md完整 API 规范与逐参数说明可查阅仓库文档 docs/api/set-tab-bar.md。七、如何安装与使用uni-tabBar 作为 uni_modules 插件使用方式与所有 uni_modules 一致获取插件在 HBuilderX 的插件市场或 uni_modules 目录中导入uni-tabBar当前仓库内的实现位于 src/uni_modules/uni-tabBar可直接作为参考实现比对HBuilderX 版本需不低于^3.6.8确认页面配置确保当前页面属于pages.json中tabBar.list配置的 tab 页面因为所有 API 都依赖getTabBar()获取到已创建的 TabBar 实例否则会以错误码 100tabBar is not exist失败直接调用插件安装后 API 自动挂载到全局uni在script languts setup中直接书写uni.setTabBarBadge({ index, text })等调用即可返回值为 Promise 或使用 success/fail/complete 回调恢复现场参考官方示例在页面onUnmounted中按状态标记恢复 TabBar防止修改泄漏到其他页面。八、结语从 uni-tabBar 看 UTS 插件工程的范式uni-tabBar 是一个体量不大却极具教学价值的 UTS 插件它用共享的interface.uts统一定义 API 类型与平台标注用protocol.uts集中管理 API 常量与参数协议用unierror.uts统一错误语义再用app-android/app-harmony分别对接两端原生运行时。这种共享类型 平台实现的分层模式正是 uni-app x 生态中所有扩展 API 插件的标准范式。理解它你不仅掌握了 TabBar 动态定制的全部 API也获得了一套可复刻的 UTS 插件工程模板。进一步的深入学习可参考仓库内以下资料docs/plugin/uts-plugin.mdUTS 插件开发、docs/uts/README.mdUTS 语言、docs/uts/uts_diff_ts.md与 TS 的差异、docs/api/set-tab-bar.mdAPI 规范以及官方示例 src/components/api-set-tabbar/api-set-tabbar.vue。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考