ow

uniapp/youjiala/src/md/theme.md

@@ -0,0 +1,82 @@
+# uView Pro 主题系统与渐变底接线
+
+适用范围：`src/common/uview-pro.theme.ts`（主题定义）、`src/main.ts`（注册）、`src/composables/useThemeGradient.ts`（渐变派生）、`src/pages/tab/mine.vue`（切换入口）、文件页等使用主题渐变底的页面。
+路由与权限见 [page-routing.md](./page-routing.md)、[permission.md](./permission.md)；环境变量见 [environment.md](./environment.md)。
+
+---
+
+## 1. 主题从哪来：定义 → 注册 → 使用
+
+- **定义**：`src/common/uview-pro.theme.ts` 导出主题数组，每项 `{ name, label, color }`；`color` 必含 `primary/error/warning/success/info`，`*Light/*Dark/*Disabled` 可缺（库有 `applyColorFallbacks` 自动派生）。当前四套：`purple 霞光紫 / green 清翠绿 / orange 暖阳橙 / dark 午夜蓝`。
+- **注册**：`main.ts` 装插件时一次性传入，改默认主题或增删主题都只动这两个文件：
+
+```text
+app.use(uViewPro, {
+  theme: {
+    themes,                 // 来自 common/uview-pro.theme.ts
+    defaultTheme: "green",  // 冷启动且 Storage 无记录时用它
+    defaultDarkMode: "light",
+  },
+  ...
+});
+```
+
+- **使用**：组件配色走 CSS 变量 `--u-type-primary`（注入在 `:root`），或 JS 里读 `useTheme().currentTheme`。
+
+## 2. 切换与持久化：不要自建 store
+
+```text
+const { themes, currentTheme, setTheme, darkMode, setDarkMode, isInDarkMode } = useTheme();
+setTheme("orange");          // 切换 + 写 Storage('uview-pro-theme')
+setDarkMode("auto");         // 'auto' | 'light' | 'dark'，写 Storage('uview-pro-dark-mode')
+```
+
+要点（均为库行为，实测确认）：
+
+- `useTheme()` 的 `currentTheme/darkMode` 是**包级单例 ref**：任何页面调用拿到的都是同一份，mine 页切主题、文件页渐变即时联动，**无需刷新、无需事件总线**；
+- 持久化由库自动完成（Storage 键 `uview-pro-theme`、`uview-pro-dark-mode`），冷启动 `initTheme` 自动恢复，**页面层不要再包一层 Pinia store**；
+- `themes` 列表 = **内置 defaultThemes 与自定义主题合并**（`config-provider.normalizeThemes` 的 `mergeThemes`），所以 mine 页会多渲染一个出厂「默认蓝 #2979ff」色点——这是库设计，不是 bug；只想要自定义 4 套的话按 `name` 过滤即可。
+
+## 3. 深色模式的生效层级
+
+`setDarkMode("dark")` 实测：`html` 类切到 `u-theme-dark`、`body` 背景变暗、`--u-type-primary` 重算为暗色降饱和变体。
+
+已知小瑕疵：`.u-config-provider` 元素自身的 `u-theme-light` 类**不跟随**切换（uView Pro 内部响应性缺口，仅该类，不影响变量与 html/body 层生效）。
+
+注意：本项目自定义样式大量写死色值（文件页白卡、`#2b8fff` 强调色等），**页面不会自动变暗**；要让整页跟随暗黑，需要把关键色逐个改走 `--u-type-*` 变量，属独立改造任务。
+
+## 4. 渐变底：useThemeGradient（多页共用）
+
+文件页头部各块（navbar/面包屑/搜索/快捷入口/分类条）已透明化，页面底用「主题色混白」的纵向渐变承接主题色。派生逻辑在 `src/composables/useThemeGradient.ts`，规则：
+
+- `mixWithWhite(primary, ratio)`：主题 primary 按占比混白，`c*ratio + 255*(1-ratio)`，输出 `rgb()`；
+- 三段停靠：顶部 25% 浓度 → 40% 高度 14% → 底部 5%（`linear-gradient(180deg, ...)`），保证任意主题都是同色系浅底，白卡与文字对比天然保持；
+- 浓度可覆盖：`useThemeGradient({ top: 0.15, middle: 0.08, bottom: 0.03 })`。
+
+新页面接入只要两行：
+
+```text
+const { themeBackground } = useThemeGradient();
+<!-- 模板根节点 -->
+<view class="xxx-page" :style="{ background: themeBackground }">
+```
+
+实测对照（顶部 = primary 混白 25%）：green `#059669` → `rgb(193,229,218)`；purple `#7c3aed` → `rgb(222,206,251)`；dark `#0b3d91` → `rgb(194,207,228)`。
+
+历史备注：文件页渐变曾经是写死的 `#b8e5fd → #eaf7fe`（蓝色系），不随主题；现已全部由本 composable 接管，**不要再在页面里加固定渐变覆盖**。
+
+## 5. mine 页设置入口
+
+`src/pages/tab/mine.vue` 两张卡片：
+
+- **主题颜色**：遍历 `useTheme().themes` 渲染色点（背景取 `theme.color.primary`，选中打勾），点击 `setTheme(theme.name)`；
+- **深色模式**：跟随系统/浅色/深色三段胶囊，点击 `setDarkMode(mode)`；`DarkMode` 类型顶层未导出，页面内以同构字面量联合 `"auto" | "light" | "dark"` 声明。
+
+词条在语言包 `MinePage` 块（`src/locale/lang/zh-CN.json` / `en-US.json`）；主题 `label`（霞光紫等）来自 `uview-pro.theme.ts`，是中文写死的——若要随语言切换需给主题加双 label 字段，暂未做。
+
+## 6. 新增/修改主题的固定步骤
+
+1. 在 `common/uview-pro.theme.ts` 数组增删一项（`name` 必须全局唯一，是 Storage 持久化的键值）；
+2. 如需换默认主题，改 `main.ts` 的 `defaultTheme`；
+3. 无需动 mine 页——色点列表由 `themes` 响应式驱动；
+4. 验证：`npx vue-tsc --noEmit -p tsconfig.json` 退出码 0 + 浏览器实测 mine 切换 → 文件页渐变联动 → F5 持久化。