更新记录

1.0.0（2025-12-24） 下载此版本

新增

• 初始版本发布
• 支持简单模式（items）和分组模式（sections）两种数据结构
• 支持亮色（light）、暗色（dark）、自动（auto）三种主题模式
• 支持无限层级子菜单嵌套
• 支持手风琴模式，同级菜单只展开一个
• 支持分组可折叠功能
• 支持自定义颜色配置（背景色、文字色、选中色、悬浮色等）
• 支持 Logo 标题和副标题显示
• 支持导航项图标（图片路径、base64、文字/emoji）
• 支持导航项角标（badge）
• 支持导航项禁用状态
• 支持分割线和分组标题类型
• 提供 header、footer、section-header、icon、item、badge 六个插槽
• 提供 expandAll、collapseAll 两个公开方法
• 提供 change、item-click、expand、section-expand 事件
• 支持 v-model 双向绑定当前选中项
• 支持默认展开指定菜单项（defaultExpandedIds）
• 自动跟随系统主题切换（H5/App/小程序）

平台兼容性

uni-app(3.6.16)

tri-quicken-side-nav

一个功能丰富的 uni-app 侧边导航栏组件，支持多级菜单、分组模式、主题切换等特性。

特性

• 支持亮色/暗色/自动主题切换
• 支持简单模式和分组模式两种数据结构
• 支持无限层级子菜单
• 支持手风琴模式（同级只展开一个）
• 支持分组可折叠
• 丰富的自定义样式选项
• 提供多个插槽满足自定义需求

安装

从 uni-app 插件市场导入即可使用。

基本用法

简单模式

<template>
  <tri-quicken-side-nav
    v-model="activeId"
    :items="navItems"
    @change="handleChange"
  />
</template>

<script>
export default {
  data() {
    return {
      activeId: 'home',
      navItems: [
        { id: 'home', label: '首页', icon: '🏠' },
        { id: 'user', label: '用户管理', icon: '👤' },
        { id: 'settings', label: '设置', icon: '⚙️' }
      ]
    }
  },
  methods: {
    handleChange(item) {
      console.log('选中:', item)
    }
  }
}
</script>

分组模式

<template>
  <tri-quicken-side-nav
    v-model="activeId"
    :sections="sections"
  />
</template>

<script>
export default {
  data() {
    return {
      activeId: 'dashboard',
      sections: [
        {
          id: 'main',
          title: '主菜单',
          items: [
            { id: 'dashboard', label: '仪表盘', icon: '📊' },
            { id: 'analytics', label: '数据分析', icon: '📈' }
          ]
        },
        {
          id: 'system',
          title: '系统设置',
          collapsible: true,
          defaultExpanded: true,
          items: [
            { id: 'profile', label: '个人信息', icon: '👤' },
            { id: 'security', label: '安全设置', icon: '🔒' }
          ]
        }
      ]
    }
  }
}
</script>

多级子菜单

<script>
export default {
  data() {
    return {
      navItems: [
        {
          id: 'products',
          label: '产品管理',
          icon: '📦',
          children: [
            { id: 'product-list', label: '产品列表' },
            { id: 'product-add', label: '添加产品' },
            {
              id: 'product-category',
              label: '产品分类',
              children: [
                { id: 'category-1', label: '分类一' },
                { id: 'category-2', label: '分类二' }
              ]
            }
          ]
        }
      ]
    }
  }
}
</script>

Props 属性

Events 事件

Slots 插槽

Methods 方法

通过 ref 调用组件方法：

<template>
  <tri-quicken-side-nav ref="navRef" :items="items" />
  <button @click="$refs.navRef.expandAll()">展开全部</button>
  <button @click="$refs.navRef.collapseAll()">折叠全部</button>
</template>

数据结构

Item 导航项

Section 分组

主题配置

组件内置两套主题预设：

暗色主题 (dark)

• 背景色：#1a1a1a
• 文字颜色：#ffffff
• 选中色：linear-gradient(90deg, #6366f1 0%, #8b5cf6 100%)

亮色主题 (light)

• 背景色：#ffffff
• 文字颜色：#1a1a1a
• 选中色：linear-gradient(90deg, #6366f1 0%, #8b5cf6 100%)

设置 theme="auto" 时，组件会自动跟随系统主题切换。

使用示例

自定义图标插槽

<template>
  <tri-quicken-side-nav :items="items">
    <template #icon="{ item, active }">
      <image
        :src="active ? item.iconActive : item.icon"
        style="width: 40rpx; height: 40rpx;"
      />
    </template>
  </tri-quicken-side-nav>
</template>

自定义底部

<template>
  <tri-quicken-side-nav :items="items">
    <template #footer>
      <view class="user-info">
        <image src="/static/avatar.png" class="avatar" />
        <text>用户名</text>
      </view>
    </template>
  </tri-quicken-side-nav>
</template>

带角标的导航

<script>
export default {
  data() {
    return {
      navItems: [
        { id: 'messages', label: '消息中心', icon: '💬', badge: 99 },
        { id: 'tasks', label: '待办任务', icon: '📋', badge: 'NEW' }
      ]
    }
  }
}
</script>

使用 iconMap 图标映射

通过 iconMap 属性，可以将简短的图标名称映射到实际的图片路径，方便统一管理图标资源：

<template>
  <tri-quicken-side-nav
    v-model="activeId"
    :items="navItems"
    :icon-map="iconMap"
  />
</template>

<script>
export default {
  data() {
    return {
      activeId: 'home',
      // 图标映射表
      iconMap: {
        'home': '/static/icons/home.png',
        'user': '/static/icons/user.png',
        'settings': '/static/icons/settings.png'
      },
      // 导航数据中使用简短的图标名称
      navItems: [
        { id: 'home', label: '首页', icon: 'home' },
        { id: 'user', label: '用户管理', icon: 'user' },
        { id: 'settings', label: '设置', icon: 'settings' }
      ]
    }
  }
}
</script>

注意事项

1. 使用分组模式时，sections 的优先级高于 items
2. icon 字段支持图片路径（以 /、http、data: 开头）、文字/emoji，以及 iconMap 中定义的 key
3. 手风琴模式仅对同级菜单生效
4. 主题相关的颜色属性（如 backgroundColor、textColor 等）会覆盖主题预设值