导航菜单

TuiNav 是一个高度集成的数据驱动型导航组件。

与传统的通过 DOM 嵌套（如 <ul><li>）构建菜单不同，TuiNav 完全基于 JSON 数据渲染。这意味着您只需维护一份路由表或菜单配置数组，即可自动生成具备多级嵌套、响应式收缩和折叠动画的完整导航系统。

核心特性

• 数据驱动: 通过 data 属性传入 JSON 树形结构，自动渲染多级菜单。
• 双向布局: 支持 水平 (Horizontal) 顶栏模式和 垂直 (Vertical) 侧边栏模式。
• 智能响应:
  • 水平模式: 空间不足时，自动计算并将多余菜单项收纳至 "..." 下拉菜单中。
  • 垂直模式: 支持一键折叠为图标导航（Mini Sidebar）。
• 交互丰富: 内置手风琴模式、自定义触发方式（Click/Hover）及路由集成。

基础用法

数据结构

组件核心依赖 data 属性。默认的数据字段结构如下（可通过 props 属性自定义映射）：

const menuData = [
  { 
    id: "1", 
    label: '控制台', 
    icon: 'tui-icon ti-home', // 图标类名
    children: [               // 子菜单
      { id: "1-1", label: '主控台' },
      { id: "1-2", label: '监控页' }
    ]
  },
  { 
    id: "2", 
    label: '设置', 
    disabled: true // 禁用状态
  }
];

垂直导航

默认模式 (direction="v")。适用于侧边栏。

<template>
  <div style="width: 250px;">
    <TuiNav 
      :data="menuData" 
      :defaultOpened="['1']"
      @change="handleChange"
    />
  </div>
</template>

水平导航

设置 direction="h" 开启水平模式。 开启 ellipsis 后，组件会根据容器宽度自动计算，将放不下的菜单项收纳到末尾的省略号菜单中。

<template>
  <TuiNav 
    direction="h"
    :data="menuData" 
    :ellipsis="true"
  />
</template>

进阶功能

折叠模式 (Collapse)

仅在垂直模式下生效。设置 collapse 为 true，菜单将收缩为仅显示图标的条带。 子菜单将以弹出（Popover）的形式展示。

<template>
  <div style="width: auto;">
    <TuiNav 
      direction="v"
      :collapse="isCollapse" 
      :data="menuData"
    />
    <button @click="isCollapse = !isCollapse">切换折叠</button>
  </div>
</template>

手风琴模式 (Accordion)

设置 accordion 为 true，开启手风琴效果。此时同级菜单中最多只能展开一项，打开新的菜单会自动收起其他的。

<TuiNav direction="v" accordion :data="menuData" />

路由集成 (Router)

设置 router 为 true 后，组件会自动开启路由监听模式。

• 状态同步: 组件会自动监测当前路由的 path，并将对应的菜单项设置为高亮（Active）状态。
• 手动跳转: 点击菜单项不会自动触发路由跳转，您需要在 @change 事件中手动调用 router.push 或自定义的跳转逻辑。这种设计是为了方便集成页面切换动画（如 TechUI 的 routerTransition）。

<script setup>
import { useRouter } from "vue-router";
const router = useRouter();

// 菜单数据
const menuData = [
  { id: "/home", label: '首页', icon: 'ti-home' },
  { id: "/settings", label: '设置', icon: 'ti-settings' }
];

// 处理跳转逻辑
const handleChange = (obj) => {
  // obj.item 包含当前点击的菜单项数据
  console.log("Navigating to:", obj.item.id);
  
  // 手动执行路由跳转
  router.push(obj.item.id);
  
  // 或者使用自定义的过渡跳转
  // routerTransition({ path: obj.item.id });
}
</script>

<template>
  <TuiNav 
    router 
    :data="menuData" 
    @change="handleChange"
  />
</template>

API 参考

Props

核心数据与布局

属性名	类型	默认值	说明
data	Array	[]	核心数据源。树形结构数组。
direction	String	'v'	导航方向。可选：'v' (垂直), 'h' (水平)。
props	Object	{ id:'id', ... }	数据字段映射配置。默认：{ id:'id', children: 'children', label: 'label', disabled: 'disabled' }。
defaultActive	Array	[]	默认选中的菜单项 ID 数组。
defaultOpened	Array	[]	默认展开的子菜单 ID 数组。

交互行为

属性名	类型	默认值	说明
menuTrigger	String	'global'	子菜单触发方式。可选：'click', 'hover', 'global'(跟随全局设定)。
accordion	Boolean	false	是否开启手风琴模式（仅垂直模式有效）。
router	Boolean	false	是否开启路由模式。
collapse	Boolean	false	是否折叠菜单（仅垂直模式有效）。

响应式与外观

属性名	类型	默认值	说明
ellipsis	Boolean	true	是否开启水平导航的自动省略功能（仅水平模式有效）。
ellipsisIcon	String	'tui-icon ti-more-h'	省略菜单的图标类名。
lineHeight	Number	-	强制指定行高（用于特殊布局微调）。
resizeObserver	String	'global'	尺寸监听策略：'self', 'global', 'none'。用于触发省略计算。
popperOffset	Number	4	弹出菜单的偏移距离。
popperDelay	Number	1000	弹出菜单的显示/隐藏延迟 (ms)。

Events

事件名	说明	回调参数
change	选中菜单项改变时触发。	(item: Object) 当前选中的菜单项数据对象。
open	子菜单展开时触发。	(index: String, indexPath: Array) 展开的菜单 ID 及路径。
close	子菜单收起时触发。	(index: String, indexPath: Array) 收起的菜单 ID 及路径。