n-tabbar 底部标签栏
应用级底部导航栏：固定底部 + 底部安全区适配 + 选中高亮 + 图标角标 + 中间凸起按钮 + 点击跳页。数据驱动（list），选中值绑定 modelValue，按 item.value 匹配；仅未设置 item.value 时才使用数组下标。
- 受控切换：点击项时组件发出
update:modelValue与change，是否切换由使用方回写modelValue决定——change回调里做登录校验等前置逻辑，不回写即拦截切换（click事件已选中项也会触发，可作埋点入口）- 角标悬于项内容右上角：数字 ≤0 不显示、>99 显示 "99+"，字符串原样显示，
badge: true显示为红点；#item 插槽项的角标仍按item.badge自动渲染，无需插槽自绘middle: true的项渲染为凸出栏顶的圆形按钮（发布类入口），圆钮只放图标或#middle插槽，标签文字单独保留在栏内；middleWidth/middleHeight分别设置圆钮宽高，默认 40px。middlePlaceholder是栏内图标占位高度，默认 24px，用于让标签与普通项对齐。凸起按钮是动作入口不是选项卡：点击只发click（与 url 跳页），不改选中值，菜单/弹层在click回调里接管。item.url配合linkType在点击后自动跳页（redirectTo 替换当前页 / navigateTo 压栈 / switchTab 跳原生 tabBar 页 / reLaunch 重启）；组件不转发导航 API 的失败回调。需要处理失败时，不配置url，在click事件中由调用方自行调用对应的uni导航 API 并处理fail。跳转与选中值相互独立，由使用方自行决定是否回写。shape: "circle"为悬浮胶囊形态（圆角栏体），配fit（按内容收缩并水平居中，每项水平留白默认 20px）与bottom（固定时距底距离）调整观感；mode: "tag"为标签样式（项呈圆角块、激活项显底色），适合分类切换场景- fixed 时自动生成等高占位防止页面内容塌陷（
placeholder可关）；底部安全区（异形屏 Home 指示条）默认留出距离（safeAreaInsetBottom可关）init在挂载完成后回报栏体与底部安全区的总高度，适合页面自行安排内容偏移；自动占位仍由placeholder控制，运行中随时查询栏体几何用实例方法getRect- 发布菜单通过
#middle插槽组合n-popover；圆钮的尺寸、位置与栏内标签由标签栏管理，插槽只编写触发内容与菜单业务。- 组件默认自带底部安全区垫层：放入自带安全区垫层的宿主（如页面骨架的底栏）时，关闭宿主的垫层或本组件的
safeAreaInsetBottom，两者只留一处，避免双垫
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
API
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| list | NTabbarItem[] | string[] | [] | 标签数据源：对象数组（文字、字体或图片图标、颜色、角标、凸起按钮、跳转路径）或字符串数组（每项作为标签文字，值即下标，适合纯文字导航）；对象列表内 value 需唯一，数量建议 2~5 个 |
| modelValue | string | number | 0 | 当前选中项的值（按 item.value 匹配，缺省值即下标；匹配不到时回落第一项）。受控绑定：change 回调里不回写即拦截切换 |
| height | number | string | 50 | 标签内容区高度（不含底部安全区）；数字按 px，字符串支持 px/rpx；安全区另占完整高度 |
| fixed | boolean | true | 固定底部：标签栏脱离文档流钉在视口底部 |
| placeholder | boolean | true | fixed 开启时是否生成等高占位防止页面内容塌陷 |
| safeAreaInsetBottom | boolean | true | 是否为底部安全区留出距离；胶囊形态不添加安全区垫层，使用 bottom 设置距底间距 |
| background | string | "" | 栏体底色：空串取主题面底色；传色值行内覆盖，支持 linear-gradient(...) 渐变串 |
| activeColor | string | "" | 激活色：选中项图标与文字的颜色；空串取品牌色主题令牌 |
| inactiveColor | string | "" | 未选中项图标与文字的颜色：空串取主题次要文字令牌 |
| badgeBackground | string | "" | 角标底色；空串使用错误色令牌 |
| badgeColor | string | "" | 角标文字颜色；空串使用反白文字令牌 |
| showIcon | boolean | true | 是否显示内置图标；自定义 item 插槽内容不受影响 |
| showText | boolean | true | 是否显示内置文字；自定义 item 插槽内容不受影响 |
| iconSize | number | string | 24 | 图标尺寸；数字按 px，字符串支持 px/rpx |
| textSize | number | string | 10 | 文字字号；数字按 px，字符串支持 px/rpx |
| fontWeight | string | "normal" | 标签文字字重；可设为 "500"、"600"、"bold" 等平台支持值 |
| textStyle | string | "" | 文字行内样式，如 "font-weight:600" |
| shape | "normal" | "circle" | "normal" | 栏体形状：normal 通栏矩形；circle 悬浮胶囊（圆角栏体，配 fit 与 bottom 调整宽度与边距） |
| fit | boolean | false | 胶囊按内容宽度收缩并水平居中，每项水平留白默认 20px；false 时栏体铺满容器。仅 shape = circle 时生效 |
| bottom | number | string | 0 | 胶囊形态固定底部时距视口底部的距离；数字按 px，字符串支持 px/rpx |
| mode | "normal" | "tag" | "normal" | 标签模式：normal 常规底部导航；tag 标签样式（项呈圆角块，激活项显底色），适合分类切换场景 |
| activeBgColor | string | "" | 激活项背景色（任何模式生效）；tag 模式下空串取品牌色 12% 透明度 |
| shadow | boolean | true | 是否显示栏体顶部投影分界 |
| zIndex | number | string | 996 | 层级 z-index |
| customClass | string | "" | 挂到根节点的额外 class（类须在组件样式表内定义，页面 class 打不进组件） |
| customStyle | string | "" | 根节点行内样式 |
NTabbarItem 数据项
| 字段 | 类型 | 说明 |
|---|---|---|
| text | string | 标签文字；空串时不显示内置文字 |
| value | string | number | 标签值，modelValue 按它匹配选中项；缺省以数组下标为值 |
| icon | string | 图标名（n-icon 名称）；更自由的排版走 #item 插槽 |
| activeIcon | string | 选中态图标名；缺省回落 icon |
| iconPath | string | 普通态图片图标路径；与字体图标二选一，图片优先 |
| selectedIconPath | string | 选中态图片图标路径；缺省回落 iconPath |
| color | string | 单项普通态文字与图标颜色，覆盖 inactiveColor |
| selectedColor | string | 单项选中态文字与图标颜色，覆盖 activeColor |
| iconColor | string | 单项图标颜色，设置后普通态与选中态图标均使用该颜色 |
| iconSize | number | string | 单项图标尺寸，缺省使用组件 iconSize |
| customStyle | string | UTSJSONObject | 项节点样式，支持 CSS 字符串或样式对象 |
| disabled | boolean | 单项禁用：保色相降透明，点击不触发事件、不切换 |
| badge | number | string | boolean | 角标：数字 ≤0 不显示、>99 显示 "99+"；字符串原样、空串不显示 |
| dot | boolean | 红点角标；开启后优先于 badge 文本显示 |
| middle | boolean | 中间凸起按钮位：该项渲染为凸出栏顶的按钮，文字与图标仍可用，或由 #item 插槽完整接管 |
| middleWidth | number | string | 凸起按钮宽度；默认 40px，字符串支持 px/rpx |
| middleHeight | number | string | 凸起按钮高度；默认 40px，字符串支持 px/rpx |
| center | boolean | 凸起按钮在栏体内垂直居中；只作用于 middle 项 |
| middleBottom | number | 凸起按钮下缘距栏底的距离（px），默认 24 |
| middlePlaceholder | number | 栏内图标占位高度（px），默认 24；与普通项图标等高时，标签文字对齐 |
| url | string | 点击后跳转的页面路径；空串不跳转 |
| linkType | "navigateTo" | "redirectTo" | "switchTab" | "reLaunch" | 跳转方式，默认 "redirectTo" |
内置跳转不会透传 uni.navigateTo 等 API 的 fail 回调。需要根据失败结果提示用户或回滚业务状态时，省略数据项的 url，在 click 处理器中自行调用 uni.navigateTo、uni.redirectTo、uni.switchTab 或 uni.reLaunch，并处理对应的 fail 回调。不要同时设置 url，以免发生重复跳转。
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
| update:modelValue | value: string | number | 选中项变化时触发，参数为选中项的值（item.value 缺省时为其下标）；配合 :model-value 手动双向绑定 |
| change | detail: | 选中项变化时触发；点已选中项、禁用项或凸起按钮（middle，动作入口不改选中）时不触发 |
| click | detail: | 点击标签项时触发（已选中项也触发）；url 跳转在 click 之后执行 |
| init | detail: | 挂载完成后触发；height 是栏体内容与底部安全区的总高度 |
插槽
| 插槽名 | 参数 | 说明 |
|---|---|---|
| item | 完整接管每一项内容，优先于 middle；角标继续由组件显示 | |
| middle | 仅接管 middle 项的圆钮内部；宽高与位置由组件管理，width/height 为组件计算的实际像素尺寸，可用于填写触发区域宽高，标签仍在栏内 |
方法
| 方法名 | 参数 | 返回 | 说明 |
|---|---|---|---|
| getRect | — | Promise<NTabbarRect | null>（width/height/top/bottom/left/right，视口坐标 px；节点未就绪时 resolve null） | 查询栏体节点几何；凸起按钮避让、胶囊吸底间距等自定义布局可随时调用。init 事件只在挂载时回报一次高度，运行中查询用本方法 |
通过 ref 直接调用：
html
<n-tabbar ref="tabbarRef" :list="list" v-model="active" />js
const tabbarRef = ref<NTabbarComponentPublicInstance | null>(null);
const rect = await tabbarRef.value?.getRect();实现说明（参考做法对照）
| 机制 | 参考做法 | 本组件 | 分歧理由 |
|---|---|---|---|
| 数据模型 | 子组件组合（tabbar + tabbar-item）或 list 数组；一参考支持字符串数组简写 | list 数组驱动，同时接受字符串数组（归一为 { text }，值即下标） | 与本库标签页/分段器同构；项级自由度由数据字段与 #item 作用域插槽承担，纯文字导航保留免写壳的简写通道 |
| 选中值 | name 匹配 / value 匹配 / 纯索引 | modelValue 按 item.value 匹配，缺省下标 | 字符串与数字皆可作标识，比纯索引灵活；命名与本库标签页一致 |
| 切换拦截 | change 回调不回写即不切换 | 同左（受控） | 前置校验（登录等）的主流做法 |
| 图标 | 图片对（icon/selectedIcon）或内置字体名 | icon / activeIcon 与 iconPath / selectedIconPath 并存，图片优先；showIcon 与 showText 控制内置内容 | 支持图片与字体图标数据项，不要求为基础图片切换另写插槽 |
| 角标 | badge + dot 两个属性；支持角标底色与文字色 | badge 与 dot 独立字段，true badge 兼容红点；全局 badgeBackground / badgeColor 可定色 | 保留来源字段并集，合并布尔红点语义 |
| 凸起按钮 | midButton 图片 / middle 插槽 + 独立宽高与位置属性 | item.middle + 独立宽高和定位；#middle 只定制圆钮内部，标签在栏内；middlePlaceholder 为图标占位，图标默认反白 | 采用参考中的独立宽高，支持自定义宽高比例 |
| 文字字重 | 提供 fontWeight | fontWeight 默认为 normal，支持平台字重值 | 保留参考能力，便于按导航层级调整标签文字 |
| 形态 | shape=circle；fit 自适应宽度；迷你示例 height=34、三项纯图标、每项左右 20px | 同左；定位容器负责 fixed，胶囊表面在容器内按内容居中 | 按公开属性与示例核对；加密源码的内部节点组织不可核对 |
| 标签模式 | mode="tag" + 激活底色 | 同左；tag 模式激活底色默认取品牌色 12% 透明度 | 参考源码不可核对的视觉细节按文档描述与本库令牌惯例实现 |
| 固定与占位 | fixed + placeholder / init 事件汇报高度由页面手占 | fixed + 自动等高占位，保留 init 高度回报，另暴露 getRect 随时查询栏体几何 | 占位自动化与手动布局信息并存，分别满足防塌陷及自定义偏移；init 只在挂载时回报一次，运行中查询走 getRect |
| 底部安全区 | safeArea + 异形屏机型表；胶囊不添加安全区 | 普通栏取窗口安全区；胶囊用 bottom 留出间距 | 平台 API 直取，不维护机型表 |
| 顶缘分界 | 0.5px 边框线 / 无 | 顶缘投影（shadow 可关） | 本库浮层分界统一用投影不用边框线（页面底栏同款） |
| 层级 | 默认 1 / 980 / 900 | 默认 996 | 与本库导航栏同层（页面骨架浮层） |