cube-layout

@newlifex/cube-vue 布局系统

什么时候用

当需要以下场景时使用：

• 新增自定义页面布局
• 修改框架默认布局
• 切换不同页面使用不同布局
• 为特定路由指定布局

布局使用方式

方式一：框架默认布局（开箱即用）

框架内置了 CyberLayout（赛博风格布局），默认已注册并使用，无需任何配置：

@newlifex/cube-vue/core/layouts/CyberLayout/  ← 默认使用
@newlifex/cube-vue/core/layouts/MainLayout/   ← 备用布局
@newlifex/cube-vue/core/layouts/TopMenu/      ← 备用布局

方式二：应用层注册并使用自定义布局

在项目 src/main.ts 中调用 registerLayout 注册自定义布局，并设为当前布局：

// src/main.ts
import { initApp } from '@newlifex/cube-vue/core/initApp';
import '@newlifex/cube-vue/core/global.css';
import { registerLayout } from '@newlifex/cube-vue/core/composables/useLayout';
import MainLayout from '@newlifex/cube-vue/core/layouts/MainLayout';

// 注册布局并立即切换为当前布局（第二个参数 setAsCurrent = true）
registerLayout({
  id: 'main',
  label: '主布局',
  icon: '⊟',
  description: '侧边栏 + 内容区布局',
  component: MainLayout,
}, true);

initApp();

关键：registerLayout(option, setAsCurrent) 是注册布局的唯一入口。

• setAsCurrent = true：立即切换为该布局（写入 localStorage）
• setAsCurrent = false（默认）：仅注册，不切换（可通过 setLayout(id) 或布局切换器后续切换）

不要使用 provide(app, LayoutKey, ...) —— 那是旧机制，RootLayout 不读取它。

---

CSS Token 规范

重要：布局样式必须使用 Element Plus CSS token（--el-*）或 Cube Layout token（--cube-layout-*），禁止硬编码色值、自定义 CSS 变量或第三方 token 体系。 框架 global.css 和 core/cube-layout-vars.css 提供了完整的 Token 体系，布局组件直接引用即可。

双 Token 架构

┌───────────────────────────────────────────────┐
│  --el-* 体系（Element Plus 语义 Token）        │
│  --el-bg-color, --el-text-color-primary        │  ← 页面背景/文字/边框/填充
│  --el-color-primary, --el-border-color         │  ← 主色/边框
├───────────────────────────────────────────────┤
│  --cube-layout-* 体系（布局结构 Token）         │
│  --cube-layout-sidebar-width                  │  ← 侧边栏宽度
│  --cube-layout-menu-item-color                │  ← 菜单项颜色
│  --cube-layout-nav-height                     │  ← 导航栏高度
│  --cube-layout-tabsview-*                     │  ← 标签页颜色
└───────────────────────────────────────────────┘

Element Plus 语义 Token（--el-*）

Cube Layout 布局结构 Token（--cube-layout-*）

完整 --cube-layout-* 变量清单见 @newlifex/cube-vue/core/cube-layout-vars.css

使用规则

布局专属变量定义方式

推荐：在布局的 styles/variables.css 中使用两层覆盖：

/* styles/variables.css — 同时覆盖 --el-* 和 --cube-layout-* */
:root,
[data-theme="aurora"] {
  /* 1) 覆盖 Element Plus 通用 Token */
  --el-color-primary: #2563eb;
  --el-bg-color: #f8fafc;
  --el-bg-color-overlay: #ffffff;
  --el-text-color-primary: #1e293b;
  --el-text-color-regular: #475569;
  --el-border-color: #e2e8f0;

  /* 2) 覆盖 Cube Layout 布局 Token */
  --cube-layout-sidebar-width: 220px;
  --cube-layout-sidebar-collapsed-width: 64px;
  --cube-layout-nav-height: 60px;
  --cube-layout-sidebar-bg: var(--el-bg-color-overlay);
  --cube-layout-menu-item-active-bg: linear-gradient(135deg, rgba(37,99,235,0.1), rgba(16,185,129,0.1));
}

[data-theme="aurora-dark"] {
  /* 深色模式只覆盖差异化值 */
  --el-bg-color: #0f172a;
  --el-bg-color-overlay: #1e293b;
  --el-text-color-primary: #f1f5f9;
  ...
}

示例对照

/* ❌ 错误：硬编码 */
.sidebar { background: #1e1e1e; color: #e8eaed; }

/* ❌ 错误：使用已废弃的自定义 token */
.sidebar { background: var(--bg-secondary); color: var(--text-primary); }

/* ✅ 正确：使用 Element Plus token */
.sidebar { background: var(--el-bg-color-overlay); color: var(--el-text-color-primary); }

/* ✅ 正确：使用 Cube Layout token */
.sidebar { background: var(--cube-layout-sidebar-bg); }

---

新增自定义布局

注意：首先判断在哪个项目新增布局：

• @newlifex/cube-vue 框架项目：布局将作为内置布局，默认被所有应用使用
• 用户自己的项目（如 NewLife.Cube.Vue）：布局仅当前应用可用

---

场景 A：在用户项目中新增布局

适用于需要为当前项目定制独特外观的情况。

步骤 1：创建布局组件

在项目 src/layouts/ 下创建布局目录：

NewLife.Cube.Vue/src/layouts/
└── CustomLayout/
    ├── index.vue           # 主布局入口
    ├── Sidebar.vue         # 侧边栏（可选）
    └── Navbar.vue          # 顶部导航栏（可选）

步骤 2：编写布局组件

src/layouts/CustomLayout/index.vue：

<template>
  <div class="custom-layout">
    <aside class="layout-sidebar">
      <slot name="sidebar">
        <div class="logo">自定义Logo</div>
      </slot>
    </aside>

    <main class="layout-main">
      <header class="layout-navbar">
        <slot name="header">
          <h1>{{ title }}</h1>
        </slot>
      </header>

      <div class="layout-content">
        <slot></slot>
      </div>
    </main>
  </div>
</template>

<script setup lang="ts">
defineProps<{
  title?: string;
}>();
</script>

<style scoped lang="scss">
.custom-layout {
  display: flex;
  min-height: 100vh;
  background: var(--bg-primary);
  color: var(--text-primary);
}

.layout-sidebar {
  width: var(--custom-sidebar-width, 260px);
  flex-shrink: 0;
  background: var(--bg-secondary);
  border-right: 1px solid var(--border-default);
}

.layout-main {
  flex: 1;
  display: flex;
  flex-direction: column;
}

.layout-navbar {
  height: 64px;
  padding: 0 24px;
  background: var(--navbar-bg, var(--bg-secondary));
  border-bottom: 1px solid var(--navbar-border, var(--border-subtle));
  color: var(--navbar-text, var(--text-secondary));
}

.layout-content {
  flex: 1;
  padding: 24px;
}
</style>

步骤 3：在应用中使用

src/main.ts：

import { initApp } from '@newlifex/cube-vue/core/initApp';
import '@newlifex/cube-vue/core/global.css';
import { registerLayout } from '@newlifex/cube-vue/core/composables/useLayout';
import CustomLayout from './layouts/CustomLayout/index.vue';

// 注册自定义布局并立即切换为当前布局
registerLayout({
  id: 'custom',
  label: '自定义布局',
  icon: '◉',
  description: '自定义布局描述',
  component: CustomLayout,
}, true);

initApp();

---

场景 B：在 @newlifex/cube-vue 框架中新增布局

适用于需要让布局成为框架内置布局，所有应用默认使用的情况。

步骤 1：创建布局组件

在 @newlifex/cube-vue/core/layouts/ 下创建布局目录：

@newlifex/cube-vue/core/layouts/
└── YourLayout/
    ├── index.vue           # 主布局入口
    ├── Sidebar.vue         # 侧边栏（可选）
    ├── Navbar.vue          # 顶部导航栏（可选）
    └── styles/
        ├── variables.scss  # CSS 变量（可选）
        └── theme.scss      # 主题样式（可选）

步骤 2：编写布局组件

@newlifex/cube-vue/core/layouts/YourLayout/index.vue：

<template>
  <div class="your-layout">
    <aside class="layout-sidebar">
      <slot name="sidebar">
        <div class="logo">Logo</div>
      </slot>
    </aside>

    <main class="layout-main">
      <header class="layout-navbar">
        <slot name="header">
          <h1>{{ title }}</h1>
        </slot>
      </header>

      <div class="layout-content">
        <slot></slot>
      </div>
    </main>
  </div>
</template>

<script setup lang="ts">
defineProps<{
  title?: string;
}>();
</script>

<style lang="scss" scoped>
.your-layout {
  display: flex;
  min-height: 100vh;
  background: var(--bg-primary);
  color: var(--text-primary);
}

.layout-sidebar {
  width: 260px;
  flex-shrink: 0;
  background: var(--bg-secondary);
  border-right: 1px solid var(--border-default);
}

.layout-main {
  flex: 1;
  display: flex;
  flex-direction: column;
}

.layout-navbar {
  height: 64px;
  padding: 0 24px;
  background: var(--navbar-bg, var(--bg-secondary));
  border-bottom: 1px solid var(--navbar-border, var(--border-subtle));
  color: var(--navbar-text, var(--text-secondary));
}

.layout-content {
  flex: 1;
  padding: 24px;
}
</style>

步骤 3：在框架中注册布局

编辑 @newlifex/cube-vue/core/main.ts：

import { initApp } from './initApp';
import YourLayout from './layouts/YourLayout/index.vue';
import { registerLayout } from './composables/useLayout';

// 注册新布局
registerLayout({
  id: 'your-layout',      // 唯一标识
  label: '你的布局',       // 显示名称
  icon: '◉',             // 图标
  description: '布局描述',
  component: YourLayout,
});

initApp();

步骤 4：设为默认布局（可选）

在 registerLayout 时设置第二个参数 setAsCurrent = true：

registerLayout({
  id: 'your-layout',
  label: '你的布局',
  icon: '◉',
  description: '布局描述',
  component: YourLayout,
}, true);  // setAsCurrent = true，立即切换为该布局

注意：registerLayout 的第二个参数是 setAsCurrent（布尔值），不是 isDefault。

• true：立即切换为该布局（写入 localStorage）
• false（默认）：仅注册到列表，不切换

应用层使用布局

覆盖框架默认布局

// src/main.ts
import { initApp } from '@newlifex/cube-vue/core/initApp';
import '@newlifex/cube-vue/core/global.css';
import { registerLayout } from '@newlifex/cube-vue/core/composables/useLayout';
import CustomLayout from './layouts/CustomLayout/index.vue';

// 注册自定义布局并立即切换
registerLayout({
  id: 'custom',
  label: '自定义布局',
  icon: '◉',
  description: '自定义布局描述',
  component: CustomLayout,
}, true);

initApp();

运行时切换布局

使用 useLayout 组合函数：

import { useLayout } from '@newlifex/cube-vue/core/composables/useLayout';

const { currentLayout, setLayout, availableLayouts } = useLayout();

// 切换到指定布局
setLayout('main-layout');

// 获取当前布局
console.log(currentLayout.value);

路由级别指定布局

在路由 meta 中指定布局 ID：

const routes = [
  {
    path: '/dashboard',
    component: () => import('./views/Dashboard.vue'),
    meta: {
      layout: 'your-layout',
    },
  },
];

框架内置布局

CyberLayout 赛博风格

CyberLayout 是框架默认布局，特点：

• 默认深色主题（#0a0e14）
• 绿色（#4ade80）/ 青色（#22d3ee）霓虹发光
• 260px 固定侧边栏
• 64px 顶部导航栏
• 内置主题切换按钮（明/暗）

CSS 变量（可在项目覆盖）：

:root {
  --cyber-bg-primary: #0a0e14;
  --cyber-accent-green: #4ade80;
  --cyber-accent-cyan: #22d3ee;
  --cyber-sidebar-width: 260px;
  --cyber-nav-height: 64px;
}

[data-theme="light"] {
  --cyber-bg-primary: #f5f7fa;
  --cyber-accent-green: #16a34a;
  --cyber-accent-cyan: #0891b2;
}

提示：自定义布局的主题变量命名建议以布局名做前缀（如 --aurora-xxx），而非 --cyber-xxx，避免与 CyberLayout 冲突。具体规则见上方「CSS Token 规范」章节。

布局插槽

验证布局

1. 确保布局文件路径正确（框架 vs 用户项目）
2. 运行 pnpm dev
3. 检查布局是否正确渲染
4. 测试主题切换（如适用）
5. 测试响应式效果

布局功能实现流程

重要：新增布局必须实现以下全部功能，才能成为生产级布局。 仅实现 UI 骨架（静态 HTML）属于"玩具"，不能上线。

功能清单与实现流程

1. 注册布局

在 src/main.ts 中调用 registerLayout 注册布局：

// src/main.ts
import { initApp } from '@newlifex/cube-vue/core/initApp';
import '@newlifex/cube-vue/core/global.css';
import { registerLayout } from '@newlifex/cube-vue/core/composables/useLayout';
import AuroraLayout from './layouts/AuroraLayout/index.vue';

registerLayout({
  id: 'aurora',
  label: '极光蓝绿',
  icon: '◉',
  description: '极光蓝绿风格布局',
  component: AuroraLayout,
}, true);  // true = 立即切换为当前布局

initApp();

2. 布局入口组件（index.vue）

<template>
  <div class="aurora-layout">
    <Sidebar />
    <main class="aurora-main">
      <Navbar />
      <div class="aurora-content">
        <slot></slot>
      </div>
    </main>
  </div>
</template>

<script setup lang="ts">
import Sidebar from './Sidebar.vue';
import Navbar from './Navbar.vue';
</script>

<style>
@import './styles/variables.css';
</style>

3. 侧边栏（Sidebar.vue）— 对接 menuStore + 使用 MenuItem + LogoBrand

必须功能：

• Logo：<LogoBrand /> 自动读取配置中的 logo 和 system title
• 搜索框（可选）：<SearchBar mode="box" /> 实时搜索菜单
• 从 menuStore.treeMenus 获取树形菜单
• 使用 <MenuItem> 组件渲染菜单（自动处理递归、图标、高亮、跳转）
• 加载/空状态：显示"加载菜单中..."或"暂无菜单数据"
• 底部用户区域（可选）：<UserProfile variant="sidebar" dropup> 含退出登录

推荐实现（使用 MenuItem 组件）：

<script setup lang="ts">
import { computed } from 'vue';
import { storeToRefs } from 'pinia';
import { useMenuStore } from '@newlifex/cube-vue/core/stores/menu';
import LogoBrand from '@newlifex/cube-vue/core/components/LogoBrand.vue';
import SearchBar from '@newlifex/cube-vue/core/components/SearchBar.vue';
import MenuItem from '@newlifex/cube-vue/core/components/MenuItem.vue';
import UserProfile from '@newlifex/cube-vue/core/components/UserProfile.vue';

const menuStore = useMenuStore();
const { treeMenus, activeMenu, loading, hasMenus } = storeToRefs(menuStore);
const menuGroups = computed(() => treeMenus.value ?? []);
</script>

<template>
  <aside class="sidebar">
    <!-- Logo（自动读取配置） -->
    <div class="sidebar-logo"><LogoBrand /></div>

    <!-- 搜索框 -->
    <div class="sidebar-search"><SearchBar mode="box" placeholder="搜索菜单..." /></div>

    <!-- 菜单（MenuItem 自动处理递归/图标/高亮/跳转） -->
    <nav class="sidebar-menu">
      <template v-for="group in menuGroups" :key="group.id">
        <div v-if="group.children?.length" class="menu-group">
          <div class="menu-group-title">{{ group.title || group.name }}</div>
          <MenuItem v-for="item in group.children" :key="item.id" :menu="item" :activeMenu="activeMenu" />
        </div>
      </template>
      <div v-if="!hasMenus" class="menu-empty">{{ loading ? '加载菜单中...' : '暂无菜单数据' }}</div>
    </nav>

    <!-- 底部用户区域 -->
    <div class="sidebar-user">
      <UserProfile variant="sidebar" dropup>
        <template #extra-options>
          <ModeSwitcher />
          <ThemeSwitcher />
          <LayoutSwitcher />
          <NotificationBell />
        </template>
      </UserProfile>
    </div>
  </aside>
</template>

MenuItem 自动处理了菜单的所有交互（展开/折叠、递归、图标、高亮、跳转），无需手写。

仅当需要自定义交互时才手写菜单（不推荐）：

4. 顶部导航（Navbar.vue）— 对接 userStore + menuStore + 框架组件

必须功能：

• 页面标题：从 menuStore.activeMenu.title 获取
• 用户信息：<UserProfile variant="navbar" /> 自动对接 userStore.userInfo
• 布局切换器：<LayoutSwitcher />
• 主题切换器：<ThemeSwitcher />
• 模式切换器：<ModeSwitcher />
• 通知按钮：<NotificationBell />
• 搜索框（可选）：<SearchBar mode="icon" />

完整示例：

<script setup lang="ts">
import { computed } from 'vue';
import { useMenuStore } from '@newlifex/cube-vue/core/stores/menu';
import LayoutSwitcher from '@newlifex/cube-vue/core/components/LayoutSwitcher.vue';
import ThemeSwitcher from '@newlifex/cube-vue/core/components/ThemeSwitcher.vue';
import ModeSwitcher from '@newlifex/cube-vue/core/components/ModeSwitcher.vue';
import NotificationBell from '@newlifex/cube-vue/core/components/NotificationBell.vue';
import UserProfile from '@newlifex/cube-vue/core/components/UserProfile.vue';
import SearchBar from '@newlifex/cube-vue/core/components/SearchBar.vue';

const menuStore = useMenuStore();
const pageTitle = computed(() => menuStore.activeMenu?.title || menuStore.activeMenu?.name || '仪表盘');
</script>

<template>
  <header class="navbar">
    <!-- 左侧标题 -->
    <div class="navbar-left">
      <h2>{{ pageTitle }}</h2>
    </div>

    <!-- 右侧工具栏 -->
    <div class="navbar-right">
      <SearchBar mode="icon" />
      <ModeSwitcher />
      <ThemeSwitcher />
      <LayoutSwitcher />
      <NotificationBell />
      <UserProfile variant="navbar" />
    </div>
  </header>
</template>

5. 面包屑（可选，在 Navbar 或独立组件中实现）

基于 activeMenu.parentMenu 反向指针链向上递推：

const breadcrumbPath = computed(() => {
  if (!activeMenu.value) return [];
  const path = [];
  let current = activeMenu.value;
  while (current) {
    path.unshift({ name: current.name, title: current.title });
    current = current.parentMenu;
  }
  return path;
});

6. 主题变量（variables.css）

基于框架 CSS Token 定义布局专属变量：

:root,
[data-theme='aurora'] {
  /* 布局尺寸 */
  --aurora-sidebar-width: 220px;
  --aurora-nav-height:    60px;
  --aurora-content-padding: 24px;

  /* 布局颜色（基于 Layer 1 派生） */
  --aurora-bg:             var(--bg-primary);
  --aurora-sidebar-bg:     var(--bg-secondary);
  --aurora-nav-bg:         var(--bg-secondary);
  --aurora-text-primary:   var(--text-primary);
  --aurora-text-secondary: var(--text-secondary);
  --aurora-text-muted:     var(--text-muted);
  --aurora-border:         var(--border-default);
  --aurora-sidebar-border: var(--border-default);

  /* 品牌渐变 */
  --aurora-logo-gradient:  linear-gradient(135deg, var(--blue-600), var(--green-500));
  --aurora-primary-gradient: linear-gradient(135deg, var(--blue-600), var(--green-500));

  /* 圆角 */
  --aurora-radius-sm: 8px;
  --aurora-radius-md: 12px;

  /* 动画 */
  --aurora-transition: all 0.2s ease;
}

7. CSS Token 使用规范

功能完整性检查清单

关键：所有展示用户/菜单/Logo 的组件都已对接真实 Store 或配置，无需手动获取数据。

关键框架组件清单

关键框架 Store

场景判断速查

核心规则：无论哪种场景，都必须调用 registerLayout 才能让布局生效。 RootLayout.vue 只读取 useLayout 的 currentComponent，不读取 provide(LayoutKey)。

---

布局实现完整流程总结

本文档以 AuroraLayout（极光蓝绿） 的实际实现过程为例，完整记录从零到生产可用的全部步骤、复用的框架组件、菜单对接方式、踩坑记录与最佳实践。 后续新增布局时，按此流程执行即可避免常见错误。

---

一、整体流程概览

需求分析 → 研究框架 → 设计 CSS Token → 创建目录结构
  → 实现 index.vue → 实现 Sidebar（对接 menuStore）
  → 实现 Navbar（对接 userStore + 框架组件）
  → 注册布局（registerLayout）→ 构建验证 → 浏览器验证

---

二、复用的框架组件清单

以下组件均来自 @newlifex/cube-vue/core/components/，无需自行实现，直接 import 使用即可。

可复用的框架内置组件

以下组件均来自 @newlifex/cube-vue/core/components/，无需自行实现，直接 import 使用即可。 所有组件都已对接真实数据（menuStore / userStore / config），不是静态 UI。

2.1 LogoBrand — Logo 和系统标题（自动读取配置）

<script setup lang="ts">
import LogoBrand from '@newlifex/cube-vue/core/components/LogoBrand.vue';
</script>

<template>
  <!-- 折叠时隐藏标题 -->
  <LogoBrand :collapsed="false" />
</template>

2.2 MenuItem — 树形菜单组件（动态数据 + 图标）

<script setup lang="ts">
import MenuItem from '@newlifex/cube-vue/core/components/MenuItem.vue';
import { useMenuStore } from '@newlifex/cube-vue/core/stores/menu';
import { storeToRefs } from 'pinia';

const menuStore = useMenuStore();
const { activeMenu } = storeToRefs(menuStore);
</script>

<template>
  <MenuItem v-for="item in topMenus" :key="item.id" :menu="item" :activeMenu="activeMenu" />
</template>

2.3 SearchBar — 菜单搜索框（对接 menuStore 真实菜单）

<script setup lang="ts">
import SearchBar from '@newlifex/cube-vue/core/components/SearchBar.vue';
</script>

<template>
  <!-- 搜索框模式：输入文字弹出搜索结果下拉 -->
  <SearchBar mode="box" placeholder="搜索菜单..." />

  <!-- 图标模式：仅显示搜索图标按钮 -->
  <SearchBar mode="icon" />
</template>

2.4 UserProfile — 用户头像下拉（真实用户数据）

<script setup lang="ts">
import UserProfile from '@newlifex/cube-vue/core/components/UserProfile.vue';
</script>

<template>
  <!-- 顶部栏模式：下拉向下 -->
  <UserProfile variant="navbar" />

  <!-- 侧边栏底部模式：下拉向上 -->
  <UserProfile variant="sidebar" dropup />
</template>

⚠️ 注意：组件名为 UserProfile，不是 NavbarUserProfile。CyberLayout 的 Navbar 中引用 NavbarUserProfile 是旧代码遗留问题，实际该文件不存在，新布局应直接使用 UserProfile。

2.5 LayoutSwitcher — 布局切换下拉

<script setup lang="ts">
import LayoutSwitcher from '@newlifex/cube-vue/core/components/LayoutSwitcher.vue';
</script>

<template>
  <LayoutSwitcher />
</template>

2.6 ThemeSwitcher — 主题选择下拉

<script setup lang="ts">
import ThemeSwitcher from '@newlifex/cube-vue/core/components/ThemeSwitcher.vue';
</script>

<template>
  <ThemeSwitcher />
</template>

2.7 ModeSwitcher — 明暗模式切换

<script setup lang="ts">
import ModeSwitcher from '@newlifex/cube-vue/core/components/ModeSwitcher.vue';
</script>

<template>
  <ModeSwitcher />
</template>

2.8 NotificationBell — 通知铃铛

<script setup lang="ts">
import NotificationBell from '@newlifex/cube-vue/core/components/NotificationBell.vue';
</script>

<template>
  <NotificationBell show-label @click="handleClick" />
</template>

2.9 UserAvatar — 用户头像首字母（轻量级）

<script setup lang="ts">
import UserAvatar from '@newlifex/cube-vue/core/components/UserAvatar.vue';
</script>

<template>
  <UserAvatar size="small" :showName="true" variant="default" />
</template>

---

三、菜单对接方式（Sidebar + Navbar）

3.1 使用的 Store

import { useMenuStore, type TreeMenuItem } from '@newlifex/cube-vue/core/stores/menu';
import { useUserStore } from '@newlifex/cube-vue/core/stores/user';

3.2 TreeMenuItem 数据结构

interface TreeMenuItem {
  id: string;           // 菜单项唯一标识
  name: string;         // 路由名称（用于 router-link 的 name）
  title: string;        // 显示标题
  path: string;         // 路由路径（用于 router-link 的 to）
  icon?: string;        // 图标（emoji 或图标类名）
  parentId?: string;    // 父菜单 ID
  parentMenu?: TreeMenuItem;  // 父菜单对象引用（面包屑用）
  children?: TreeMenuItem[]; // 子菜单
}

3.3 Sidebar 菜单渲染模式

数据来源：menuStore.treeMenus（顶层节点作为分组，children 作为组内菜单项）

推荐使用 MenuItem 组件（无需手写菜单逻辑）：

<script setup lang="ts">
import { storeToRefs } from 'pinia';
import { useMenuStore } from '@newlifex/cube-vue/core/stores/menu';
import MenuItem from '@newlifex/cube-vue/core/components/MenuItem.vue';

const menuStore = useMenuStore();
const { treeMenus, activeMenu } = storeToRefs(menuStore);
const menuGroups = computed(() => treeMenus.value ?? []);
</script>

<template>
  <nav>
    <template v-for="group in menuGroups" :key="group.id">
      <div v-if="group.children?.length" class="menu-group">
        <div class="menu-group-title">{{ group.title || group.name }}</div>
        <MenuItem
          v-for="item in group.children"
          :key="item.id"
          :menu="item"
          :activeMenu="activeMenu"
        />
      </div>
    </template>
    <div v-if="!hasMenus" class="menu-empty">
      {{ loading ? '加载菜单中...' : '暂无菜单数据' }}
    </div>
  </nav>
</template>

MenuItem 自动处理：

• 递归渲染子菜单（含缩进）
• 展开/折叠切换
• 激活高亮（当前项 + 祖先链路）
• 图标渲染（Element Plus → SVG → 默认 Menu 图标）
• 路由跳转（调 openMenuTab() + setActiveMenu()）

如果不需要分组标题或需要自定义交互（如分组折叠），可参考 CyberLayout 的直接使用 MenuItem 方式：

<MenuItem v-for="menu in menuList" :key="menu.id" :menu="menu" :activeMenu="activeMenu" />

手写菜单（不推荐，仅当需要特殊交互时）：

3.4 Navbar 面包屑（基于 parentMenu 链）

// Navbar.vue
const activeMenu = computed(() => menuStore.activeMenu);

const breadcrumbPath = computed(() => {
  const menu = activeMenu.value;
  if (!menu) return [];
  const path: Array<{ name: string; title?: string }> = [];
  let current: TreeMenuItem | undefined = menu;
  while (current) {
    path.unshift({ name: current.name, title: current.title });
    current = current.parentMenu; // 沿 parentMenu 反向指针向上递推
  }
  return path;
});

<template>
  <nav class="breadcrumb">
    <template v-for="(item, idx) in breadcrumbPath" :key="idx">
      <span v-if="idx < breadcrumbPath.length - 1" class="bc-item">{{ item.title }}</span>
      <span v-if="idx < breadcrumbPath.length - 1" class="bc-sep">›</span>
      <span v-else class="bc-current">{{ item.title }}</span>
    </template>
  </nav>
</template>

关键点：parentMenu 是框架在构建菜单树时自动填充的反向指针，无需手动维护。

---

四、CSS Token 三层架构（完整规范）

Layer 0 — 设计原语（框架定义，布局不应重复定义）

/* 框架全局定义，布局直接引用 */
--blue-600: #2563eb;
--green-500: #22c55e;
--gray-50: #f9fafb;
--gray-100: #f3f4f6;
--gray-200: #e5e7eb;
--gray-300: #d1d5db;
--gray-400: #9ca3af;
--gray-500: #6b7280;
--gray-600: #4b5563;
--gray-700: #374151;
--gray-800: #1f2937;
--gray-900: #111827;
/* ... 更多原语 */

Layer 1 — 语义变量（框架定义，布局直接引用）

--bg-primary:      #ffffff;     /* 亮色主背景 */
--bg-secondary:    #f9fafb;     /* 亮色次背景 */
--text-primary:    #111827;
--text-secondary:  #6b7280;
--text-muted:      #9ca3af;
--border-default:  #e5e7eb;

Layer 2 — 布局专属变量（在 variables.css 中定义）

/* layouts/AuroraLayout/styles/variables.css */
:root,
[data-theme='aurora'] {
  /* 尺寸 */
  --aurora-sidebar-width: 220px;
  --aurora-nav-height:    60px;
  --aurora-content-padding: 24px;

  /* 颜色（基于 Layer 1 派生，禁止硬编码） */
  --aurora-bg:             var(--bg-primary);
  --aurora-sidebar-bg:     var(--bg-secondary);
  --aurora-nav-bg:         var(--bg-secondary);
  --aurora-text-primary:   var(--text-primary);
  --aurora-text-secondary: var(--text-secondary);
  --aurora-text-muted:     var(--text-muted);
  --aurora-border:         var(--border-default);
  --aurora-sidebar-border: var(--border-default);

  /* 品牌渐变 */
  --aurora-logo-gradient:  linear-gradient(135deg, var(--blue-600), var(--green-500));
  --aurora-primary-gradient: linear-gradient(135deg, var(--blue-600), var(--green-500));

  /* 圆角 */
  --aurora-radius-sm: 8px;
  --aurora-radius-md: 12px;

  /* 动画 */
  --aurora-transition: all 0.2s ease;
}

命名规范

---

五、目录结构规范

src/layouts/{LayoutName}/
├── index.vue              # 布局入口（组合 Sidebar + Navbar + slot）
├── Sidebar.vue            # 侧边栏（必须对接 menuStore）
├── Navbar.vue             # 顶部导航（必须对接 userStore + 框架组件）
├── styles/
│   └── variables.css      # 布局专属 CSS Token（Layer 2）
└── README.md              # 可选：布局说明文档

注意：variables.css 使用 @import 导入（非 scoped），确保变量定义在 :root 作用域，供所有布局子组件引用。

---

六、注册布局（main.ts）

// src/main.ts
import { initApp } from '@newlifex/cube-vue/core/initApp';
import '@newlifex/cube-vue/core/global.css';
import { registerLayout } from '@newlifex/cube-vue/core/composables/useLayout';
import AuroraLayout from './layouts/AuroraLayout/index.vue';

registerLayout({
  id: 'aurora',
  label: '极光蓝绿',
  icon: '◉',
  description: '极光蓝绿风格布局',
  component: AuroraLayout,
}, true);  // true = 立即切换为当前布局

initApp();

⚠️ 踩坑记录：早期尝试通过 provide(LayoutKey, ...) 注册布局，但 RootLayout.vue 只读取 useLayout().currentComponent（模块级状态），不读取 injected 值。正确方式是通过 registerLayout() 函数修改 registeredLayouts 数组。

---

七、各组件职责与代码结构

7.1 index.vue — 布局入口

职责：组合 Sidebar + Navbar + 内容区，导入 CSS 变量。

<script setup lang="ts">
import Sidebar from './Sidebar.vue';
import Navbar from './Navbar.vue';
</script>

<template>
  <div class="aurora-layout">
    <Sidebar />
    <main class="aurora-main">
      <Navbar />
      <div class="aurora-content">
        <slot></slot>
      </div>
    </main>
  </div>
</template>

<style>
@import './styles/variables.css';  /* 非 scoped，定义 :root 变量 */
</style>

<style scoped lang="scss">
.aurora-layout { display: flex; min-height: 100vh; }
.aurora-main   { margin-left: var(--aurora-sidebar-width); flex: 1; }
.aurora-content { flex: 1; padding: var(--aurora-content-padding); }
</style>

7.2 Sidebar.vue — 动态侧边栏

职责：展示 Logo + 搜索框 + 动态菜单树 + 活跃状态高亮。

关键逻辑：

• Logo：使用 <LogoBrand />，自动从 configs/config.ts 的 base.logo 和 base.title 读取
• 搜索框（可选）：使用 <SearchBar mode="box" placeholder="搜索菜单..." />，支持菜单模糊搜索
• 菜单：使用 <MenuItem> 组件（menuStore.treeMenus 动态数据），自动处理递归渲染、图标、高亮、跳转
• 底部用户区域（可选）：使用 <UserProfile variant="sidebar" dropup>，含头像/用户名/退出登录
• 加载中/无数据时显示友好提示

7.3 Navbar.vue — 顶部导航栏

职责：面包屑 + 布局/主题/模式切换 + 通知 + 用户头像下拉。

关键逻辑：

• 面包屑：沿 activeMenu.parentMenu 链向上递推
• 右侧工具栏：LayoutSwitcher + ThemeSwitcher + ModeSwitcher + NotificationBell + UserProfile
• 不直接读取 userStore，用户信息由 UserProfile 组件内部处理

---

八、常见踩坑与解决方案

---

九、验证清单

构建通过后，按以下步骤在浏览器中验证：

• 布局正确渲染（侧边栏 + 顶部栏 + 内容区）
• 侧边栏 Logo 显示配置中的 logo 图片和系统标题
• 侧边栏搜索框可搜索菜单并跳转
• 侧边栏显示动态菜单（从后端加载，非静态数据）
• 点击菜单项后高亮状态正确切换
• 菜单图标正常显示（Element Plus 图标/默认 Menu 图标）
• 路由跳转正常
• 面包屑随路由变化正确更新
• 右上角显示当前登录用户的头像/名称
• 用户头像下拉菜单有「个人资料」和「退出登录」
• 布局切换器显示（注册多个布局时）
• 主题切换器可切换主题
• 明暗模式切换正常
• 通知铃铛可点击
• 响应式：窗口缩小时侧边栏行为正常（如折叠）
• 刷新页面后布局/主题/模式状态保持

---

十、从原型 HTML 到生产组件的转换要点

如果已有设计原型（HTML/CSS），按以下步骤转换：

1. 提取设计 Token：从原型中提取颜色、间距、圆角等，映射到 CSS 变量
2. 保留三层架构：原型色值 → Layer 0 原语 / Layer 1 语义 / Layer 2 布局专属
3. 拆分组件：原型 HTML → index.vue（骨架）+ Sidebar.vue + Navbar.vue
4. 替换静态数据：原型中的示例菜单 → menuStore.treeMenus
5. 接入框架组件：原型中的按钮/图标 → LayoutSwitcher / ThemeSwitcher 等
6. 保留交互逻辑：折叠/展开/下拉等交互，参考 CyberLayout 的实现方式

---