@hlw-uni/mp-vue 2.1.56 → 2.1.58

package/src/composables/theme/appearance.ts

@@ -11,16 +11,26 @@
  * - 用 `var(--border-color-light)` 代替硬编码 `#f1f5f9`
  */
 
+/** 外观模式选项类型：浅色模式、深色模式、跟随系统 */
 export type Appearance = "light" | "dark" | "auto";
+
+/** 实际生效的外观模式：仅浅色或深色 */
 export type AppearanceMode = "light" | "dark";
 
+/**
+ * 外观预设配置接口。
+ */
 export interface AppearancePreset {
+    /** 选项值 */
     value: Appearance;
+    /** 选项展示名称 */
     label: string;
 }
 
+/** 存储外观设置的 LocalStorage 键名 */
 export const APPEARANCE_KEY = "hlw_appearance";
 
+/** 预设外观模式列表，常供设置页渲染选择器使用 */
 export const APPEARANCE_PRESETS: AppearancePreset[] = [
     { value: "light", label: "浅色模式" },
     { value: "dark", label: "深色模式" },
@@ -67,12 +77,17 @@ const DARK_VARS: Record<string, string> = {
     "--shadow-card": "0 4rpx 16rpx rgba(0, 0, 0, 0.35)",
 };
 
+/** 不同外观模式的 CSS 变量映射 */
 export const APPEARANCE_VAR_MAP: Record<AppearanceMode, Record<string, string>> = {
     light: LIGHT_VARS,
     dark: DARK_VARS,
 };
 
-/** 读取用户设置的外观（light/dark/auto），默认 auto */
+/**
+ * 读取用户设置的外观配置（light / dark / auto）。
+ * 默认返回 'auto'。
+ * @returns 设定的外观模式类型
+ */
 export function getCurrentAppearance(): Appearance {
     try {
         const v = uni.getStorageSync(APPEARANCE_KEY);
@@ -81,7 +96,12 @@ export function getCurrentAppearance(): Appearance {
     return "auto";
 }
 
-/** 将 auto 解析为具体的 light/dark，依据系统主题 */
+/**
+ * 将 auto 设置或用户选择解析为具体的 light/dark 实际模式。
+ * 当为 auto 时，将读取系统当前的配色偏好。
+ * @param appearance 输入的外观配置
+ * @returns 解析后最终生效的外观模式 (light 或 dark)
+ */
 export function resolveAppearance(appearance: Appearance): AppearanceMode {
     if (appearance === "light" || appearance === "dark") return appearance;
     try {
@@ -91,12 +111,19 @@ export function resolveAppearance(appearance: Appearance): AppearanceMode {
     return "light";
 }
 
-/** 当前实际生效的模式（light 或 dark） */
+/**
+ * 获取当前实际生效的外观模式 (light 或 dark)。
+ * 自动根据用户偏好及系统主题进行判定。
+ * @returns 实际生效的外观模式
+ */
 export function getCurrentAppearanceMode(): AppearanceMode {
     return resolveAppearance(getCurrentAppearance());
 }
 
-/** 当前外观对应的 CSS 变量 */
+/**
+ * 获取当前外观对应的 CSS 变量映射表。
+ * @returns 包含各 CSS 变量名与对应颜色值键值对
+ */
 export function getCurrentAppearanceVars(): Record<string, string> {
     return APPEARANCE_VAR_MAP[getCurrentAppearanceMode()];
 }

package/src/composables/theme/font.ts

@@ -1,12 +1,26 @@
+/**
+ * 字体大小缩放档位类型。
+ * 从较小到特大，共 7 个档位。
+ */
 export type FontScale = "small" | "compact" | "normal" | "medium" | "large" | "xlarge" | "xxlarge";
 
+/**
+ * 字体大小配置预设接口。
+ */
 export interface FontPreset {
+    /** 档位名称 */
     label: string;
+    /** 该档位对应的全部 CSS 字号变量及对应尺寸 */
     vars: Record<string, string>;
 }
 
+/** 存储字体字号档位设置的 LocalStorage 键名 */
 export const FONT_SCALE_KEY = "hlw_font_scale";
 
+/**
+ * 字体档位对应的尺寸变量预设表。
+ * 每个档位定义了从超小 (--font-xs) 到超大 (--font-xl) 的响应式字号。
+ */
 export const FONT_PRESETS: Record<FontScale, FontPreset> = {
     small: {
         label: "较小",
@@ -59,6 +73,11 @@ export const FONT_PRESETS: Record<FontScale, FontPreset> = {
     },
 };
 
+/**
+ * 获取当前用户配置的字体字号缩放档位。
+ * 默认返回 'normal'。
+ * @returns 字体档位
+ */
 export function getCurrentFontScale(): FontScale {
     try {
         const v = uni.getStorageSync(FONT_SCALE_KEY);
@@ -67,6 +86,10 @@ export function getCurrentFontScale(): FontScale {
     return "normal";
 }
 
+/**
+ * 获取当前字体字号档位所映射的 CSS 变量表。
+ * @returns CSS 变量名与具体字号的键值对
+ */
 export function getCurrentFontVars(): Record<string, string> {
     return FONT_PRESETS[getCurrentFontScale()].vars;
 }

package/src/composables/theme/index.ts

@@ -11,10 +11,12 @@ import { getCurrentThemeVars } from "./palette";
 export const THEME_CHANGE_EVENT = "hlw:theme-change";
 
 /**
- * 只注入运行时配置变量（字号档位、主题色）。
- *
+ * 构建仅注入运行时配置变量（字号档位、主题色）的行内样式字符串。
+ * 
  * 页面背景、卡片色、文字色、边框色等业务视觉变量统一由项目全局 CSS
  * （static/css/style.scss）控制，避免 page-meta 运行时样式覆盖业务侧配置。
+ * 
+ * @returns 扁平化后的 CSS 变量样式属性字符串
  */
 export function buildThemeStyle(): string {
     return varsToStyle({
@@ -23,18 +25,32 @@ export function buildThemeStyle(): string {
     });
 }
 
+/**
+ * 将 CSS 键值对对象平铺拼接为 CSS inline style 格式字符串。
+ */
 function varsToStyle(vars: Record<string, string>): string {
     return Object.entries(vars).map(([key, value]) => `${key}:${value}`).join(";") + ";";
 }
 
 /**
- * 获取主题样式字符串，用于注入 <page-meta :page-style>。
+ * 获取及监听主题与字号变化，返回可注入到 `<page-meta :page-style="themePageStyle">` 的计算属性。
  *
- * 实现走 pinia store 响应式：store.scale / primaryColor 任一变化
- * → computed 重算 → page-meta 自动 setData。
+ * 实现基于 pinia store 响应式：当 store 中的字号档位或主题色发生改变时，
+ * 触发计算属性重算并由 Vue 自动更新至 `<page-meta>` 的 setData 接口。
  *
- * 注：早期版本用 uni.$emit + onMounted+uni.$on 事件总线驱动，在 vue3 + 小程序部分
- * 基础库下 emit 后 ref 不响应（导致字号 / 主题色切换不生效）。已改成响应式驱动。
+ * @returns 包含 `themePageStyle` 计算属性的对象
+ * 
+ * @example
+ * ```vue
+ * <template>
+ *   <page-meta :page-style="themePageStyle" />
+ *   <view class="container">...</view>
+ * </template>
+ * 
+ * <script setup>
+ * const { themePageStyle } = useThemePageStyle();
+ * </script>
+ * ```
  */
 export function useThemePageStyle() {
     const store = useThemeStore();

package/src/composables/theme/palette.ts

@@ -1,10 +1,20 @@
+/**
+ * 主题颜色配置项接口。
+ */
 export interface ThemeColor {
+    /** 颜色名称描述 */
     label: string;
+    /** 主题色十六进制值 (Hex Color) */
     value: string;
 }
 
+/** 存储当前主题色设置的 LocalStorage 键名 */
 export const THEME_COLOR_KEY = "hlw_theme_color";
 
+/**
+ * 预设的语义化颜色。
+ * 包含成功、警告、错误和提示的默认色彩配置。
+ */
 export const THEME_SEMANTIC_COLORS = {
     success: "#10b981",
     warning: "#f59e0b",
@@ -12,6 +22,9 @@ export const THEME_SEMANTIC_COLORS = {
     info: "#64748b",
 } as const;
 
+/**
+ * 系统预设的默认主题色列表。
+ */
 export const DEFAULT_THEMES: ThemeColor[] = [
     { label: "翡翠绿", value: "#10b981" },
     { label: "活力橙", value: "#f97316" },
@@ -21,6 +34,11 @@ export const DEFAULT_THEMES: ThemeColor[] = [
     { label: "青石灰", value: "#64748b" },
 ];
 
+/**
+ * 读取当前配置的主题色 Hex 字符串。
+ * 默认使用 `DEFAULT_THEMES` 数组中首位颜色的值。
+ * @returns 十六进制颜色字符串
+ */
 export function getCurrentThemeColor(): string {
     try {
         const v = uni.getStorageSync(THEME_COLOR_KEY);
@@ -29,6 +47,11 @@ export function getCurrentThemeColor(): string {
     return DEFAULT_THEMES[0].value;
 }
 
+/**
+ * 获取当前主题色所对应的完整 CSS 颜色语义变量映射表。
+ * 会基于当前主题色，自动计算衍生出对应的亮色调、暗色调以及各状态色语义变量。
+ * @returns 包含各 CSS 变量名与对应颜色值键值对
+ */
 export function getCurrentThemeVars(): Record<string, string> {
     const color = getCurrentThemeColor();
     return {
@@ -64,6 +87,9 @@ export function getCurrentThemeVars(): Record<string, string> {
 
 const HEX_RE = /^#[0-9a-fA-F]{6}$/;
 
+/**
+ * 将 6 位 hex 颜色字符串转换为 RGB 三原色元组。
+ */
 function parseHex(hex: string): [number, number, number] {
     if (!HEX_RE.test(hex)) throw new Error(`Invalid hex color: ${hex}`);
     return [
@@ -73,11 +99,17 @@ function parseHex(hex: string): [number, number, number] {
     ];
 }
 
+/**
+ * 转换 Hex 颜色为 rgba 格式字符串。
+ */
 function hexToRgba(hex: string, alpha: number): string {
     const [r, g, b] = parseHex(hex);
     return `rgba(${r},${g},${b},${alpha})`;
 }
 
+/**
+ * 将 Hex 颜色调暗。
+ */
 function darkenHex(hex: string, amount = 0.15): string {
     const [r, g, b] = parseHex(hex);
     const darken = (value: number) => Math.max(0, Math.round(value * (1 - amount)));

package/src/composables/theme/typography.ts

@@ -14,6 +14,9 @@
  * - caption:  角标 / 底部小字 / 时间戳
  */
 
+/**
+ * 语义排版角色配置项接口。
+ */
 export interface TypographyRole {
     /** 对应 `--text-{role}-size` 的值（通常引用字号档位 token） */
     size: string;
@@ -25,6 +28,9 @@ export interface TypographyRole {
     color: string;
 }
 
+/**
+ * 全局预设排版角色的参数配置表。
+ */
 export const TYPOGRAPHY_ROLES: Record<string, TypographyRole> = {
     "title-lg": {
         size: "var(--font-xl)",
@@ -68,7 +74,9 @@ export const TYPOGRAPHY_ROLES: Record<string, TypographyRole> = {
  * 展开成 CSS 变量平铺 map，用于 buildThemeStyle 注入 page 元素。
  *
  * 每个角色产出 4 个变量：
- *   --text-{role}-size / -weight / -line-height / -color
+ *   --text-${role}-size / -weight / -line-height / -color
+ * 
+ * @returns 包含全部排版 CSS 变量键值对的对象
  */
 export function getCurrentTypographyVars(): Record<string, string> {
     const vars: Record<string, string> = {};