@hlw-uni/mp-vue 2.1.57 → 2.1.59

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

@@ -10,20 +10,46 @@
  * - 用 `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;
 }
+/** 存储外观设置的 LocalStorage 键名 */
 export declare const APPEARANCE_KEY = "hlw_appearance";
+/** 预设外观模式列表，常供设置页渲染选择器使用 */
 export declare const APPEARANCE_PRESETS: AppearancePreset[];
+/** 不同外观模式的 CSS 变量映射 */
 export declare const APPEARANCE_VAR_MAP: Record<AppearanceMode, Record<string, string>>;
-/** 读取用户设置的外观（light/dark/auto），默认 auto */
+/**
+ * 读取用户设置的外观配置（light / dark / auto）。
+ * 默认返回 'auto'。
+ * @returns 设定的外观模式类型
+ */
 export declare function getCurrentAppearance(): Appearance;
-/** 将 auto 解析为具体的 light/dark，依据系统主题 */
+/**
+ * 将 auto 设置或用户选择解析为具体的 light/dark 实际模式。
+ * 当为 auto 时，将读取系统当前的配色偏好。
+ * @param appearance 输入的外观配置
+ * @returns 解析后最终生效的外观模式 (light 或 dark)
+ */
 export declare function resolveAppearance(appearance: Appearance): AppearanceMode;
-/** 当前实际生效的模式（light 或 dark） */
+/**
+ * 获取当前实际生效的外观模式 (light 或 dark)。
+ * 自动根据用户偏好及系统主题进行判定。
+ * @returns 实际生效的外观模式
+ */
 export declare function getCurrentAppearanceMode(): AppearanceMode;
-/** 当前外观对应的 CSS 变量 */
+/**
+ * 获取当前外观对应的 CSS 变量映射表。
+ * @returns 包含各 CSS 变量名与对应颜色值键值对
+ */
 export declare function getCurrentAppearanceVars(): Record<string, string>;

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

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

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

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

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

@@ -1,14 +1,37 @@
+/**
+ * 主题颜色配置项接口。
+ */
 export interface ThemeColor {
+    /** 颜色名称描述 */
     label: string;
+    /** 主题色十六进制值 (Hex Color) */
     value: string;
 }
+/** 存储当前主题色设置的 LocalStorage 键名 */
 export declare const THEME_COLOR_KEY = "hlw_theme_color";
+/**
+ * 预设的语义化颜色。
+ * 包含成功、警告、错误和提示的默认色彩配置。
+ */
 export declare const THEME_SEMANTIC_COLORS: {
     readonly success: "#10b981";
     readonly warning: "#f59e0b";
     readonly error: "#ef4444";
     readonly info: "#64748b";
 };
+/**
+ * 系统预设的默认主题色列表。
+ */
 export declare const DEFAULT_THEMES: ThemeColor[];
+/**
+ * 读取当前配置的主题色 Hex 字符串。
+ * 默认使用 `DEFAULT_THEMES` 数组中首位颜色的值。
+ * @returns 十六进制颜色字符串
+ */
 export declare function getCurrentThemeColor(): string;
+/**
+ * 获取当前主题色所对应的完整 CSS 颜色语义变量映射表。
+ * 会基于当前主题色，自动计算衍生出对应的亮色调、暗色调以及各状态色语义变量。
+ * @returns 包含各 CSS 变量名与对应颜色值键值对
+ */
 export declare function getCurrentThemeVars(): Record<string, string>;

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

@@ -13,6 +13,9 @@
  * - desc:     卡片描述 / 副文
  * - caption:  角标 / 底部小字 / 时间戳
  */
+/**
+ * 语义排版角色配置项接口。
+ */
 export interface TypographyRole {
     /** 对应 `--text-{role}-size` 的值（通常引用字号档位 token） */
     size: string;
@@ -23,11 +26,16 @@ export interface TypographyRole {
     /** 对应 `--text-{role}-color`（通常引用文字色 token） */
     color: string;
 }
+/**
+ * 全局预设排版角色的参数配置表。
+ */
 export declare 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 declare function getCurrentTypographyVars(): Record<string, string>;

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

@@ -1,35 +1,142 @@
 /**
  * 小程序通用工具。
+ * 包含查询字符串参数拼接、数据转换、剪贴板交互、授权及图片/视频等多媒体资源下载保存。
+ */
+/**
+ * 文件下载选项配置接口。
  */
 export interface DownloadOpt {
+    /** 文件的网络下载链接 */
     url: string;
+    /** 指定文件保存的本地目标路径，可选 */
     path?: string;
+    /** 请求的自定义 HTTP 请求头 */
     header?: Record<string, string>;
+    /** 下载进度更新的回调函数 */
     progress?: (value: number, done: number, total: number) => void;
 }
+/**
+ * 文件下载结果接口。
+ */
 export interface DownloadRes {
+    /** 是否成功下载 */
     ok: boolean;
+    /** 临时或保存后的本地文件路径 */
     path?: string;
+    /** 服务器返回的 HTTP 状态码 */
     code?: number;
+    /** 错误或提示信息 */
     msg?: string;
 }
-declare function withQuery(url: string, qs: string): string;
-declare function toQuery(data: Record<string, unknown>): string;
-declare function signText(url: string): string;
-declare function toNumber(val: unknown, def: number): number;
-declare function toBoolean(val: unknown, def: boolean): boolean;
+/**
+ * 拼接 URL 与 Query String。
+ * 会根据原 URL 中是否包含问号，自动拼接 `?` 或 `&`。
+ * @param url 原 URL
+ * @param qs 格式化后的 query 字符串（如 'a=1&b=2'）
+ * @returns 拼接后的完整 URL
+ */
+export declare function withQuery(url: string, qs: string): string;
+/**
+ * 将键值对对象转换为 URL 编码的 Query String。
+ * 会自动过滤值为 `undefined` 或 `null` 的键。
+ * @param data 需要转换的键值对数据对象
+ * @returns 格式化后的 Query String 字符串
+ */
+export declare function toQuery(data: Record<string, unknown>): string;
+/**
+ * 按照特定规则对 URL 或者是 Query 参数进行排序并构造签名文本。
+ * 常用于 API 请求签名的加密前置数据处理。
+ * @param url 需要签名的完整 URL 或路径
+ * @returns 排序拼接后的签名基准字符串
+ */
+export declare function signText(url: string): string;
+/**
+ * 安全转换未知值到数字类型，若转换失败则返回默认值。
+ * @param val 待转换的值
+ * @param def 默认数字
+ * @returns 转换后的数字或默认值
+ */
+export declare function toNumber(val: unknown, def: number): number;
+/**
+ * 安全转换未知值到布尔值类型，若转换失败则返回默认值。
+ * 兼容特殊数值（如 0, "0", "false" 视为 false；1, "1", "true" 视为 true）。
+ * @param val 待转换的值
+ * @param def 默认布尔值
+ * @returns 转换后的布尔值或默认值
+ */
+export declare function toBoolean(val: unknown, def: boolean): boolean;
+/**
+ * 复制文本内容至剪贴板。
+ * @param text 需要复制的文本
+ * @param tip 是否在成功时显示 "复制成功" 的 Toast 提示，默认 true
+ * @returns 是否复制成功
+ */
+export declare function copy(text: string, tip?: boolean): Promise<boolean>;
+/**
+ * 从系统剪贴板中读取文本内容。
+ * @returns 剪贴板文本，若读取失败或无内容返回空字符串
+ */
+export declare function paste(): Promise<string>;
+/**
+ * 引导用户进行系统相册权限授权提示弹窗。
+ */
+export declare function auth(): void;
+/**
+ * 保存本地临时图片文件到系统相册中。
+ * 若无权限会自动调起 `auth()` 引导用户去设置页开启权限。
+ * @param path 本地临时图片路径 (如 wxfile://xxx, http://tmp/xxx)
+ * @returns 保存是否成功
+ */
+export declare function saveImage(path: string): Promise<boolean>;
+/**
+ * 保存本地临时视频文件到系统相册中。
+ * 若无权限会自动引导授权。
+ * @param path 本地临时视频路径
+ * @returns 保存是否成功
+ */
+export declare function saveVideoFile(path: string): Promise<boolean>;
+/**
+ * 基于 UniApp 下载网络资源至本地临时目录中。
+ * @param opt 下载参数配置项
+ * @returns 下载结果 Promise
+ */
+export declare function download(opt: DownloadOpt): Promise<DownloadRes>;
+/**
+ * 下载并保存网络图片至系统相册。
+ * 过程中包含 Loading 提示以及权限处理。
+ * @param url 网络图片地址
+ * @param progress 可选的下载进度更新回调
+ * @returns 操作是否成功
+ */
+export declare function saveImageUrl(url: string, progress?: (value: number) => void): Promise<boolean>;
+/**
+ * 下载并保存网络视频至系统相册。
+ * 过程中包含 Loading 提示以及权限处理。
+ * @param url 网络视频地址
+ * @param progress 可选的下载进度更新回调
+ * @returns 操作是否成功
+ */
+export declare function saveVideoUrl(url: string, progress?: (value: number) => void): Promise<boolean>;
+/**
+ * 获取系统通用工具方法的 hook。
+ *
+ * @example
+ * ```ts
+ * const { copy, saveImageUrl } = useUtils();
+ * copy('hello');
+ * ```
+ */
 export declare function useUtils(): {
     withQuery: typeof withQuery;
     toQuery: typeof toQuery;
     signText: typeof signText;
     toNumber: typeof toNumber;
     toBoolean: typeof toBoolean;
-    copy: (text: string, tip?: boolean) => Promise<boolean>;
-    paste: () => Promise<string>;
-    saveImage: (path: string) => Promise<boolean>;
-    saveVideo: (path: string) => Promise<boolean>;
-    download: (opt: DownloadOpt) => Promise<DownloadRes>;
-    saveImageUrl: (url: string, progress?: ((value: number) => void) | undefined) => Promise<boolean>;
-    saveVideoUrl: (url: string, progress?: ((value: number) => void) | undefined) => Promise<boolean>;
+    copy: typeof copy;
+    paste: typeof paste;
+    saveImage: typeof saveImage;
+    saveVideoFile: typeof saveVideoFile;
+    download: typeof download;
+    saveImageUrl: typeof saveImageUrl;
+    saveVideoUrl: typeof saveVideoUrl;
 };
-export {};

package/dist/directives/copy.d.ts

@@ -1,3 +1,8 @@
 import { Directive } from 'vue';
 
+/**
+ * 自定义 Vue 指令 `v-copy`
+ *
+ * 在元素/组件被创建或更新前，拦截其点击事件并注入复制剪贴板逻辑。
+ */
 export declare const vCopy: Directive;

package/dist/hlw.d.ts

@@ -3,10 +3,20 @@ import { DeviceInfo } from './composables/device';
 import { useRequest } from './composables/request';
 import { useUtils } from './composables/utils';
 
+/**
+ * 全局 hlw 实例接口定义，聚合了框架的核心能力。
+ */
 export interface HlwInstance {
+    /** 统一的消息提示与模态弹窗管理模块 */
     $msg: ReturnType<typeof useMsg>;
+    /** 当前运行设备的详细系统信息 */
     $device: DeviceInfo;
+    /** 全局配置的统一 HTTP 请求实例 */
     $request: ReturnType<typeof useRequest>;
+    /** 聚合的常用小程序公共工具函数 */
     $utils: ReturnType<typeof useUtils>;
 }
+/**
+ * 全局单例 `hlw` 实例，各核心模块在首次读取时延迟初始化并缓存。
+ */
 export declare const hlw: HlwInstance;