fix: 修复主题切换后首页状态重置 + 首页 UX 优化 + 文档同步

## 根因设置页 `navigate('/settings')` 导致 React Router `/*` 的 index 路由不匹配，HomePage 被卸载重挂载，所有 useState 回到默认值。 ## 修复（6 文件） - event-bus.ts: 新增 OPEN_SETTINGS 事件 - nav-config.ts: 设置按钮 action: 'navigate' → 'button'，去路由化 - NavBar.tsx: button case 中 emit(OPEN_SETTINGS) - SettingsPage.tsx: 去路由化，改为 Modal 居中叠加 + open/onClose props，使用 antd 6.x 正确 API destroyOnHidden（非废弃的 destroyOnClose）， mask={{ closable: false }} + keyboard={false} 仅允许 X 按钮关闭 - router/index.tsx: 移除 SettingsPage 渲染 - App.tsx: 添加 SettingsPage Modal，事件驱动（与 LoginPage 模式一致） ## UX 优化（2 文件） - HomeContent.tsx: 右侧分隔条移除多余 marginLeft，左右视觉对称 - BannerCarousel.tsx: 新增关闭按钮，session 级别 useState 隐藏，不做 localStorage 持久化，确保每次启动重新展示 ## 架构原则确立 QT 多窗口模型 → Web 映射：叠加层走 Modal/Drawer + 事件总线，主页面不卸载；真正的视图切换才用 React Router。 ## 文档同步 - TODO.md: 移除已完成项详细记录，精简为未完成待办 - WORKLOG.md: 追加 2026-06-07 完整工作日志 - PROJECT.md: 更新路由/叠加层架构说明 - CHANGELOG.md: 追加 v0.0.13 条目 - ARCHITECTURE.md: 更新日期 + 新增叠加层模式章节
2026-06-05 21:03:14 +08:00
parent a8ace232a4
commit 72ec1a5459
15 changed files with 192 additions and 164 deletions
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -3,6 +3,7 @@ import { HashRouter } from 'react-router-dom';

 import { useAppContext } from './contexts/app-context';
 import { LoginPage } from './pages/login';
+import { SettingsPage } from './pages/settings';
 import { on, off, EVENTS } from './utils/event-bus';
 import { AppRoutes } from './router';

@@ -12,7 +13,12 @@ import { AppRoutes } from './router';
 * 层级：
 *   HashRouter
 *     ├── LoginPage（Modal 弹层，事件总线驱动）
- *     ├── AppRoutes（页面路由 + SettingsPage Drawer 叠加）
+ *     ├── SettingsPage（Modal 居中叠加，事件总线驱动 — 对应 QT 原版设置窗口）
+ *     ├── AppRoutes（页面路由）
+ *
+ * 设计原则（对应 QT 原版多窗口模型）：
+ *   - 叠加层（设置、公告等）→ Modal/Drawer + 事件总线，主页面不卸载
+ *   - 页面跳转 → React Router，需要跨页保持的状态放 Provider 或 localStorage
 */
 function App() {
   const { isLoggedIn } = useAppContext();
@@ -42,12 +48,25 @@ function App() {
      setLoginOpen(false);
   }, []);

+   // 设置 Drawer 状态
+   const [settingsOpen, setSettingsOpen] = useState(false);
+
+   // 监听打开设置 Drawer
+   useEffect(() => {
+      const handler = () => setSettingsOpen(true);
+      on(EVENTS.OPEN_SETTINGS, handler);
+      return () => { off(EVENTS.OPEN_SETTINGS, handler); };
+   }, []);
+
   return (
      <HashRouter>
         {/* 登录 Modal — 可关闭，关闭后主页可操作 */}
         <LoginPage open={loginOpen && !isLoggedIn} onClose={handleLoginClose} />

-         {/* 页面路由 + SettingsPage Drawer 叠加 */}
+         {/* 设置 Modal — 事件驱动，居中叠加，主页面始终挂载（对应 QT 原版独立设置窗口） */}
+         <SettingsPage open={settingsOpen} onClose={() => setSettingsOpen(false)} />
+
+         {/* 页面路由 */}
         <AppRoutes />
      </HashRouter>
   );
--- a/src/components/navbar/NavBar.tsx
+++ b/src/components/navbar/NavBar.tsx
@@ -79,6 +79,8 @@ export function NavBar() {
            case 'button':
               if (item.key === 'logout') {
                   logout();
+               } else if (item.key === 'settings') {
+                   emit(EVENTS.OPEN_SETTINGS);
               }
               break;

--- a/src/components/navbar/nav-config.ts
+++ b/src/components/navbar/nav-config.ts
@@ -99,8 +99,7 @@ const personalRight: NavItemConfig[] = [
      key: 'settings',
      label: '设置',
      iconSrc: settingsSvg,
-      action: 'navigate',
-      target: '/settings',
+      action: 'button',
      position: 'right',
   },
   {
@@ -168,8 +167,7 @@ const enterpriseRight: NavItemConfig[] = [
      key: 'settings',
      label: '设置',
      iconSrc: settingsSvg,
-      action: 'navigate',
-      target: '/settings',
+      action: 'button',
      position: 'right',
   },
   {
--- a/src/pages/home/HomeContent.tsx
+++ b/src/pages/home/HomeContent.tsx
@@ -239,10 +239,7 @@ export function HomeContent() {
            {/* 右分隔条 */}
            <div
               onMouseDown={handleDividerMouseDown('right')}
-               style={{
-                  ...dividerStyle('right'),
-                  marginLeft: 12,
-               }}
+               style={dividerStyle('right')}
               onMouseEnter={() => setHoveredDivider('right')}
               onMouseLeave={() => setHoveredDivider(null)}
            >
@@ -261,7 +258,7 @@ export function HomeContent() {
            </div>

            {/* 右列 */}
-            <div style={{ width: rightWidth, overflow: 'hidden', flexShrink: 0, marginLeft: 6 }}>
+            <div style={{ width: rightWidth, overflow: 'hidden', flexShrink: 0 }}>
               <RightPanel />
            </div>
         </div>
--- a/src/pages/home/components/BannerCarousel.tsx
+++ b/src/pages/home/components/BannerCarousel.tsx
@@ -1,10 +1,16 @@
 // ============================================================
 // BannerCarousel — 首页顶部轮播图
 // 使用 useBannerList() Hook 获取数据，组件仅负责渲染
+//
+// 关闭行为：
+//   - 关闭后当前会话不再显示（组件内 useState 驱动）
+//   - 刷新/重启应用 → state 重置 → 重新展示
+//   - 不做 localStorage 持久化，确保每次启动都可见
 // ============================================================

-import { useRef, useMemo } from 'react';
-import { Carousel, Skeleton } from 'antd';
+import { useRef, useMemo, useState } from 'react';
+import { Carousel, Skeleton, Button } from 'antd';
+import { CloseOutlined } from '@ant-design/icons';
 import type { CarouselRef } from 'antd/es/carousel';

 import { useBannerList } from '@/hooks/use-api';
@@ -22,6 +28,9 @@ export function BannerCarousel({ className }: BannerCarouselProps) {
   const carouselRef = useRef<CarouselRef>(null);
   const { data: rawBanners, loading } = useBannerList();

+   /** 当前会话是否已关闭轮播图（组件卸载即重置，下次启动重新展示） */
+   const [dismissed, setDismissed] = useState(false);
+
   // 过滤 + 排序（纯计算，无副作用）
   const banners = useMemo<Banner[]>(() => {
      if (!rawBanners) return [];
@@ -31,8 +40,8 @@ export function BannerCarousel({ className }: BannerCarouselProps) {
         .sort((a, b) => a.sort_order - b.sort_order);
   }, [rawBanners]);

-   // 无数据时不渲染
-   if (!loading && banners.length === 0) {
+   // 用户已关闭或加载完成但无数据 → 不渲染
+   if (dismissed || (!loading && banners.length === 0)) {
      return null;
   }

@@ -69,6 +78,35 @@ export function BannerCarousel({ className }: BannerCarouselProps) {
               </div>
            ))}
         </Carousel>
+
+         {/* 关闭按钮 — 右上角悬浮，半透明底色，hover 加深 */}
+         <Button
+            type="text"
+            size="small"
+            icon={<CloseOutlined />}
+            onClick={() => setDismissed(true)}
+            title="关闭轮播图"
+            style={{
+               position: 'absolute',
+               top: 8,
+               right: 8,
+               zIndex: 10,
+               color: '#fff',
+               background: 'rgba(0, 0, 0, 0.35)',
+               borderRadius: 4,
+               width: 24,
+               height: 24,
+               display: 'flex',
+               alignItems: 'center',
+               justifyContent: 'center',
+            }}
+            onMouseEnter={(e) => {
+               (e.currentTarget as HTMLButtonElement).style.background = 'rgba(0, 0, 0, 0.55)';
+            }}
+            onMouseLeave={(e) => {
+               (e.currentTarget as HTMLButtonElement).style.background = 'rgba(0, 0, 0, 0.35)';
+            }}
+         />
      </div>
   );
 }
--- a/src/pages/settings/SettingsPage.tsx
+++ b/src/pages/settings/SettingsPage.tsx
@@ -1,48 +1,47 @@
 // ============================================================
-// SettingsPage — 设置页面（路由命中 /settings 时以居中 Modal 叠加展示）
+// SettingsPage — 设置页面（Modal 居中叠加，事件驱动显隐）
 //
 // 核心设计：
-//   - 独立于 <Routes> 之外，通过 useLocation 判断是否渲染
-//   - 命中 /settings → Modal 居中弹出，首页内容保持在背景不动
-//   - 关闭 Modal → navigate(-1)，仅可通过 X 按钮关闭
-//   - destroyOnClose → 关闭即销毁 DOM，不堆内存
+//   - 通过 open/onClose props 控制显隐，不使用路由（避免主页面被卸载）
+//   - Modal 居中弹出 + 遮罩层，首页内容始终保持挂载不动
+//   - destroyOnHidden → 关闭即销毁 DOM，不堆内存
+//   - 仅可通过标题栏 X 按钮关闭（mask 不可关闭、ESC 禁用）
+//
+// 对应 QT 原版：设置窗口为独立窗口叠加在主窗口之上，主窗口不销毁
 // ============================================================

-import {Modal} from 'antd';
-import {SettingOutlined} from '@ant-design/icons';
-import {useLocation, useNavigate} from 'react-router-dom';
-import {useAppContext} from '@/contexts/app-context';
-import {ThemeSetting} from './ThemeSetting';
-import {StoragePathSetting} from './StoragePathSetting';
-import {SystemInfoSetting} from './SystemInfoSetting';
-import {UpdateSetting} from './UpdateSetting';
+import { Modal } from 'antd';
+import { SettingOutlined } from '@ant-design/icons';
+import { useAppContext } from '@/contexts/app-context';
+import { ThemeSetting } from './ThemeSetting';
+import { StoragePathSetting } from './StoragePathSetting';
+import { SystemInfoSetting } from './SystemInfoSetting';
+import { UpdateSetting } from './UpdateSetting';

-export function SettingsPage() {
-    const location = useLocation();
-    const navigate = useNavigate();
-    const {edition} = useAppContext();
-    const open = location.pathname === '/settings';
+interface SettingsPageProps {
+   open: boolean;
+   onClose: () => void;
+}
+
+export function SettingsPage({ open, onClose }: SettingsPageProps) {
+    const { edition } = useAppContext();

    return (
        <Modal
            open={open}
            width={480}
-            onCancel={() => navigate(-1)}
+            onCancel={onClose}
            destroyOnHidden={true}
-            mask={
-                {
-                    closable: false
-                }
-            }
+            mask={{ closable: false }}
            keyboard={false}
            footer={null}
            title={
                <span className="flex items-center gap-2">
-               <SettingOutlined />
-               设置
-            </span>
+                    <SettingOutlined />
+                    设置
+                </span>
            }
-            styles={{body: {padding: 0, maxHeight: '70vh', overflow: 'auto'}}}
+            styles={{ body: { padding: 0, maxHeight: '70vh', overflow: 'auto' } }}
        >
            <div className="flex flex-col gap-4 p-4">
                <ThemeSetting />
--- a/src/router/index.tsx
+++ b/src/router/index.tsx
@@ -2,25 +2,20 @@
 // AppRoutes — 应用路由配置（由 App.tsx 在 HashRouter 内使用）
 //
 // 核心设计：
-//   - SettingsPage 在 <Routes> 外部，路由命中时以 Drawer 叠加首页
+//   - Settings 等叠加层通过事件总线驱动 Drawer/Modal 展示，不走路由
 //   - 首页始终保持挂载，不会因导航而卸载
 // ============================================================

 import { Routes, Route } from 'react-router-dom';
 import { Layout } from '@/components/Layout';
 import { HomePage } from '@/pages/home/HomePage';
-import { SettingsPage } from '@/pages/settings';

 export function AppRoutes() {
   return (
-      <>
-         <Routes>
-            <Route path="/*" element={<Layout />}>
-               <Route index element={<HomePage />} />
-            </Route>
-         </Routes>
-         {/* 独立于 Routes：根据 URL /settings 自动显隐 Drawer */}
-         <SettingsPage />
-      </>
+      <Routes>
+         <Route path="/*" element={<Layout />}>
+            <Route index element={<HomePage />} />
+         </Route>
+      </Routes>
   );
 }
--- a/src/utils/event-bus.ts
+++ b/src/utils/event-bus.ts
@@ -71,4 +71,6 @@ export const EVENTS = {
   LOGOUT: 'auth:logout',
   /** 任务提交成功（→ 刷新任务列表） */
   TASK_SUBMITTED: 'task:submitted',
+   /** 打开设置 Drawer（导航栏"设置"按钮点击） */
+   OPEN_SETTINGS: 'settings:open',
 } as const;