@hlw-uni/mp-vue 2.1.57 → 2.1.59

package/src/composables/ad/index.ts

@@ -1,33 +1,49 @@
 /**
  * 小程序广告工具。
+ * 提供插屏广告 (Interstitial Ad) 与激励视频广告 (Rewarded Video Ad) 的注册、缓存与展示能力。
  */
 
+declare const uni: any;
 declare const wx: any;
 
+/**
+ * 广告播放/加载结果数据结构。
+ */
 export interface AdRes {
+    /** 广告是否正常加载或成功展示完成 */
     ok: boolean;
+    /** 激励视频是否完全播放完毕 (仅激励视频有此属性) */
     isEnded?: boolean;
+    /** 加载或展示失败时的错误对象 */
     err?: unknown;
 }
 
 type AdDone = (res: AdRes) => void;
 
-let popupAd: any = null;
+// 缓存不同 Unit ID 的广告实例
+const popupCache = new Map<string, any>();
+const rewardCache = new Map<string, any>();
+
+let activePopupAdId = "";
 let popupDone: ((ok: boolean) => void) | undefined;
-let popupClose: (() => void) | null = null;
-let popupError: ((err: unknown) => void) | null = null;
 
-let rewardAd: any = null;
+let activeRewardAdId = "";
 let rewardDone: AdDone | undefined;
 let rewardPromise: Promise<AdRes> | null = null;
 let rewardResolve: ((res: AdRes) => void) | null = null;
-let rewardClose: ((res: { isEnded?: boolean }) => void) | null = null;
-let rewardError: ((err: unknown) => void) | null = null;
 
-function api() {
-    return typeof wx === "undefined" ? null : wx;
+/**
+ * 获取当前环境的小程序全局 API 实例。
+ */
+function getAdApi() {
+    if (typeof uni !== "undefined") return uni;
+    if (typeof wx !== "undefined") return wx;
+    return null;
 }
 
+/**
+ * 触发激励视频广告结束的回调并 resolve Promise。
+ */
 function finish(res: AdRes) {
     rewardDone?.(res);
     rewardResolve?.(res);
@@ -35,46 +51,75 @@ function finish(res: AdRes) {
     rewardPromise = null;
 }
 
-function clearReward() {
-    if (!rewardAd) return;
-    if (rewardClose) rewardAd.offClose?.(rewardClose);
-    if (rewardError) rewardAd.offError?.(rewardError);
-    rewardClose = null;
-    rewardError = null;
-}
-
+/**
+ * 小程序广告 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 function useHlwAd() {
-    function clearPopup() {
-        if (!popupAd) return;
-        if (popupClose) popupAd.offClose?.(popupClose);
-        if (popupError) popupAd.offError?.(popupError);
-        popupClose = null;
-        popupError = null;
-    }
-
+    /**
+     * 配置/预加载插屏广告。
+     * 
+     * @param adId 广告单元 ID
+     * @param done 广告关闭后的回调（可选）
+     * @returns 是否配置成功
+     */
     function setAdPopup(adId: string, done?: (ok: boolean) => void): boolean {
         popupDone = done;
-        const wxApi = api();
-        if (!adId || !wxApi?.createInterstitialAd) return false;
-
-        clearPopup();
-        popupAd = wxApi.createInterstitialAd({ adUnitId: adId });
-        popupAd.onLoad?.(() => {});
-        popupError = (err: unknown) => {
-            console.error("插屏广告加载失败", err);
-            popupDone?.(false);
-        };
-        popupClose = () => {
-            popupDone?.(true);
-        };
-        popupAd.onError?.(popupError);
-        popupAd.onClose?.(popupClose);
+        if (!adId) return false;
+
+        const api = getAdApi();
+        if (!api?.createInterstitialAd) return false;
+
+        activePopupAdId = adId;
+        if (!popupCache.has(adId)) {
+            try {
+                const ad = api.createInterstitialAd({ adUnitId: adId });
+                ad.onLoad?.(() => console.log(`[HlwAd] Interstitial loaded: ${adId}`));
+                ad.onError?.((err: unknown) => {
+                    console.error("[HlwAd] Interstitial load error:", err);
+                    if (activePopupAdId === adId) {
+                        popupDone?.(false);
+                    }
+                });
+                ad.onClose?.(() => {
+                    if (activePopupAdId === adId) {
+                        popupDone?.(true);
+                    }
+                });
+                popupCache.set(adId, ad);
+            } catch (e) {
+                console.error("[HlwAd] Interstitial creation failed:", e);
+                return false;
+            }
+        }
         return true;
     }
 
+    /**
+     * 延迟展示已配置的插屏广告。
+     * 
+     * @param delay 延迟毫秒数，默认 3000ms
+     * @returns 返回 Promise，resolve 是否成功显示且用户关闭了它
+     */
     function showAdPopup(delay = 3000): Promise<boolean> {
         return new Promise((resolve) => {
-            if (!popupAd) {
+            const ad = popupCache.get(activePopupAdId);
+            if (!ad) {
                 resolve(false);
                 return;
             }
@@ -86,44 +131,72 @@ export function useHlwAd() {
             };
 
             setTimeout(() => {
-                popupAd.show().catch((err: unknown) => {
-                    console.error("插屏广告显示失败", err);
+                ad.show().catch((err: unknown) => {
+                    console.error("[HlwAd] Interstitial show error:", err);
                     popupDone?.(false);
                 });
             }, Math.max(0, delay));
         });
     }
 
-
+    /**
+     * 配置/预加载激励视频广告。
+     * 
+     * @param adId 广告单元 ID
+     * @param done 播放结束的回调（可选）
+     * @returns 返回 Promise<AdRes>，在加载或创建失败时直接 resolve
+     */
     function setAdReward(adId: string, done?: AdDone): Promise<AdRes> {
         rewardDone = done;
         rewardPromise = new Promise((resolve) => {
             rewardResolve = resolve;
         });
 
-        const wxApi = api();
-        if (!adId || !wxApi?.createRewardedVideoAd) {
+        if (!adId) {
             finish({ ok: false });
             return rewardPromise;
         }
 
-        clearReward();
-        rewardAd = wxApi.createRewardedVideoAd({ adUnitId: adId });
-        rewardAd.onLoad?.(() => {});
-        rewardClose = (res: { isEnded?: boolean }) => {
-            finish({ ok: !!res?.isEnded, isEnded: !!res?.isEnded });
-        };
-        rewardError = (err: unknown) => {
-            console.error("激励视频广告加载失败", err);
-            finish({ ok: false, err });
-        };
-        rewardAd.onClose?.(rewardClose);
-        rewardAd.onError?.(rewardError);
+        const api = getAdApi();
+        if (!api?.createRewardedVideoAd) {
+            finish({ ok: false });
+            return rewardPromise;
+        }
+
+        activeRewardAdId = adId;
+        if (!rewardCache.has(adId)) {
+            try {
+                const ad = api.createRewardedVideoAd({ adUnitId: adId });
+                ad.onLoad?.(() => console.log(`[HlwAd] Rewarded video loaded: ${adId}`));
+                ad.onError?.((err: unknown) => {
+                    console.error("[HlwAd] Rewarded video load error:", err);
+                    if (activeRewardAdId === adId) {
+                        finish({ ok: false, err });
+                    }
+                });
+                ad.onClose?.((res: { isEnded?: boolean }) => {
+                    if (activeRewardAdId === adId) {
+                        const isEnded = !!res?.isEnded;
+                        finish({ ok: isEnded, isEnded });
+                    }
+                });
+                rewardCache.set(adId, ad);
+            } catch (e) {
+                console.error("[HlwAd] Rewarded video creation failed:", e);
+                finish({ ok: false, err: e });
+            }
+        }
         return rewardPromise;
     }
 
+    /**
+     * 立即播放已加载的激励视频广告。
+     * 
+     * @returns 返回 Promise<AdRes>，指示广告是否正常播放完毕
+     */
     function showAdReward(): Promise<AdRes> {
-        if (!rewardAd) {
+        const ad = rewardCache.get(activeRewardAdId);
+        if (!ad) {
             return Promise.resolve({ ok: false });
         }
 
@@ -132,11 +205,11 @@ export function useHlwAd() {
         });
         rewardPromise = current;
 
-        rewardAd.show().catch(() => {
-            rewardAd.load()
-                .then(() => rewardAd.show())
+        ad.show().catch(() => {
+            ad.load()
+                .then(() => ad.show())
                 .catch((err: unknown) => {
-                    console.error("激励视频广告显示失败", err);
+                    console.error("[HlwAd] Rewarded video show error:", err);
                     finish({ ok: false, err });
                 });
         });
@@ -151,3 +224,4 @@ export function useHlwAd() {
         showAdReward,
     };
 }
+

package/src/composables/device/index.ts

@@ -1,8 +1,12 @@
 /**
  * useDevice - 设备信息与接口 query
+ * 提供一致的、缓存后的多端设备系统信息接口。
  */
-import { useUtils } from "../utils";
+import { toQuery } from "../utils";
 
+/**
+ * 完整设备系统信息接口，包含小程序环境与宿主系统的关键元数据。
+ */
 export interface DeviceInfo {
     /** 小程序 appId */
     appid: string;
@@ -62,6 +66,9 @@ export interface DeviceInfo {
     version: string;
 }
 
+/**
+ * 过滤后常用于接口公共请求 Query 的设备字段子集。
+ */
 export type DeviceQueryInfo = Pick<DeviceInfo,
     | "appid"
     | "device_brand"
@@ -86,6 +93,9 @@ export type DeviceQueryInfo = Pick<DeviceInfo,
 
 let deviceCache: DeviceInfo | null = null;
 
+/**
+ * 安全地执行获取系统信息的函数，防止环境不支持导致异常崩溃。
+ */
 function readSafe(fn: (() => unknown) | undefined): Record<string, unknown> {
     try {
         return (fn?.() ?? {}) as Record<string, unknown>;
@@ -94,6 +104,9 @@ function readSafe(fn: (() => unknown) | undefined): Record<string, unknown> {
     }
 }
 
+/**
+ * 从运行期 API 采集设备与系统属性，建立标准化数据。
+ */
 function collectDevice(): DeviceInfo {
     // @ts-ignore - 新 API 在旧版 @dcloudio/types 中可能未声明。
     let device = readSafe(uni.getDeviceInfo);
@@ -142,6 +155,9 @@ function collectDevice(): DeviceInfo {
     };
 }
 
+/**
+ * 尝试从小程序运行期 context 中读取 AppId。
+ */
 function getAppid(device: Record<string, unknown>) {
     try {
         const account = uni.getAccountInfoSync() as { miniProgram?: { appId?: string } };
@@ -151,11 +167,17 @@ function getAppid(device: Record<string, unknown>) {
     }
 }
 
+/**
+ * 读取或延迟初始化缓存的设备信息。
+ */
 function getDevice() {
     deviceCache ??= collectDevice();
     return deviceCache;
 }
 
+/**
+ * 抽取供接口调用的缩略版设备 query 字段。
+ */
 function getQueryInfo(info: DeviceInfo): DeviceQueryInfo {
     return {
         appid: info.appid,
@@ -180,9 +202,13 @@ function getQueryInfo(info: DeviceInfo): DeviceQueryInfo {
     };
 }
 
+/**
+ * 访问当前设备配置信息的 hooks。
+ * 
+ * @returns 包含 `info` (原始数据) 和 `query` (用于 HTTP 报头/URL query 的 urlencoded 字符串)
+ */
 export function useDevice() {
     const info = getDevice();
-    const { toQuery } = useUtils();
 
     return {
         info,
@@ -190,6 +216,10 @@ export function useDevice() {
     };
 }
 
+/**
+ * 清除本地设备信息缓存，使下一次读取重新走系统调用收集。
+ */
 export function clearDeviceCache(): void {
     deviceCache = null;
 }
+

package/src/composables/index.ts

@@ -15,7 +15,24 @@ export {
     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";
 
 // Theme（mp-vue 自带）

package/src/composables/msg/index.ts

@@ -1,52 +1,111 @@
 /**
  * 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 function useMsg(): HlwMsg {
     /**
      * 显示普通 toast，支持字符串或完整配置。
      */
     function toast(opts: ToastOptions | string) {
-        const normalized: ToastOptions = typeof opts === "string" ? { message: opts } : opts;
-        const { message, icon = "none", image, duration = 2000, mask = false, position = "center" } = normalized;
-        uni.showToast({ title: message, icon, image, duration, mask, position });
+        const {
+            message,
+            icon = "none",
+            image = undefined,
+            duration = 2000,
+            mask = false,
+            position = "center",
+        } = typeof opts === "string" ? { message: opts } : opts;
+
+        // 兼容映射旧版自定义失败图标到标准 error 图标
+        const mappedIcon = (icon === "fail" || icon === "exception") ? "error" : icon;
+
+        uni.showToast({
+            title: message,
+            icon: mappedIcon as "success" | "loading" | "error" | "none",
+            image,
+            duration,
+            mask,
+            position,
+        });
     }
 
     /**
@@ -60,7 +119,7 @@ export function useMsg(): HlwMsg {
      * 显示失败提示。
      */
     function error(message: string) {
-        uni.showToast({ title: message, icon: "fail", duration: 2000 });
+        uni.showToast({ title: message, icon: "error", duration: 2000 });
     }
 
     /**
@@ -105,20 +164,14 @@ export function useMsg(): HlwMsg {
         });
     }
 
-    /**
-     * modal 是 confirm 的语义别名。
-     */
-    function modal(opts: ModalOptions): Promise<boolean> {
-        return confirm(opts);
-    }
-
     /**
      * 通过标题文本模拟简单进度条展示。
      */
     function setLoadingBar(progress: number) {
         const clamped = Math.max(0, Math.min(100, progress));
+        const filled = Math.round(clamped / 2);
         uni.setNavigationBarTitle({
-            title: `${"■".repeat(Math.round(clamped / 2))}${"□".repeat(50 - Math.round(clamped / 2))} ${clamped}%`,
+            title: `${"■".repeat(filled)}${"□".repeat(50 - filled)} ${clamped}%`,
         });
     }
 
@@ -130,7 +183,8 @@ export function useMsg(): HlwMsg {
         showLoading,
         hideLoading,
         confirm,
-        modal,
+        modal: confirm,
         setLoadingBar,
     };
 }
+

package/src/composables/navigator/index.ts

@@ -1,6 +1,9 @@
 /**
- * useNavigate - uni-app 跳转工具
+ * useNavigate - uni-app 路由跳转工具
+ * 封装并统一原生的页面跳转、重定向、Switch Tab、返回、以及打开外部小程序或 WebView 等方法。
  */
+
+/** 页面跳转类型，支持微信小程序的各类路由动作与 WebView/小程序跳转 */
 export type NavigateType =
     | "navigateTo"
     | "redirectTo"
@@ -11,17 +14,29 @@ export type NavigateType =
     | "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>;
 }
 
 type UniFail = { errMsg?: string };
 
+/**
+ * 集中处理跳转失败时的提示与回调。
+ */
 function fail(message: string, options: NavigateOptions = {}) {
     if (!options.silent) {
         uni.showToast({ title: message, icon: "none" });
@@ -29,12 +44,22 @@ function fail(message: string, options: NavigateOptions = {}) {
     options.onFail?.(message);
 }
 
+/**
+ * 创建符合 uni-app 失败规范的回调处理函数。
+ */
 function failHandler(target: string, options: NavigateOptions = {}) {
     return (error?: UniFail) => {
         fail(error?.errMsg || `无法跳转：${target}`, options);
     };
 }
 
+/**
+ * 核心的底层页面路由分发方法。
+ * 
+ * @param type 跳转动作类型
+ * @param url 跳转目标路径或小程序 AppId
+ * @param options 额外的控制参数
+ */
 function navigate(type: NavigateType = "navigateTo", url = "", options: NavigateOptions = {}) {
     if (type === "navigateBack") {
         uni.navigateBack({ delta: options.delta || 1, fail: failHandler("返回上一页", options) });
@@ -91,14 +116,33 @@ function navigate(type: NavigateType = "navigateTo", url = "", options: Navigate
     uni.navigateTo({ url, fail: onFail });
 }
 
+/**
+ * 路由跳转工具 hooks。
+ * 
+ * @example
+ * ```ts
+ * const router = useNavigate();
+ * router.to('/pages/index/index');
+ * router.back();
+ * router.miniProgram('app-id');
+ * ```
+ */
 export function useNavigate() {
     return {
+        /** 核心底层路由分发函数 */
         navigate,
+        /** 保留当前页面，跳转到应用内的某个页面 */
         to: (url: string, options?: NavigateOptions) => navigate("navigateTo", url, options),
+        /** 关闭当前页面，跳转到应用内的某个页面 */
         redirect: (url: string, options?: NavigateOptions) => navigate("redirectTo", url, options),
+        /** 跳转到 switchTab 页面，并关闭其他所有非 tabBar 页面 */
         tab: (url: string, options?: NavigateOptions) => navigate("switchTab", url, options),
+        /** 关闭所有页面，打开到应用内的某个页面 */
         reLaunch: (url: string, options?: NavigateOptions) => navigate("reLaunch", url, options),
+        /** 关闭当前页面，返回上一页面或多级页面 */
         back: (delta = 1, options: NavigateOptions = {}) => navigate("navigateBack", "", { ...options, delta }),
+        /** 打开另一个小程序 */
         miniProgram: (appId: string, options?: NavigateOptions) => navigate("miniprogram", appId, options),
     };
 }
+