更新记录

0.1.6（2026-08-01） 下载此版本

• 修复暗黑模式下字体图标仍使用浅色主题固定色，导致激活图标与文字颜色不一致
• 图标默认激活色与未激活色改为跟随 --nax-color-primary、--nax-color-text-secondary；显式 activeColor / inactiveColor 行为不变

平台兼容性

uni-app x(4.25)

其他

nax-tabbar

自定义底部标签栏（非 pages.json 原生 tabBar）。面向 uni-app x：字体图标优先、轻量徽标、fixed 占位与安全区。

用法

<template>
  <view class="page">
    <scroll-view class="body" scroll-y>
      <!-- 页面内容 -->
    </scroll-view>
    <nax-tabbar v-model="tab" :list="tabs" @change="onChange" @click="onClick" />
  </view>
</template>

<script setup lang="uts">
const tab = ref(0)
const tabs = [
  { text: '首页', icon: 'home' },
  { text: '发现', icon: 'search', badge: 12 },
  { text: '发布', icon: 'plus', midButton: true },
  { text: '消息', icon: 'heart', dot: true },
  { text: '我的', icon: 'user' }
]

function onChange(index: number) {
  console.log('change', index)
}

function onClick(index: number) {
  // 重复点同一项也会触发，可做「回顶」等
}
</script>

路由切换由业务处理：本组件只负责 UI 选中态与事件，不自动 switchTab / reLaunch。

Props

list 项字段

图标优先级： 配置了图片路径 → image；否则 nax-icon 字体图标（性能更优）。

事件

主题 Token

• --nax-color-bg / --nax-color-border
• --nax-color-primary / --nax-color-primary-deep
• --nax-color-text-secondary
• --nax-color-error
• --nax-font-size-xs

依赖

• nax-icon
• nax-ui-theme（可选，提供统一 token）

与原生 tabBar

• 本组件是 自定义 tab 栏 UI，可在任意页面使用；不内置 switchTab / reLaunch。
• 多页秒切（推荐）：pages.json 登记原生 tabBar → 业务用 uni.switchTab 互切 → 各 Tab 页 uni.hideTabBar → 底部渲染本组件。
• 切勿对主 Tab 页默认 reLaunch（整页重建，鸿蒙/App 上可感知数百毫秒～1s 延迟）。
• 单页方案：同一容器内多区块用 CSS visibility 保活，避免反复 v-if 销毁。

自定义底栏 + 原生 Tab 路由（推荐方案）

推荐方案（本仓库已采用）

1. 把「主 Tab 页」登记为 pages.json 原生 tabBar 页面（系统负责保活与 switchTab）
2. 业务 UI 继续用 nax-tabbar（图标 / 徽标 / 中间凸起 / 主题）
3. 每个 Tab 页 onShow 调 uni.hideTabBar({ animation: false })，隐藏原生底栏，避免双栏
4. Tab 互切统一走 uni.switchTab，禁止对 Tab 页 reLaunch / redirectTo

配置示例（pages.json）

{
  "tabBar": {
    "color": "#767c82",
    "selectedColor": "#18a058",
    "backgroundColor": "#ffffff",
    "borderStyle": "black",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/tabbar/blank.png",
        "selectedIconPath": "static/tabbar/blank-active.png"
      },
      {
        "pagePath": "pages/catalog/index",
        "text": "组件",
        "iconPath": "static/tabbar/blank.png",
        "selectedIconPath": "static/tabbar/blank-active.png"
      }
    ]
  }
}

路由封装示例

export function demoTabPaths() : string[] {
    return [
        '/pages/index/index',
        '/pages/catalog/index',
        '/pages/scenes/index',
        '/pages/mine/index'
    ] as string[]
}

export function hideDemoNativeTabBar() {
    // 仅 Tab 页可调；非 Tab 页会 fail（HBuilderX ≥ 4.23）
    uni.hideTabBar({
        animation: false
    })
}

export function switchDemoTab(index : number) {
    const paths = demoTabPaths()
    if (index < 0 || index >= paths.length) {
        return
    }
    uni.switchTab({
        url: paths[index]
    })
}

页面侧

<template>
  <view class="page-root">
    <!-- 内容区 -->
    <nax-tabbar :model-value="0" :list="tabList" @change="onTabChange" />
  </view>
</template>

<script setup lang="uts">
function onTabChange(index : number) {
    if (index == 0) return
    switchDemoTab(index)
}

onShow(() => {
    hideDemoNativeTabBar()
})
</script>

每个主 Tab 页都要挂 nax-tabbar（或抽公共 layout），model-value 对应当前下标。