feat: 主题切换性能优化 — View Transitions API + 0.15s 统一过渡 + 设置页增强

【问题】桌面端（Electron）切换主题时颜色变化速度不一致、明显卡顿。根因分析（4 轮迭代）： 1. 过渡时长不统一（body 0.3s / 组件 0.15s）→ 统一到 0.2s 2. antd CSS-in-JS 标签替换导致瞬间变色 → 尝试 cssVar（无效，仍走标签替换） 3. applyHtmlTheme 在 updater 回调中执行，与 antd CSS 变更不同帧 → 移入 useLayoutEffect 4. html * 全局过渡在 Electron 中为数千 DOM 节点同步插值 → 合成器掉帧终极方案：View Transitions API（GPU 合成器 1 次 cross-fade 替代 N 个 CSS 过渡） + 精准 CSS 过渡覆盖 ~80 个 antd 容器类（回退方案）【修改】 ThemeProvider.tsx — 核心重构 - applyHtmlTheme 从 setIsDark updater → useLayoutEffect([isDark]) 确保自定义 CSS 变量与 antd CSS-in-JS 在同一次 React 提交中生效 - View Transitions API：document.startViewTransition + flushSync GPU 合成器截取旧/新两帧做单次 cross-fade，消除多元素插值卡顿 - 浏览器不支持时自动回退到 CSS transition 方案 globals.css — 过渡策略 - body: 0.3s ease → 0.15s linear - View Transitions 动画：::view-transition-old/new(root) 0.15s linear - ~80 个 antd 容器类精准过渡（Layout/Card/Modal/Table/Input/ Select/Picker/Menu/Tabs/Tag/Alert/Empty/Result/Skeleton 等）按功能分组：布局 → 表格 → 表单 → 导航 → 反馈不覆盖交互组件自有 transition（Button/Switch/Slider 等） linear 替代 ease — 匀速插值，桌面应用更利落 Layout.tsx / HomeContent.tsx / LeftPanel.tsx / ModelSelector.tsx - 过渡参数对齐：全部 0.2s → 0.15s linear SettingsPage.tsx — 用户体验 - Modal 取消 keyboard={false}，Esc 键可关闭 - macOS：关闭按钮移至标题左侧（遵循 macOS HIG） - afterClose 中 blur 当前焦点元素，防止聚焦跳到导航栏【文档】 CHANGELOG.md — 新增 0.0.15 版本记录 CLAUDE.md — 新增主题系统架构章节（双轨颜色体系 / 时序 / 过渡策略）
2026-06-09 11:02:40 +08:00
parent 59059caae7
commit eb12248a62
12 changed files with 356 additions and 128 deletions
--- a/src/components/Layout.tsx
+++ b/src/components/Layout.tsx
@@ -13,7 +13,7 @@ export function Layout({ children }: { children: ReactNode }) {

   return (
      <div
-         className="h-screen flex flex-col transition-colors duration-300"
+         className="h-screen flex flex-col transition-colors duration-150"
         style={{ background: token.colorBgLayout }}
      >
         <BannerCarousel />
--- a/src/components/ThemeProvider.tsx
+++ b/src/components/ThemeProvider.tsx
@@ -1,8 +1,14 @@
 // ============================================================
 // ThemeProvider — 主题 Provider 组件
+//
+// 桌面端（Electron）使用 View Transitions API 驱动主题切换：
+// GPU 合成器截取旧/新两帧做一次 cross-fade，替代 80+ 个
+// 独立 CSS 过渡，消除 Electron Chromium 的合成器卡顿。
+// 浏览器不支持时回退到 CSS transition 方案。
 // ============================================================

-import { useState, useEffect, useCallback, type ReactNode } from 'react';
+import { useState, useEffect, useLayoutEffect, useCallback, type ReactNode } from 'react';
+import { flushSync } from 'react-dom';
 import { ConfigProvider } from 'antd';
 import zhCN from 'antd/locale/zh_CN';

@@ -20,33 +26,66 @@ interface ThemeProviderProps {
   children: ReactNode;
 }

+/** 检测 View Transitions API 是否可用（Chromium 111+，Electron 28+） */
+function supportsViewTransition(): boolean {
+   return typeof document !== 'undefined' && 'startViewTransition' in document;
+}
+
 export function ThemeProvider({ children }: ThemeProviderProps) {
   const [isDark, setIsDark] = useState<boolean>(readStoredTheme);

-   // 挂载时同步
-   useEffect(() => {
+   useLayoutEffect(() => {
      applyHtmlTheme(isDark);
-   }, []); // eslint-disable-line react-hooks/exhaustive-deps
+   }, [isDark]);

   const toggleTheme = useCallback(() => {
-      setIsDark((prev) => {
-         const next = !prev;
-         writeStoredTheme(next);
-         applyHtmlTheme(next);
-         return next;
-      });
+      if (supportsViewTransition()) {
+         // View Transitions API：GPU 合成器 cross-fade，1 个动画替代 N 个 CSS 过渡
+         document.startViewTransition(() => {
+            flushSync(() => {
+               setIsDark((prev) => {
+                  const next = !prev;
+                  writeStoredTheme(next);
+                  return next;
+               });
+            });
+         });
+      } else {
+         // 回退：普通 React 状态更新 + CSS transition
+         setIsDark((prev) => {
+            const next = !prev;
+            writeStoredTheme(next);
+            return next;
+         });
+      }
   }, []);

   const setLight = useCallback(() => {
-      setIsDark(false);
-      writeStoredTheme(false);
-      applyHtmlTheme(false);
+      if (supportsViewTransition()) {
+         document.startViewTransition(() => {
+            flushSync(() => {
+               setIsDark(false);
+               writeStoredTheme(false);
+            });
+         });
+      } else {
+         setIsDark(false);
+         writeStoredTheme(false);
+      }
   }, []);

   const setDark = useCallback(() => {
-      setIsDark(true);
-      writeStoredTheme(true);
-      applyHtmlTheme(true);
+      if (supportsViewTransition()) {
+         document.startViewTransition(() => {
+            flushSync(() => {
+               setIsDark(true);
+               writeStoredTheme(true);
+            });
+         });
+      } else {
+         setIsDark(true);
+         writeStoredTheme(true);
+      }
   }, []);

   // 监听系统主题变化（仅用户从未手动切换时跟随）
@@ -56,7 +95,6 @@ export function ThemeProvider({ children }: ThemeProviderProps) {
         const stored = localStorage.getItem(STORAGE_KEY);
         if (stored === null) {
            setIsDark(e.matches);
-            applyHtmlTheme(e.matches);
         }
      };
      mq.addEventListener('change', handleChange);
--- a/src/pages/home/HomeContent.tsx
+++ b/src/pages/home/HomeContent.tsx
@@ -211,7 +211,7 @@ export function HomeContent() {
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'center',
-         transition: 'background 0.2s ease',
+         transition: 'background 0.15s linear',
      };
   };

@@ -283,7 +283,7 @@ export function HomeContent() {
                              : hoveredDivider === 'left'
                                  ? token.colorPrimary
                                  : token.colorBorder,
-                          transition: 'background 0.2s ease',
+                          transition: 'background 0.15s linear',
                       }} />
                    </div>
                 </>
@@ -311,7 +311,7 @@ export function HomeContent() {
                       : hoveredDivider === 'right'
                           ? token.colorPrimary
                           : token.colorBorder,
-                   transition: 'background 0.2s ease',
+                   transition: 'background 0.15s linear',
                }} />
             </div>

--- a/src/pages/home/components/LeftPanel.tsx
+++ b/src/pages/home/components/LeftPanel.tsx
@@ -150,7 +150,7 @@ export function LeftPanel() {
               display: 'flex',
               alignItems: 'center',
               justifyContent: 'center',
-               transition: 'background 0.2s ease',
+               transition: 'background 0.15s linear',
               zIndex: 10,
            }}
            onMouseEnter={() => setHovered(true)}
@@ -166,7 +166,7 @@ export function LeftPanel() {
                  : isHovered
                     ? token.colorPrimary
                     : token.colorBorder,
-               transition: 'background 0.2s ease',
+               transition: 'background 0.15s linear',
            }} />
         </div>

--- a/src/pages/home/components/ModelSelector.tsx
+++ b/src/pages/home/components/ModelSelector.tsx
@@ -68,7 +68,7 @@ function ModelItem({ model, isSelected, onSelect }: ModelItemProps) {
                alignItems: 'center',
                justifyContent: 'space-between',
                gap: 8,
-                transition: 'background 0.15s ease, border-color 0.15s ease, opacity 0.15s ease',
+                transition: 'background 0.15s linear, border-color 0.15s linear, opacity 0.15s linear',
            }}
        >
            <Text
--- a/src/pages/settings/SettingsPage.tsx
+++ b/src/pages/settings/SettingsPage.tsx
@@ -5,14 +5,17 @@
 //   - 通过 open/onClose props 控制显隐，不使用路由（避免主页面被卸载）
 //   - Modal 居中弹出 + 遮罩层，首页内容始终保持挂载不动
 //   - destroyOnHidden → 关闭即销毁 DOM，不堆内存
-//   - 仅可通过标题栏 X 按钮关闭（mask 不可关闭、ESC 禁用）
+//   - Esc 键可关闭（跨平台统一）
+//   - macOS：关闭按钮移至标题左侧（遵循 macOS HIG）
 //
 // 对应 QT 原版：设置窗口为独立窗口叠加在主窗口之上，主窗口不销毁
 // ============================================================

+import { useCallback } from 'react';
 import { Modal } from 'antd';
-import { SettingOutlined } from '@ant-design/icons';
+import { SettingOutlined, CloseOutlined } from '@ant-design/icons';
 import { useAppContext } from '@/contexts/app-context';
+import { isMacOS } from '@/utils/platform';
 import { ThemeSetting } from './blocks/ThemeSetting';
 import { StoragePathSetting } from './blocks/StoragePathSetting';
 import { SystemInfoSetting } from './blocks/SystemInfoSetting';
@@ -26,18 +29,31 @@ interface SettingsPageProps {

 export function SettingsPage({ open, onClose }: SettingsPageProps) {
   const { edition } = useAppContext();
+   const isMac = isMacOS();
+
+   // 关闭后移除焦点，避免跑到导航栏设置按钮上
+   const handleAfterClose = useCallback(() => {
+      (document.activeElement as HTMLElement)?.blur();
+   }, []);

   return (
      <Modal
         open={open}
         width={480}
         onCancel={onClose}
+         afterClose={handleAfterClose}
         destroyOnHidden={true}
         mask={{ closable: false }}
-         keyboard={false}
+         closable={!isMac}
         footer={null}
         title={
            <span className="flex items-center gap-2">
+               {isMac && (
+                  <CloseOutlined
+                     onClick={onClose}
+                     className="cursor-pointer text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
+                  />
+               )}
               <SettingOutlined />
               设置
            </span>
--- a/src/theme/globals.css
+++ b/src/theme/globals.css
@@ -168,8 +168,125 @@ body {
   background-color: var(--color-bg-base);
   min-height: 100vh;
   transition:
-      background-color 0.3s ease,
-      color 0.3s ease;
+      background-color 0.15s linear,
+      color 0.15s linear;
+}
+
+/* ============================================================
+ * View Transitions API — GPU 合成器驱动的主题切换动画
+ * 替代 80+ 个独立 CSS 过渡，单次 cross-fade 消除 Electron 卡顿。
+ * 仅在 Chromium 111+（Electron 28+）生效，其他浏览器回退 CSS 过渡。
+ * ============================================================ */
+
+::view-transition-old(root),
+::view-transition-new(root) {
+   animation-duration: 0.15s;
+   animation-timing-function: linear;
+}
+
+/* ============================================================
+ * 主题切换过渡 — 精准覆盖大面积视觉容器，避免 * 全局选择器
+ * 在 Electron 中为数千个 DOM 节点同时启动过渡造成卡顿。
+ *
+ * 策略：
+ *   1. 容器/布局组件（Card / Modal / Layout / Drawer 等）
+ *   2. 表格 & 列表（Table / List / Timeline）
+ *   3. 表单控件（Input / Select / Picker）
+ *   4. 导航 & 标签（Menu / Tabs / Tag / Breadcrumb）
+ *   5. 反馈 & 展示（Alert / Empty / Result / Statistic / Skeleton）
+ *
+ * 不覆盖交互组件自有 transition（Button / Switch / Slider 等
+ * 均使用 transition: all，特异性更高不受影响）。
+ * ============================================================ */
+
+/* —— 布局 & 容器 —— */
+body,
+.ant-layout,
+.ant-layout-header,
+.ant-layout-sider,
+.ant-layout-content,
+.ant-card,
+.ant-card-head,
+.ant-card-body,
+.ant-card-actions,
+.ant-modal-content,
+.ant-modal-header,
+.ant-modal-body,
+.ant-modal-footer,
+.ant-drawer-content,
+.ant-drawer-header,
+.ant-drawer-body,
+.ant-drawer-footer,
+
+/* —— 表格 & 列表 —— */
+.ant-table,
+.ant-table-thead > tr > th,
+.ant-table-tbody > tr > td,
+.ant-table-tbody > tr:hover > td,
+.ant-list,
+.ant-list-item,
+.ant-timeline-item,
+.ant-transfer-list,
+.ant-tree-node-content-wrapper,
+
+/* —— 表单控件 —— */
+.ant-input,
+.ant-input-affix-wrapper,
+.ant-select-selector,
+.ant-select-dropdown,
+.ant-picker,
+.ant-picker-input,
+.ant-picker-dropdown,
+.ant-picker-panel-container,
+.ant-input-number,
+.ant-input-number-input,
+.ant-radio-button-wrapper,
+.ant-radio-group,
+.ant-checkbox-wrapper,
+.ant-segmented,
+.ant-segmented-item,
+.ant-upload-drag,
+.ant-upload-list-item,
+
+/* —— 导航 & 标签 —— */
+.ant-menu,
+.ant-menu-item,
+.ant-menu-submenu-title,
+.ant-tabs-nav,
+.ant-tabs-nav-list,
+.ant-tabs-tab,
+.ant-tabs-content,
+.ant-tag,
+.ant-breadcrumb,
+.ant-pagination-item,
+.ant-dropdown-menu,
+
+/* —— 反馈 & 展示 —— */
+.ant-alert,
+.ant-empty,
+.ant-result,
+.ant-statistic,
+.ant-statistic-content,
+.ant-badge,
+.ant-avatar,
+.ant-divider,
+.ant-skeleton,
+.ant-skeleton-input,
+.ant-skeleton-button,
+.ant-notification-notice,
+.ant-message-notice-content,
+.ant-popover-inner,
+.ant-tooltip-inner,
+.ant-collapse,
+.ant-collapse-item,
+.ant-collapse-header,
+.ant-collapse-content-box,
+.ant-descriptions-item-container {
+   transition:
+      color 0.15s linear,
+      background-color 0.15s linear,
+      border-color 0.15s linear,
+      box-shadow 0.15s linear;
 }

 #root {