@hlw-uni/mp-vue 1.1.22 → 1.2.1

package/dist/composables/theme/appearance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 外观模式 — 浅色 / 深色 / 跟随系统
+ *
+ * 提供一套语义化 CSS 变量（--bg-page, --surface-card, --text-primary ...），
+ * 页面通过 hlw-page 的 `:page-style` 注入到 `page` 元素，让内部组件和样式统一消费。
+ *
+ * 使用指南：
+ * - 业务样式里用 `var(--text-primary)` 代替硬编码 `#0f172a`
+ * - 用 `var(--surface-card)` 代替硬编码 `#ffffff`
+ * - 用 `var(--border-color-light)` 代替硬编码 `#f1f5f9`
+ */
+export type Appearance = "light" | "dark" | "auto";
+export type AppearanceMode = "light" | "dark";
+export interface AppearancePreset {
+    value: Appearance;
+    label: string;
+}
+export declare const APPEARANCE_KEY = "hlw_appearance";
+export declare const APPEARANCE_PRESETS: AppearancePreset[];
+export declare const APPEARANCE_VAR_MAP: Record<AppearanceMode, Record<string, string>>;
+/** 读取用户设置的外观（light/dark/auto），默认 auto */
+export declare function getCurrentAppearance(): Appearance;
+/** 将 auto 解析为具体的 light/dark，依据系统主题 */
+export declare function resolveAppearance(appearance: Appearance): AppearanceMode;
+/** 当前实际生效的模式（light 或 dark） */
+export declare function getCurrentAppearanceMode(): AppearanceMode;
+/** 当前外观对应的 CSS 变量 */
+export declare function getCurrentAppearanceVars(): Record<string, string>;

package/dist/composables/theme/index.d.ts

@@ -8,3 +8,5 @@ export type { FontScale, FontPreset } from './font';
 export { FONT_SCALE_KEY, FONT_PRESETS, getCurrentFontScale, getCurrentFontVars } from './font';
 export type { ThemeColor } from './palette';
 export { THEME_COLOR_KEY, THEME_SEMANTIC_COLORS, DEFAULT_THEMES, getCurrentThemeColor, getCurrentThemeVars, } from './palette';
+export type { Appearance, AppearanceMode, AppearancePreset } from './appearance';
+export { APPEARANCE_KEY, APPEARANCE_PRESETS, APPEARANCE_VAR_MAP, getCurrentAppearance, getCurrentAppearanceMode, getCurrentAppearanceVars, resolveAppearance, } from './appearance';

package/dist/index.js

@@ -118,12 +118,85 @@
       "--info-dark": darkenHex(THEME_SEMANTIC_COLORS.info)
     };
   }
+  const APPEARANCE_KEY = "hlw_appearance";
+  const APPEARANCE_PRESETS = [
+    { value: "light", label: "浅色模式" },
+    { value: "dark", label: "深色模式" },
+    { value: "auto", label: "跟随系统" }
+  ];
+  const LIGHT_VARS = {
+    "--bg-page": "#f6f6f6",
+    "--bg-elevated": "#ffffff",
+    "--surface-card": "#ffffff",
+    "--surface-card-muted": "#f8fafc",
+    "--surface-secondary": "#f1f5f9",
+    "--surface-tertiary": "#e2e8f0",
+    "--text-primary": "#0f172a",
+    "--text-secondary": "#334155",
+    "--text-muted": "#64748b",
+    "--text-subtle": "#94a3b8",
+    "--text-disabled": "#cbd5e1",
+    "--border-color": "#e2e8f0",
+    "--border-color-light": "#f1f5f9",
+    "--border-color-focus": "#bfdbfe",
+    "--shadow-soft": "0 2rpx 8rpx rgba(15, 23, 42, 0.04)",
+    "--shadow-card": "0 4rpx 16rpx rgba(15, 23, 42, 0.06)"
+  };
+  const DARK_VARS = {
+    "--bg-page": "#0b1020",
+    "--bg-elevated": "#111827",
+    "--surface-card": "#1e293b",
+    "--surface-card-muted": "#273549",
+    "--surface-secondary": "#273549",
+    "--surface-tertiary": "#334155",
+    "--text-primary": "#f8fafc",
+    "--text-secondary": "#cbd5e1",
+    "--text-muted": "#94a3b8",
+    "--text-subtle": "#64748b",
+    "--text-disabled": "#475569",
+    "--border-color": "#334155",
+    "--border-color-light": "#1e293b",
+    "--border-color-focus": "#3b82f6",
+    "--shadow-soft": "0 2rpx 8rpx rgba(0, 0, 0, 0.3)",
+    "--shadow-card": "0 4rpx 16rpx rgba(0, 0, 0, 0.35)"
+  };
+  const APPEARANCE_VAR_MAP = {
+    light: LIGHT_VARS,
+    dark: DARK_VARS
+  };
+  function getCurrentAppearance() {
+    try {
+      const v = uni.getStorageSync(APPEARANCE_KEY);
+      if (v === "light" || v === "dark" || v === "auto")
+        return v;
+    } catch {
+    }
+    return "auto";
+  }
+  function resolveAppearance(appearance) {
+    if (appearance === "light" || appearance === "dark")
+      return appearance;
+    try {
+      const info = uni.getSystemInfoSync();
+      if (info.theme === "dark")
+        return "dark";
+    } catch {
+    }
+    return "light";
+  }
+  function getCurrentAppearanceMode() {
+    return resolveAppearance(getCurrentAppearance());
+  }
+  function getCurrentAppearanceVars() {
+    return APPEARANCE_VAR_MAP[getCurrentAppearanceMode()];
+  }
   const { varsToStyle } = mpCore.useColor();
   const THEME_CHANGE_EVENT = "hlw:theme-change";
   function buildThemeStyle() {
     return varsToStyle({
       ...getCurrentFontVars(),
-      ...getCurrentThemeVars()
+      ...getCurrentThemeVars(),
+      ...getCurrentAppearanceVars()
     });
   }
   function useThemePageStyle() {
@@ -158,6 +231,15 @@
         uni.setStorageSync(THEME_COLOR_KEY, color);
         uni.$emit(THEME_CHANGE_EVENT);
       }
+      const appearance = vue.ref("auto");
+      const appearanceOptions = APPEARANCE_PRESETS;
+      const appearanceMode = vue.computed(() => resolveAppearance(appearance.value));
+      const isDark = vue.computed(() => appearanceMode.value === "dark");
+      function setAppearance(a) {
+        appearance.value = a;
+        uni.setStorageSync(APPEARANCE_KEY, a);
+        uni.$emit(THEME_CHANGE_EVENT);
+      }
       return {
         // 字体
         scale,
@@ -167,7 +249,13 @@
         primaryColor,
         themes,
         activeTheme,
-        setTheme
+        setTheme,
+        // 外观模式
+        appearance,
+        appearanceOptions,
+        appearanceMode,
+        isDark,
+        setAppearance
       };
     },
     { unistorage: true }

package/dist/index.mjs

@@ -117,12 +117,85 @@ function getCurrentThemeVars() {
     "--info-dark": darkenHex(THEME_SEMANTIC_COLORS.info)
   };
 }
+const APPEARANCE_KEY = "hlw_appearance";
+const APPEARANCE_PRESETS = [
+  { value: "light", label: "浅色模式" },
+  { value: "dark", label: "深色模式" },
+  { value: "auto", label: "跟随系统" }
+];
+const LIGHT_VARS = {
+  "--bg-page": "#f6f6f6",
+  "--bg-elevated": "#ffffff",
+  "--surface-card": "#ffffff",
+  "--surface-card-muted": "#f8fafc",
+  "--surface-secondary": "#f1f5f9",
+  "--surface-tertiary": "#e2e8f0",
+  "--text-primary": "#0f172a",
+  "--text-secondary": "#334155",
+  "--text-muted": "#64748b",
+  "--text-subtle": "#94a3b8",
+  "--text-disabled": "#cbd5e1",
+  "--border-color": "#e2e8f0",
+  "--border-color-light": "#f1f5f9",
+  "--border-color-focus": "#bfdbfe",
+  "--shadow-soft": "0 2rpx 8rpx rgba(15, 23, 42, 0.04)",
+  "--shadow-card": "0 4rpx 16rpx rgba(15, 23, 42, 0.06)"
+};
+const DARK_VARS = {
+  "--bg-page": "#0b1020",
+  "--bg-elevated": "#111827",
+  "--surface-card": "#1e293b",
+  "--surface-card-muted": "#273549",
+  "--surface-secondary": "#273549",
+  "--surface-tertiary": "#334155",
+  "--text-primary": "#f8fafc",
+  "--text-secondary": "#cbd5e1",
+  "--text-muted": "#94a3b8",
+  "--text-subtle": "#64748b",
+  "--text-disabled": "#475569",
+  "--border-color": "#334155",
+  "--border-color-light": "#1e293b",
+  "--border-color-focus": "#3b82f6",
+  "--shadow-soft": "0 2rpx 8rpx rgba(0, 0, 0, 0.3)",
+  "--shadow-card": "0 4rpx 16rpx rgba(0, 0, 0, 0.35)"
+};
+const APPEARANCE_VAR_MAP = {
+  light: LIGHT_VARS,
+  dark: DARK_VARS
+};
+function getCurrentAppearance() {
+  try {
+    const v = uni.getStorageSync(APPEARANCE_KEY);
+    if (v === "light" || v === "dark" || v === "auto")
+      return v;
+  } catch {
+  }
+  return "auto";
+}
+function resolveAppearance(appearance) {
+  if (appearance === "light" || appearance === "dark")
+    return appearance;
+  try {
+    const info = uni.getSystemInfoSync();
+    if (info.theme === "dark")
+      return "dark";
+  } catch {
+  }
+  return "light";
+}
+function getCurrentAppearanceMode() {
+  return resolveAppearance(getCurrentAppearance());
+}
+function getCurrentAppearanceVars() {
+  return APPEARANCE_VAR_MAP[getCurrentAppearanceMode()];
+}
 const { varsToStyle } = useColor();
 const THEME_CHANGE_EVENT = "hlw:theme-change";
 function buildThemeStyle() {
   return varsToStyle({
     ...getCurrentFontVars(),
-    ...getCurrentThemeVars()
+    ...getCurrentThemeVars(),
+    ...getCurrentAppearanceVars()
   });
 }
 function useThemePageStyle() {
@@ -157,6 +230,15 @@ const useThemeStore = defineStore(
       uni.setStorageSync(THEME_COLOR_KEY, color);
       uni.$emit(THEME_CHANGE_EVENT);
     }
+    const appearance = ref("auto");
+    const appearanceOptions = APPEARANCE_PRESETS;
+    const appearanceMode = computed(() => resolveAppearance(appearance.value));
+    const isDark = computed(() => appearanceMode.value === "dark");
+    function setAppearance(a) {
+      appearance.value = a;
+      uni.setStorageSync(APPEARANCE_KEY, a);
+      uni.$emit(THEME_CHANGE_EVENT);
+    }
     return {
       // 字体
       scale,
@@ -166,7 +248,13 @@ const useThemeStore = defineStore(
       primaryColor,
       themes,
       activeTheme,
-      setTheme
+      setTheme,
+      // 外观模式
+      appearance,
+      appearanceOptions,
+      appearanceMode,
+      isDark,
+      setAppearance
     };
   },
   { unistorage: true }

package/dist/stores/theme.d.ts

@@ -1,4 +1,4 @@
-import { FontScale, ThemeColor } from '../composables/theme';
+import { FontScale, ThemeColor, Appearance, AppearanceMode, AppearancePreset } from '../composables/theme';
 import { StoreDefinition } from 'pinia';
 import { Ref, ComputedRef } from 'vue';
 
@@ -13,7 +13,12 @@ export declare const useThemeStore: StoreDefinition<"theme", Pick<{
     themes: ThemeColor[];
     activeTheme: ComputedRef<ThemeColor>;
     setTheme: (color: string) => void;
-}, "scale" | "fontOptions" | "primaryColor" | "themes">, Pick<{
+    appearance: Ref<Appearance, Appearance>;
+    appearanceOptions: AppearancePreset[];
+    appearanceMode: ComputedRef<AppearanceMode>;
+    isDark: ComputedRef<boolean>;
+    setAppearance: (a: Appearance) => void;
+}, "scale" | "fontOptions" | "primaryColor" | "themes" | "appearance" | "appearanceOptions">, Pick<{
     scale: Ref<FontScale, FontScale>;
     fontOptions: {
         value: FontScale;
@@ -24,7 +29,12 @@ export declare const useThemeStore: StoreDefinition<"theme", Pick<{
     themes: ThemeColor[];
     activeTheme: ComputedRef<ThemeColor>;
     setTheme: (color: string) => void;
-}, "activeTheme">, Pick<{
+    appearance: Ref<Appearance, Appearance>;
+    appearanceOptions: AppearancePreset[];
+    appearanceMode: ComputedRef<AppearanceMode>;
+    isDark: ComputedRef<boolean>;
+    setAppearance: (a: Appearance) => void;
+}, "activeTheme" | "appearanceMode" | "isDark">, Pick<{
     scale: Ref<FontScale, FontScale>;
     fontOptions: {
         value: FontScale;
@@ -35,4 +45,9 @@ export declare const useThemeStore: StoreDefinition<"theme", Pick<{
     themes: ThemeColor[];
     activeTheme: ComputedRef<ThemeColor>;
     setTheme: (color: string) => void;
-}, "setScale" | "setTheme">>;
+    appearance: Ref<Appearance, Appearance>;
+    appearanceOptions: AppearancePreset[];
+    appearanceMode: ComputedRef<AppearanceMode>;
+    isDark: ComputedRef<boolean>;
+    setAppearance: (a: Appearance) => void;
+}, "setScale" | "setTheme" | "setAppearance">>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hlw-uni/mp-vue",
-    "version": "1.1.22",
+    "version": "1.2.1",
     "description": "hlw-uni Vue 组件库 — 供小程序业务方使用的 UI 组件集合",
     "main": "dist/index.js",
     "module": "dist/index.mjs",

package/src/components/hlw-page/index.vue

@@ -187,6 +187,8 @@ defineExpose(exposed as {
     display: flex;
     flex-direction: column;
     overflow: hidden;
+    background: var(--bg-page, #f6f6f6);
+    color: var(--text-primary, #0f172a);
 }
 
 .hlw-page-header {

package/src/composables/theme/appearance.ts

@@ -0,0 +1,101 @@
+/**
+ * 外观模式 — 浅色 / 深色 / 跟随系统
+ *
+ * 提供一套语义化 CSS 变量（--bg-page, --surface-card, --text-primary ...），
+ * 页面通过 hlw-page 的 `:page-style` 注入到 `page` 元素，让内部组件和样式统一消费。
+ *
+ * 使用指南：
+ * - 业务样式里用 `var(--text-primary)` 代替硬编码 `#0f172a`
+ * - 用 `var(--surface-card)` 代替硬编码 `#ffffff`
+ * - 用 `var(--border-color-light)` 代替硬编码 `#f1f5f9`
+ */
+
+export type Appearance = "light" | "dark" | "auto";
+export type AppearanceMode = "light" | "dark";
+
+export interface AppearancePreset {
+    value: Appearance;
+    label: string;
+}
+
+export const APPEARANCE_KEY = "hlw_appearance";
+
+export const APPEARANCE_PRESETS: AppearancePreset[] = [
+    { value: "light", label: "浅色模式" },
+    { value: "dark", label: "深色模式" },
+    { value: "auto", label: "跟随系统" },
+];
+
+/** 浅色模式语义变量 */
+const LIGHT_VARS: Record<string, string> = {
+    "--bg-page": "#f6f6f6",
+    "--bg-elevated": "#ffffff",
+    "--surface-card": "#ffffff",
+    "--surface-card-muted": "#f8fafc",
+    "--surface-secondary": "#f1f5f9",
+    "--surface-tertiary": "#e2e8f0",
+    "--text-primary": "#0f172a",
+    "--text-secondary": "#334155",
+    "--text-muted": "#64748b",
+    "--text-subtle": "#94a3b8",
+    "--text-disabled": "#cbd5e1",
+    "--border-color": "#e2e8f0",
+    "--border-color-light": "#f1f5f9",
+    "--border-color-focus": "#bfdbfe",
+    "--shadow-soft": "0 2rpx 8rpx rgba(15, 23, 42, 0.04)",
+    "--shadow-card": "0 4rpx 16rpx rgba(15, 23, 42, 0.06)",
+};
+
+/** 深色模式语义变量 */
+const DARK_VARS: Record<string, string> = {
+    "--bg-page": "#0b1020",
+    "--bg-elevated": "#111827",
+    "--surface-card": "#1e293b",
+    "--surface-card-muted": "#273549",
+    "--surface-secondary": "#273549",
+    "--surface-tertiary": "#334155",
+    "--text-primary": "#f8fafc",
+    "--text-secondary": "#cbd5e1",
+    "--text-muted": "#94a3b8",
+    "--text-subtle": "#64748b",
+    "--text-disabled": "#475569",
+    "--border-color": "#334155",
+    "--border-color-light": "#1e293b",
+    "--border-color-focus": "#3b82f6",
+    "--shadow-soft": "0 2rpx 8rpx rgba(0, 0, 0, 0.3)",
+    "--shadow-card": "0 4rpx 16rpx rgba(0, 0, 0, 0.35)",
+};
+
+export const APPEARANCE_VAR_MAP: Record<AppearanceMode, Record<string, string>> = {
+    light: LIGHT_VARS,
+    dark: DARK_VARS,
+};
+
+/** 读取用户设置的外观（light/dark/auto），默认 auto */
+export function getCurrentAppearance(): Appearance {
+    try {
+        const v = uni.getStorageSync(APPEARANCE_KEY);
+        if (v === "light" || v === "dark" || v === "auto") return v;
+    } catch {}
+    return "auto";
+}
+
+/** 将 auto 解析为具体的 light/dark，依据系统主题 */
+export function resolveAppearance(appearance: Appearance): AppearanceMode {
+    if (appearance === "light" || appearance === "dark") return appearance;
+    try {
+        const info = uni.getSystemInfoSync();
+        if ((info as { theme?: string }).theme === "dark") return "dark";
+    } catch {}
+    return "light";
+}
+
+/** 当前实际生效的模式（light 或 dark） */
+export function getCurrentAppearanceMode(): AppearanceMode {
+    return resolveAppearance(getCurrentAppearance());
+}
+
+/** 当前外观对应的 CSS 变量 */
+export function getCurrentAppearanceVars(): Record<string, string> {
+    return APPEARANCE_VAR_MAP[getCurrentAppearanceMode()];
+}

package/src/composables/theme/index.ts

@@ -4,6 +4,7 @@ import { useColor } from "@hlw-uni/mp-core";
 const { varsToStyle } = useColor();
 import { getCurrentFontVars } from "./font";
 import { getCurrentThemeVars } from "./palette";
+import { getCurrentAppearanceVars } from "./appearance";
 
 export const THEME_CHANGE_EVENT = "hlw:theme-change";
 
@@ -11,6 +12,7 @@ export function buildThemeStyle(): string {
     return varsToStyle({
         ...getCurrentFontVars(),
         ...getCurrentThemeVars(),
+        ...getCurrentAppearanceVars(),
     });
 }
 
@@ -37,3 +39,13 @@ export {
     getCurrentThemeColor,
     getCurrentThemeVars,
 } from "./palette";
+export type { Appearance, AppearanceMode, AppearancePreset } from "./appearance";
+export {
+    APPEARANCE_KEY,
+    APPEARANCE_PRESETS,
+    APPEARANCE_VAR_MAP,
+    getCurrentAppearance,
+    getCurrentAppearanceMode,
+    getCurrentAppearanceVars,
+    resolveAppearance,
+} from "./appearance";

package/src/stores/theme.ts

@@ -10,8 +10,11 @@ import {
     DEFAULT_THEMES,
     THEME_COLOR_KEY,
     THEME_CHANGE_EVENT,
+    APPEARANCE_KEY,
+    APPEARANCE_PRESETS,
+    resolveAppearance,
 } from "../composables/theme";
-import type { FontScale, ThemeColor } from "../composables/theme";
+import type { FontScale, ThemeColor, Appearance, AppearanceMode } from "../composables/theme";
 
 export const useThemeStore = defineStore(
     "theme",
@@ -49,6 +52,23 @@ export const useThemeStore = defineStore(
             uni.$emit(THEME_CHANGE_EVENT);
         }
 
+        // ─── 外观模式（light / dark / auto） ─────────
+        const appearance = ref<Appearance>("auto");
+
+        const appearanceOptions = APPEARANCE_PRESETS;
+
+        /** 当前实际生效的模式（auto 会被解析为 light/dark） */
+        const appearanceMode = computed<AppearanceMode>(() => resolveAppearance(appearance.value));
+
+        /** 是否深色模式（业务组件可直接读取做条件渲染） */
+        const isDark = computed(() => appearanceMode.value === "dark");
+
+        function setAppearance(a: Appearance) {
+            appearance.value = a;
+            uni.setStorageSync(APPEARANCE_KEY, a);
+            uni.$emit(THEME_CHANGE_EVENT);
+        }
+
         return {
             // 字体
             scale,
@@ -59,6 +79,12 @@ export const useThemeStore = defineStore(
             themes,
             activeTheme,
             setTheme,
+            // 外观模式
+            appearance,
+            appearanceOptions,
+            appearanceMode,
+            isDark,
+            setAppearance,
         };
     },
     { unistorage: true },