@hlw-uni/mp-vue 2.1.56 → 2.1.58

package/dist/app.d.ts

@@ -3,7 +3,18 @@ import { HlwInstance } from './hlw';
 import { RequestClient } from './composables/request';
 
 /**
- * 创建 uni-app 应用入口工具。
+ * 创建 uni-app 应用入口与全局插件配置工具。
+ *
+ * @example
+ * ```ts
+ * import { useApp } from '@hlw-uni/mp-vue';
+ * import App from './App.vue';
+ * import { createPinia } from 'pinia';
+ *
+ * const app = useApp();
+ * app.use(createPinia());
+ * export const createApp = app.install(App);
+ * ```
  */
 export declare function useApp(): {
     install: (AppComponent: Component) => () => {

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

@@ -1,12 +1,38 @@
 /**
  * 小程序广告工具。
+ * 提供插屏广告 (Interstitial Ad) 与激励视频广告 (Rewarded Video Ad) 的注册、缓存与展示能力。
+ */
+/**
+ * 广告播放/加载结果数据结构。
  */
 export interface AdRes {
+    /** 广告是否正常加载或成功展示完成 */
     ok: boolean;
+    /** 激励视频是否完全播放完毕 (仅激励视频有此属性) */
     isEnded?: boolean;
+    /** 加载或展示失败时的错误对象 */
     err?: unknown;
 }
 type AdDone = (res: AdRes) => void;
+/**
+ * 小程序广告 Composables。
+ *
+ * @example
+ * ```ts
+ * const { setAdPopup, showAdPopup, setAdReward, showAdReward } = useHlwAd();
+ *
+ * // 1. 插屏广告
+ * setAdPopup('ad-unit-id');
+ * await showAdPopup();
+ *
+ * // 2. 激励视频
+ * await setAdReward('ad-unit-id');
+ * const res = await showAdReward();
+ * if (res.ok && res.isEnded) {
+ *    // 发放奖励
+ * }
+ * ```
+ */
 export declare function useHlwAd(): {
     setAdPopup: (adId: string, done?: ((ok: boolean) => void) | undefined) => boolean;
     showAdPopup: (delay?: number) => Promise<boolean>;

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

@@ -1,3 +1,6 @@
+/**
+ * 完整设备系统信息接口，包含小程序环境与宿主系统的关键元数据。
+ */
 export interface DeviceInfo {
     /** 小程序 appId */
     appid: string;
@@ -56,9 +59,20 @@ export interface DeviceInfo {
     /** 客户端版本号 */
     version: string;
 }
+/**
+ * 过滤后常用于接口公共请求 Query 的设备字段子集。
+ */
 export type DeviceQueryInfo = Pick<DeviceInfo, "appid" | "device_brand" | "device_model" | "device_id" | "device_type" | "device_orientation" | "platform" | "system" | "os" | "version" | "sdk_version" | "host_name" | "host_version" | "host_language" | "language" | "app_version" | "app_version_code" | "screen_width" | "screen_height">;
+/**
+ * 访问当前设备配置信息的 hooks。
+ *
+ * @returns 包含 `info` (原始数据) 和 `query` (用于 HTTP 报头/URL query 的 urlencoded 字符串)
+ */
 export declare function useDevice(): {
     info: DeviceInfo;
     query: string;
 };
+/**
+ * 清除本地设备信息缓存，使下一次读取重新走系统调用收集。
+ */
 export declare function clearDeviceCache(): void;

package/dist/composables/index.d.ts

@@ -7,7 +7,7 @@ export { useDevice, clearDeviceCache, type DeviceInfo, type DeviceQueryInfo, } f
 export { useRefs } from './refs';
 export { useShare, type ShareConfig, } from './share';
 export { useHlwAd, type AdRes } from './ad';
-export { useUtils, type DownloadOpt, type DownloadRes } from './utils';
+export { useUtils, withQuery, toQuery, signText, toNumber, toBoolean, copy, paste, auth, saveImage, saveVideoFile, download, saveImageUrl, saveVideoUrl, type DownloadOpt, type DownloadRes, } from './utils';
 export { useNavigate, type NavigateType, type NavigateOptions } from './navigator';
 export type { FontScale, FontPreset } from './theme';
 export { FONT_SCALE_KEY, FONT_PRESETS, getCurrentFontScale, getCurrentFontVars, THEME_CHANGE_EVENT, buildThemeStyle, useThemePageStyle, } from './theme';

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

@@ -1,38 +1,79 @@
 /**
  * useMsg - 消息提示 composable
+ * 封装并统一小程序原生的 Toast、Loading 与模态弹窗 API。
  */
-export type ToastIcon = "success" | "fail" | "exception" | "none";
+/** Toast 支持的图标类型 */
+export type ToastIcon = "success" | "loading" | "error" | "none" | "fail" | "exception";
+/** Toast 持续时间的预设档位 */
 export type ToastDuration = "short" | "long";
+/**
+ * Toast 轻提示配置项。
+ */
 export interface ToastOptions {
+    /** 提示的消息内容 */
     message: string;
+    /** 显示的图标类型，默认为 'none' */
     icon?: ToastIcon;
+    /** 自定义图标的本地/网络图片路径（如传入，将忽略 icon 属性） */
     image?: string;
+    /** 持续时间，单位毫秒，默认 2000ms */
     duration?: number;
+    /** 是否显示透明蒙层防止穿透点击，默认 false */
     mask?: boolean;
+    /** 提示框的悬浮位置，仅在某些平台下生效 */
     position?: "top" | "center" | "bottom";
 }
+/**
+ * 模态确认对话框配置项。
+ */
 export interface ModalOptions {
+    /** 弹窗标题，默认 '提示' */
     title?: string;
+    /** 弹窗内容 */
     content: string;
+    /** 确认按钮的文字，默认 '确定' */
     confirmText?: string;
+    /** 取消按钮的文字，默认 '取消' */
     cancelText?: string;
+    /** 确认按钮的文字颜色，默认使用主题蓝色 */
     confirmColor?: string;
+    /** 取消按钮的文字颜色，默认灰色 */
     cancelColor?: string;
-    /** false=隐藏取消按钮（纯提示弹窗用） */
+    /** 是否显示取消按钮，若为 false 则只有确认按钮，默认 true */
     showCancel?: boolean;
 }
+/**
+ * useMsg 返回的方法与接口实例。
+ */
 export interface HlwMsg {
+    /** 显示普通 Toast 轻提示，支持配置对象或纯文本 */
     toast(opts: ToastOptions | string): void;
+    /** 显示成功提示 (含成功图标) */
     success(message: string): void;
+    /** 显示失败提示 (含错误图标) */
     error(message: string): void;
+    /** 显示失败提示 (含错误图标) —— error 方法的别名 */
     fail(message: string): void;
+    /** 显示全局模态 Loading 状态，默认显示 "加载中..." */
     showLoading(message?: string): void;
+    /** 关闭全局 Loading 状态 */
     hideLoading(): void;
+    /** 弹出确认模态框，返回 Promise<boolean> 代表用户是否点击了“确认” */
     confirm(opts: ModalOptions): Promise<boolean>;
+    /** 弹出确认模态框 —— confirm 方法的别名 */
     modal(opts: ModalOptions): Promise<boolean>;
+    /** 利用手机端导航栏标题动态展现一个文本模拟的进度条 */
     setLoadingBar(progress: number): void;
 }
 /**
- * 统一的消息提示与弹窗能力。
+ * 统一的消息提示与弹窗能力 hook。
+ *
+ * @example
+ * ```ts
+ * const msg = useMsg();
+ * msg.toast('操作成功');
+ * msg.showLoading('保存中...');
+ * const ok = await msg.confirm({ content: '确定删除吗？' });
+ * ```
  */
 export declare function useMsg(): HlwMsg;

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

@@ -1,23 +1,59 @@
 /**
- * useNavigate - uni-app 跳转工具
+ * useNavigate - uni-app 路由跳转工具
+ * 封装并统一原生的页面跳转、重定向、Switch Tab、返回、以及打开外部小程序或 WebView 等方法。
  */
+/** 页面跳转类型，支持微信小程序的各类路由动作与 WebView/小程序跳转 */
 export type NavigateType = "navigateTo" | "redirectTo" | "switchTab" | "reLaunch" | "navigateBack" | "miniprogram" | "webview" | (string & {});
+/**
+ * 路由跳转的额外配置选项。
+ */
 export interface NavigateOptions {
+    /** 发生失败时是否静默不抛出/显示 Toast 提示，默认 false */
     silent?: boolean;
+    /** 页面跳转失败时的回调 */
     onFail?: (message: string) => void;
+    /** 返回上级页面的层数，仅在 type="navigateBack" 时生效，默认 1 */
     delta?: number;
+    /** 打开外部小程序时的页面路径，仅在 type="miniprogram" 时生效 */
     path?: string;
+    /** 打开外部小程序的环境版本 (开发/体验/正式)，仅在 type="miniprogram" 时生效 */
     envVersion?: "develop" | "trial" | "release";
+    /** 传递给目标小程序的额外数据 */
     extraData?: Record<string, unknown>;
 }
+/**
+ * 核心的底层页面路由分发方法。
+ *
+ * @param type 跳转动作类型
+ * @param url 跳转目标路径或小程序 AppId
+ * @param options 额外的控制参数
+ */
 declare function navigate(type?: NavigateType, url?: string, options?: NavigateOptions): void;
+/**
+ * 路由跳转工具 hooks。
+ *
+ * @example
+ * ```ts
+ * const router = useNavigate();
+ * router.to('/pages/index/index');
+ * router.back();
+ * router.miniProgram('app-id');
+ * ```
+ */
 export declare function useNavigate(): {
+    /** 核心底层路由分发函数 */
     navigate: typeof navigate;
+    /** 保留当前页面，跳转到应用内的某个页面 */
     to: (url: string, options?: NavigateOptions) => void;
+    /** 关闭当前页面，跳转到应用内的某个页面 */
     redirect: (url: string, options?: NavigateOptions) => void;
+    /** 跳转到 switchTab 页面，并关闭其他所有非 tabBar 页面 */
     tab: (url: string, options?: NavigateOptions) => void;
+    /** 关闭所有页面，打开到应用内的某个页面 */
     reLaunch: (url: string, options?: NavigateOptions) => void;
+    /** 关闭当前页面，返回上一页面或多级页面 */
     back: (delta?: number, options?: NavigateOptions) => void;
+    /** 打开另一个小程序 */
     miniProgram: (appId: string, options?: NavigateOptions) => void;
 };
 export {};

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

@@ -1,6 +1,20 @@
 import { Ref } from 'vue';
 /**
- * 管理动态 ref 集合，适合 v-for 场景。
+ * 管理动态 ref 集合的 hook，尤其适合 v-for 列表场景。
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <view v-for="item in list" :key="item.id" :ref="setRefs(item.id)">
+ *     {{ item.name }}
+ *   </view>
+ * </template>
+ *
+ * <script setup>
+ * const { refs, setRefs } = useRefs();
+ * // 访问特定子项的 DOM/实例: refs.value[itemId]
+ * </script>
+ * ```
  */
 export declare function useRefs(): {
     refs: Ref<Record<string, any>, Record<string, any>>;

package/dist/composables/request/client.d.ts

@@ -1,20 +1,107 @@
 import { ApiResponse, ErrorInterceptor, RequestConfig, RequestInterceptor, ResponseInterceptor, UploadConfig, UploadResult } from './types';
 import { Ref } from 'vue';
 
+/**
+ * HTTP 请求客户端接口定义。
+ * 提供基础的 HTTP 请求方法、文件直传服务配置以及拦截器管理。
+ */
 export interface RequestClient {
+    /**
+     * 发送网络请求。
+     * @param config 请求配置项
+     * @returns 封装后的响应结果 Promise
+     */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * 发送 GET 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 query 参数
+     * @returns 封装后的响应结果 Promise
+     */
     get<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 发送 POST 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 body 数据
+     * @returns 封装后的响应结果 Promise
+     */
     post<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 发送 PUT 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 body 数据
+     * @returns 封装后的响应结果 Promise
+     */
     put<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 发送 DELETE 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 query 或 body 数据
+     * @returns 封装后的响应结果 Promise
+     */
     del<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 上传本地文件到服务器或第三方云存储。
+     * @param config 文件上传配置项
+     * @returns 上传解析结果 Promise
+     */
     upload(config: UploadConfig): Promise<UploadResult>;
+    /**
+     * 设置基础请求域名或前缀。
+     * @param url 域名字符串（如 'https://api.example.com'）
+     */
     setBaseURL(url: string): void;
+    /**
+     * 拼接并解析微服务模块或命名空间下的请求 URL。
+     * @param namespace 命名空间/模块名称
+     * @param url 具体的接口路径
+     * @param servicePrefix 服务的前缀，可选
+     * @returns 拼接完成的完整路径
+     */
     resolveServiceUrl(namespace: string, url: string, servicePrefix?: string): string;
+    /**
+     * 注册请求拦截器，在请求发出前触发。
+     * @param fn 拦截器处理函数
+     * @returns 用于注销该拦截器的注销函数
+     */
     onRequest(fn: RequestInterceptor): () => void;
+    /**
+     * 注册响应拦截器，在成功接收响应后触发。
+     * @param fn 拦截器处理函数
+     * @returns 用于注销该拦截器的注销函数
+     */
     onResponse<T = unknown>(fn: ResponseInterceptor<T>): () => void;
+    /**
+     * 注册错误拦截器，在请求或响应阶段发生异常时触发。
+     * @param fn 错误拦截处理器
+     * @returns 用于注销该拦截器的注销函数
+     */
     onError(fn: ErrorInterceptor): () => void;
 }
+/**
+ * 获取全局请求客户端单例。
+ *
+ * @example
+ * ```ts
+ * const http = useRequest();
+ * http.setBaseURL('https://api.example.com');
+ * ```
+ */
 export declare function useRequest(): RequestClient;
+/**
+ * 文件上传 composable。
+ * 提供 `uploading` 状态与上传方法。
+ *
+ * @example
+ * ```ts
+ * const { uploading, upload } = useUpload();
+ * const res = await upload({
+ *   type: 'oss',
+ *   filePath: 'temp-path',
+ *   server: 'https://oss-endpoint.com'
+ * });
+ * ```
+ */
 export declare function useUpload(): {
     uploading: Ref<boolean, boolean>;
     upload: (options: UploadConfig) => Promise<UploadResult>;

package/dist/composables/request/service.d.ts

@@ -1,28 +1,92 @@
 import { ApiResponse, RequestConfig } from './types';
 
+/**
+ * 带有具体必填 URL 的服务请求配置。
+ */
 export type ServiceRequestConfig = Omit<RequestConfig, "url"> & {
     url: string;
 };
+/**
+ * 命名空间装饰器配置项。
+ */
 export interface ServiceNamespaceOptions {
+    /** 微服务或模块命名空间 */
     namespace: string;
 }
+/**
+ * 服务前缀装饰器配置项。
+ */
 export interface ServicePrefixOptions {
+    /** 基础路径前缀 */
     prefix: string;
 }
+/**
+ * 基础服务抽象类。
+ * 业务 Service 类继承此类后，可通过 decorators 注入前缀与命名空间，
+ * 并通过便捷方法发起网络请求。
+ *
+ * @example
+ * ```ts
+ * @ServicePrefix('/api')
+ * @ServiceNamespace('user')
+ * class UserService extends BaseService {
+ *   getUserInfo(id: string) {
+ *     return this.get(`/info?id=${id}`);
+ *   }
+ * }
+ * ```
+ */
 export declare class BaseService {
+    /** 当前服务的命名空间（一般由 @ServiceNamespace 注入） */
     namespace: string;
+    /** 当前服务的基础路径前缀（一般由 @ServicePrefix 注入） */
     servicePrefix: string;
+    /**
+     * 发送服务请求。会自动拼接前缀与命名空间。
+     * @param options 请求配置项
+     * @returns 响应结果 Promise
+     */
     request<T = unknown>(options: ServiceRequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * 快捷发送 GET 请求。
+     * @param url 请求相对路径
+     * @param data 请求参数
+     */
     get<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 快捷发送 POST 请求。
+     * @param url 请求相对路径
+     * @param data 请求携带的 body
+     */
     post<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 快捷发送 PUT 请求。
+     * @param url 请求相对路径
+     * @param data 请求携带的 body
+     */
     put<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+    /**
+     * 快捷发送 DELETE 请求。
+     * @param url 请求相对路径
+     * @param data 请求参数
+     */
     del<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
 }
+/**
+ * 服务命名空间类装饰器。
+ * 注入 `namespace` 到服务类中。
+ * @param value 命名空间名称或配置对象
+ */
 export declare function ServiceNamespace(value: string | ServiceNamespaceOptions): (target: {
     prototype: {
         namespace?: string;
     };
 }) => void;
+/**
+ * 服务前缀类装饰器。
+ * 注入 `servicePrefix` 到服务类中。
+ * @param value 前缀值或配置对象
+ */
 export declare function ServicePrefix(value: string | ServicePrefixOptions): (target: {
     prototype: {
         servicePrefix?: string;

package/dist/composables/request/types.d.ts

@@ -1,48 +1,85 @@
-/** API 统一响应格式 */
+/**
+ * API 统一响应格式
+ * 定义服务端接口的标准数据返回格式。
+ */
 export interface ApiResponse<T = unknown> {
+    /** 业务状态码 (例如: 1 代表成功，非 1 代表不同类型的失败) */
     code: number;
+    /** 响应的主体数据 */
     data: T;
+    /** 响应的文本提示信息（如：操作成功、系统繁忙） */
     info: string;
 }
-/** 分页数据 */
+/**
+ * 分页请求的标准数据包装格式。
+ */
 export interface PageResult<T = unknown> {
+    /** 分页列表数据 */
     list: T[];
+    /** 总记录数 */
     total: number;
+    /** 当前页码 */
     page: number;
+    /** 每页记录条数 */
     pageSize: number;
 }
-/** 请求配置 */
+/**
+ * HTTP 请求参数配置项。
+ */
 export interface RequestConfig {
+    /** 请求的目标 URL，支持绝对路径或相对 BaseURL 的相对路径 */
     url: string;
+    /** 请求的 HTTP 方法，默认 "GET" */
     method?: "GET" | "POST" | "PUT" | "DELETE";
+    /** 请求携带的数据载体，GET/DELETE 对应 Query 传参，POST/PUT 对应 Body 传参 */
     data?: unknown;
+    /** 自定义请求头 */
     headers?: Record<string, string>;
+    /** 请求超时时间，单位毫秒 */
     timeout?: number;
 }
-/** 拦截器类型 */
+/**
+ * 请求拦截器函数定义。
+ * 允许在请求被发出前修改请求配置，支持异步处理。
+ */
 export type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+/**
+ * 响应拦截器函数定义。
+ * 允许在响应被接收并传递给业务逻辑前对响应数据做预处理，支持异步处理。
+ */
 export type ResponseInterceptor<T = unknown> = (res: ApiResponse<T>) => ApiResponse<T> | void | Promise<ApiResponse<T> | void>;
+/**
+ * 错误拦截器函数定义。
+ * 用于统一捕获和处理网络层或业务层抛出的异常。
+ */
 export type ErrorInterceptor = (err: Error) => void | Error | Promise<void | Error>;
-/** 上传配置 */
+/**
+ * 云存储或文件直传服务配置项。
+ */
 export interface UploadConfig {
-    /** 上传接口地址 */
+    /** 上传的服务器网关 URL */
     server: string;
-    /** 文件路径 */
+    /** 本地待上传的文件路径 (tempFilePath) */
     filePath: string;
-    /** 文件名，可选，默认取 filePath */
+    /** 直传服务器接收的文件参数名称，默认自动从 filePath 中截取 */
     fileName?: string;
-    /** 上传类型，支持 cos | oss | qiniu | alist | local */
+    /** 云直传供应商类型，支持 'cos' | 'oss' | 'qiniu' | 'alist' | 'local' */
     type: string;
-    /** 云存储密钥凭证 */
+    /** 直传签名凭证所需的一组敏感密钥对（AK、Signature、Token 等） */
     credentials?: Record<string, string>;
-    /** 自定义请求头 */
+    /** 直传时的自定义 HTTP 请求头 */
     header?: Record<string, string>;
-    /** 上传类型为 local 时，作为最终 server */
+    /** 当 type="local" 时，可以通过此属性覆盖 server 参数作为最终上传端点 */
     url?: string;
 }
-/** 上传结果 */
+/**
+ * 文件上传完成后标准接口解析出的结果。
+ */
 export interface UploadResult {
+    /** 业务状态码 */
     code: number;
+    /** 上传提示信息 */
     msg: string;
+    /** 上传成功后云端资源的可访问 URL 或文件路径 */
     data: string;
 }

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

@@ -1,12 +1,50 @@
+/**
+ * 分享卡片配置项。
+ */
 export interface ShareConfig {
+    /** 分享的标题，默认使用小程序名称 */
     title?: string;
+    /** 分享的页面路径，支持携带 query 参数，如 '/pages/index/index?id=123' */
     path?: string;
+    /** 分享卡片的展示图 URL 或本地路径 */
     imageUrl?: string;
 }
+/**
+ * 支持静态配置或动态解析器函数。
+ */
 export type ShareConfigResolver = ShareConfig | (() => ShareConfig);
+/**
+ * 分享操作句柄接口。
+ */
 export interface ShareHandlers {
+    /**
+     * 手动触发分享好友设置。
+     * @param config 可选的额外覆盖分享配置
+     */
     onShareAppMessage: (config?: ShareConfigResolver) => void;
+    /**
+     * 手动触发分享朋友圈设置。
+     * @param config 可选的额外覆盖分享配置
+     */
     onShareTimeline: (config?: ShareConfigResolver) => void;
+    /**
+     * 显示分享菜单项，启用小程序右上角分享。
+     */
     showShareMenu: () => void;
 }
+/**
+ * 小程序页面分享 Hook。
+ * 自动调用并监听当前页面的 `onShareAppMessage` 与 `onShareTimeline` 原生事件。
+ *
+ * @param config 默认的分享配置或配置函数
+ * @returns 包含手动触发或配置的方法句柄
+ *
+ * @example
+ * ```ts
+ * useShare({
+ *   title: '欢迎体验我的小程序',
+ *   path: '/pages/index/index'
+ * });
+ * ```
+ */
 export declare function useShare(config?: ShareConfigResolver): ShareHandlers;

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>;