| 1 | # Layout 布局组件文档 |
| 2 | |
| 3 | 本目录包含应用 App Shell 与全局布局私有组件。这里的组件默认服务布局、侧边栏、移动导航、全局 Provider 或全局挂载弹窗，不作为普通页面的共享组件目录。 |
| 4 | |
| 5 | ## 目录结构 |
| 6 | |
| 7 | | 目录/文件 | 描述 | |
| 8 | | ---------------------- | ---------------------------------------------------------------------------------------------------- | |
| 9 | | `LayoutSidebar/` | 桌面端左侧侧边栏组件。 | |
| 10 | | `MobileNav/` | 移动端底部导航组件（BottomBar + 抽屉）。 | |
| 11 | | `MainContent/` | 页面主滚动容器，主滚动元素为 `id="main-content"`。 | |
| 12 | | `LoginDialog/` | 全局登录弹窗，状态在 `src/store/login-dialog`。 | |
| 13 | | `SettingsModal/` | 全局设置弹窗，仅由 layout/Provider 挂载；跨页面控制状态放在 `src/store/settingsModal.ts`。 | |
| 14 | | `ConfigManagerDialog/` | 全局配置管理弹窗，仅由 layout/Provider 挂载；跨页面控制状态放在 `src/store/configManagerDialog.ts`。 | |
| 15 | | `HomeComponents/` | 首页布局入口组件。 | |
| 16 | | `shared/` | 布局内部共享 hooks、工具与展示组件。 | |
| 17 | | `Providers.tsx` | 全局 Provider 包装组件。 | |
| 18 | | `routerData.tsx` | 路由/导航数据配置（含图标）。 | |
| 19 | | `layout.utils.ts` | 布局工具函数。 | |
| 20 | | `images/` | 布局相关图片资源。 | |
| 21 | |
| 22 | ## 放置边界 |
| 23 | |
| 24 | - 可以放：侧边栏、移动导航、登录弹窗、设置弹窗、通知面板、全局 Provider、布局私有工具。 |
| 25 | - 可以放：只由 layout 挂载、不被普通页面直接复用的全局弹窗 UI。 |
| 26 | - 不要放：普通页面之间复用的业务组件；这类组件应放到 `src/components/<业务域>/`。 |
| 27 | - 不要放：页面私有组件；这类组件应放到对应页面目录的 `components/`。 |
| 28 | - 普通页面如果需要打开 layout 弹窗，应通过 `src/store/` 中立状态或事件协作，不要 import `src/app/layout` 内部组件。 |
| 29 | |
| 30 | ## LayoutSidebar - 桌面端侧边栏 |
| 31 | |
| 32 | - Logo 区域。 |
| 33 | - 主导航菜单使用 `routerData` 数据和图标。 |
| 34 | - 底部功能区包含频道入口、插件入口、设置、用户头像/登录按钮。 |
| 35 | - 桌面端（md 及以上）显示，移动端隐藏。 |
| 36 | |
| 37 | ## MobileNav - 移动端导航 |
| 38 | |
| 39 | - 固定底部栏展示开源版核心路由。 |
| 40 | - 抽屉式导航菜单和未登录登录按钮。 |
| 41 | - 移动端（md 以下）显示，桌面端隐藏。 |
| 42 | |
| 43 | ## SettingsModal - 全局设置弹窗 |
| 44 | |
| 45 | 设置弹窗由 `Providers` 挂载，页面和业务组件通过 `useSettingsModalStore` 打开或关闭。 |
| 46 | |
| 47 | ```tsx |
| 48 | import { useSettingsModalStore } from '@/store/settingsModal' |
| 49 | ``` |
| 50 | |
| 51 | - UI 实现在 `src/app/layout/SettingsModal/`。 |
| 52 | - 状态与 `SettingsTab` 类型在 `src/store/settingsModal.ts`，避免页面直接依赖 layout 内部实现。 |
| 53 | - 开源版只保留 profile / general 设置入口，不恢复闭源订阅、钱包、API Key、工单等设置页。 |
| 54 | |
| 55 | ## ConfigManagerDialog - 全局配置管理弹窗 |
| 56 | |
| 57 | 配置管理弹窗由 `Providers` 挂载，侧边栏和请求错误提示通过 `useConfigManagerDialogStore` 打开。 |
| 58 | |
| 59 | ```tsx |
| 60 | import { useConfigManagerDialogStore } from '@/store/configManagerDialog' |
| 61 | ``` |
| 62 | |
| 63 | - UI 实现在 `src/app/layout/ConfigManagerDialog/`。 |
| 64 | - 弹框内将后端配置对象转换为可编辑表单，不直接暴露 JSON 编辑。 |
| 65 | - 保存后可重启服务，并通过账号列表接口确认服务恢复。 |
| 66 | |
| 67 | ## routerData - 导航数据配置 |
| 68 | |
| 69 | 定义导航菜单数据，包含图标、路径和可见性控制。 |
| 70 | |
| 71 | ```tsx |
| 72 | import { routerData, visibleRouterData } from '@/app/layout/routerData' |
| 73 | ``` |
| 74 | |
| 75 | - `routerData`：完整导航数据。 |
| 76 | - `visibleRouterData`：开源版可见导航数据。 |
| 77 | - 新增路由时同步检查 `src/middleware.ts` 是否需要白名单。 |
| 78 | |
| 79 | ## Providers - 全局 Provider |
| 80 | |
| 81 | ```tsx |
| 82 | import { Providers } from '@/app/layout/Providers' |
| 83 | ;<Providers lng={lng}>{children}</Providers> |
| 84 | ``` |
| 85 | |
| 86 | - 注入平台元数据初始值、登录弹窗、设置弹窗、插件发布浮窗、Toast 等全局能力。 |
| 87 | - 集成微信/支付宝内置浏览器蒙版 `WechatBrowserOverlay`。 |
| 88 |