@hlw-uni/mp-vue 2.1.10 → 2.1.12

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

@@ -62,7 +62,7 @@ export declare function useAd(): {
     loadConfig: (force?: boolean) => Promise<void>;
     getUnitId: (type: AdType) => string;
     showReward: (onClose?: ((res: AdCloseResult) => void | Promise<void>) | undefined) => Promise<void>;
-    showPopup: () => Promise<boolean>;
+    showPopup: (delayMs?: number) => Promise<boolean>;
     confirm: typeof confirmModal;
 };
 /**

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

@@ -0,0 +1,7 @@
+/**
+ * 算法集：把通用算法包成 useXxx composable，业务侧统一从这里取。
+ *
+ * 已有：
+ *   - useUuid  RFC 4122 v4，32 字符 hex
+ */
+export { useUuid } from './uuid';

package/dist/composables/algo/uuid.d.ts

@@ -0,0 +1,17 @@
+/**
+ * UUID v4 生成器（RFC 4122 v4 算法），返回 32 字符 hex（无连字符）。
+ *
+ * 用途：当 nonce、idempotency key、临时唯一标识用。
+ *
+ * 算法：
+ *   1. 生成 16 字节随机源
+ *   2. byte 6 高 4 位置成 0100 标版本号 v4
+ *   3. byte 8 高 2 位置成 10 标变体（RFC 4122）
+ *   4. 16 字节转 hex 拼成 32 字符串
+ *
+ * 注意：随机源用 Math.random（小程序兼容兜底），加密强度有限，
+ * 不能用于密钥派生 / token 签发，只能挡重放。
+ */
+export declare function useUuid(): {
+    v4: () => string;
+};

package/dist/composables/index.d.ts

@@ -16,6 +16,7 @@ export { useContact, setConfigContact, type ContactConfig, type ContactAdapter,
 export { useUtils, type DownloadFileOptions, type DownloadFileResult, type TapEvent } from './utils';
 export { useColor } from './color';
 export { useRouter, type NavigateType, type NavigateOptions } from './navigator';
+export { useUuid } from './algo';
 export type { FontScale, FontPreset } from './theme';
 export { FONT_SCALE_KEY, FONT_PRESETS, getCurrentFontScale, getCurrentFontVars, THEME_CHANGE_EVENT, buildThemeStyle, useThemePageStyle, } from './theme';
 export type { ThemeColor } from './theme';

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

@@ -15,12 +15,12 @@ export interface NavigateOptions {
     onFail?: (errMsg: string) => void;
     /** 是否禁用默认的 Toast 错误提示，默认 false */
     silent?: boolean;
-    /** 仅 miniprogram：目标小程序的页面路径（如 pages/index/index?id=1），留空则打开首页 */
-    path?: string;
+    /** 仅 miniprogram：目标小程序的页面路径（如 pages/index/index?id=1），留空/null 则打开首页 */
+    path?: string | null;
     /** 仅 miniprogram：目标小程序版本，默认 release */
     envVersion?: "develop" | "trial" | "release";
     /** 仅 miniprogram：传给目标小程序的额外数据，对方从 onLaunch/onShow 读取 */
-    extraData?: Record<string, unknown>;
+    extraData?: Record<string, unknown> | null;
 }
 /**
  * 根据 type + value 调用对应的 uni API，屏蔽参数差异。

package/dist/index.js

@@ -630,6 +630,7 @@ var __publicField = (obj, key, value) => {
     }
     return raw;
   }
+  const DEFAULT_POPUP_DELAY_MS = 3e3;
   const EMPTY = {
     banner_unit_id: "",
     grid_unit_id: "",
@@ -686,7 +687,6 @@ var __publicField = (obj, key, value) => {
       return store.config[`${type}_unit_id`] || "";
     }
     async function showReward(onClose) {
-      await loadConfig2();
       const unitId = getUnitId("reward");
       if (!unitId) {
         msg().toast("激励广告未配置");
@@ -700,12 +700,19 @@ var __publicField = (obj, key, value) => {
       if (onClose)
         await onClose(closeRes);
     }
-    async function showPopup() {
-      await loadConfig2();
-      const unitId = getUnitId("popup");
-      if (!unitId)
-        return false;
-      return await showInterstitialAd(unitId);
+    function showPopup(delayMs = DEFAULT_POPUP_DELAY_MS) {
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          loadConfig2().then(() => {
+            const unitId = getUnitId("popup");
+            if (!unitId) {
+              resolve(false);
+              return;
+            }
+            showInterstitialAd(unitId).then(resolve);
+          });
+        }, delayMs);
+      });
     }
     return {
       // 状态
@@ -1115,7 +1122,7 @@ var __publicField = (obj, key, value) => {
           appId: value,
           path: options.path || "",
           envVersion: options.envVersion,
-          extraData: options.extraData,
+          extraData: options.extraData ?? void 0,
           fail
         });
         break;
@@ -1131,6 +1138,18 @@ var __publicField = (obj, key, value) => {
       navigate: doNavigate
     };
   }
+  function useUuid() {
+    function v4() {
+      const bytes = [];
+      for (let i = 0; i < 16; i++) {
+        bytes.push(Math.floor(Math.random() * 256));
+      }
+      bytes[6] = bytes[6] & 15 | 64;
+      bytes[8] = bytes[8] & 63 | 128;
+      return bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
+    }
+    return { v4 };
+  }
   const useThemeStore = pinia.defineStore(
     "theme",
     () => {
@@ -1933,6 +1952,7 @@ var __publicField = (obj, key, value) => {
   exports2.useThemeStore = useThemeStore;
   exports2.useUpload = useUpload;
   exports2.useUtils = useUtils;
+  exports2.useUuid = useUuid;
   exports2.useValidate = useValidate;
   exports2.vCopy = vCopy;
   Object.defineProperty(exports2, Symbol.toStringTag, { value: "Module" });

package/dist/index.mjs

@@ -629,6 +629,7 @@ function unwrapPayload(raw) {
   }
   return raw;
 }
+const DEFAULT_POPUP_DELAY_MS = 3e3;
 const EMPTY = {
   banner_unit_id: "",
   grid_unit_id: "",
@@ -685,7 +686,6 @@ function useAd() {
     return store.config[`${type}_unit_id`] || "";
   }
   async function showReward(onClose) {
-    await loadConfig2();
     const unitId = getUnitId("reward");
     if (!unitId) {
       msg().toast("激励广告未配置");
@@ -699,12 +699,19 @@ function useAd() {
     if (onClose)
       await onClose(closeRes);
   }
-  async function showPopup() {
-    await loadConfig2();
-    const unitId = getUnitId("popup");
-    if (!unitId)
-      return false;
-    return await showInterstitialAd(unitId);
+  function showPopup(delayMs = DEFAULT_POPUP_DELAY_MS) {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        loadConfig2().then(() => {
+          const unitId = getUnitId("popup");
+          if (!unitId) {
+            resolve(false);
+            return;
+          }
+          showInterstitialAd(unitId).then(resolve);
+        });
+      }, delayMs);
+    });
   }
   return {
     // 状态
@@ -1114,7 +1121,7 @@ function doNavigate(type, value, options = {}) {
         appId: value,
         path: options.path || "",
         envVersion: options.envVersion,
-        extraData: options.extraData,
+        extraData: options.extraData ?? void 0,
         fail
       });
       break;
@@ -1130,6 +1137,18 @@ function useRouter() {
     navigate: doNavigate
   };
 }
+function useUuid() {
+  function v4() {
+    const bytes = [];
+    for (let i = 0; i < 16; i++) {
+      bytes.push(Math.floor(Math.random() * 256));
+    }
+    bytes[6] = bytes[6] & 15 | 64;
+    bytes[8] = bytes[8] & 63 | 128;
+    return bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  return { v4 };
+}
 const useThemeStore = defineStore(
   "theme",
   () => {
@@ -1933,6 +1952,7 @@ export {
   useThemeStore,
   useUpload,
   useUtils,
+  useUuid,
   useValidate,
   vCopy
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hlw-uni/mp-vue",
-    "version": "2.1.10",
+    "version": "2.1.12",
     "description": "hlw-uni 小程序运行时 — Vue 组件 + composables + theme + http + 工具集（合并自原 mp-core）",
     "main": "dist/index.js",
     "module": "dist/index.mjs",

package/src/composables/ad/index.ts

@@ -47,6 +47,9 @@ import { ref } from "vue";
 import { useMsg, type HlwMsg } from "../msg";
 import { unwrapPayload, type AdapterPayload } from "../_internal/unwrap";
 
+/** showPopup 默认延迟（ms）：避免一进页面就弹打扰用户 */
+const DEFAULT_POPUP_DELAY_MS = 3000;
+
 /** 6 种广告类型 */
 export type AdType = "banner" | "grid" | "custom" | "video" | "reward" | "popup";
 
@@ -184,7 +187,6 @@ export function useAd() {
      * @param onClose 关闭回调；不传则只播。retry / toast / 发奖全在业务侧自己写。
      */
     async function showReward(onClose?: (res: AdCloseResult) => void | Promise<void>): Promise<void> {
-        await loadConfig();
         const unitId = getUnitId("reward");
         if (!unitId) {
             msg().toast("激励广告未配置");
@@ -202,11 +204,28 @@ export function useAd() {
      * 显示插屏广告
      * @returns true=展示成功；false=配置缺失 / show 失败（如近期已展示过）
      */
-    async function showPopup(): Promise<boolean> {
-        await loadConfig();
-        const unitId = getUnitId("popup");
-        if (!unitId) return false;
-        return await showInterstitialAd(unitId);
+    /**
+     * 显示插屏广告，默认延迟 3000ms 避免一进页面就弹打扰；传 0 立即弹。
+     * @returns true=展示成功；false=配置缺失 / show 失败（如近期已展示过）
+     *
+     * 实现注意：用 setTimeout + .then() 串接而非 async/await，保持 WX 插屏
+     * ad.show() 的调用栈跟 setTimeout 回调一致 —— 小程序引擎对插屏的合法
+     * 触发时机敏感，async/await 多插的 microtask 会被判为"非合法触发"导致
+     * 静默不弹。
+     */
+    function showPopup(delayMs: number = DEFAULT_POPUP_DELAY_MS): Promise<boolean> {
+        return new Promise<boolean>((resolve) => {
+            setTimeout(() => {
+                loadConfig().then(() => {
+                    const unitId = getUnitId("popup");
+                    if (!unitId) {
+                        resolve(false);
+                        return;
+                    }
+                    showInterstitialAd(unitId).then(resolve);
+                });
+            }, delayMs);
+        });
     }
 
     return {

package/src/composables/algo/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 算法集：把通用算法包成 useXxx composable，业务侧统一从这里取。
+ *
+ * 已有：
+ *   - useUuid  RFC 4122 v4，32 字符 hex
+ */
+export { useUuid } from "./uuid";

package/src/composables/algo/uuid.ts

@@ -0,0 +1,27 @@
+/**
+ * UUID v4 生成器（RFC 4122 v4 算法），返回 32 字符 hex（无连字符）。
+ *
+ * 用途：当 nonce、idempotency key、临时唯一标识用。
+ *
+ * 算法：
+ *   1. 生成 16 字节随机源
+ *   2. byte 6 高 4 位置成 0100 标版本号 v4
+ *   3. byte 8 高 2 位置成 10 标变体（RFC 4122）
+ *   4. 16 字节转 hex 拼成 32 字符串
+ *
+ * 注意：随机源用 Math.random（小程序兼容兜底），加密强度有限，
+ * 不能用于密钥派生 / token 签发，只能挡重放。
+ */
+export function useUuid() {
+    function v4(): string {
+        const bytes: number[] = [];
+        for (let i = 0; i < 16; i++) {
+            bytes.push(Math.floor(Math.random() * 256));
+        }
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        return bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
+    }
+
+    return { v4 };
+}

package/src/composables/index.ts

@@ -45,6 +45,7 @@ export {
 export { useUtils, type DownloadFileOptions, type DownloadFileResult, type TapEvent } from "./utils";
 export { useColor } from "./color";
 export { useRouter, type NavigateType, type NavigateOptions } from "./navigator";
+export { useUuid } from "./algo";
 
 // Theme（mp-vue 自带）
 export type { FontScale, FontPreset } from "./theme";

package/src/composables/navigator/index.ts

@@ -24,12 +24,12 @@ export interface NavigateOptions {
     onFail?: (errMsg: string) => void;
     /** 是否禁用默认的 Toast 错误提示，默认 false */
     silent?: boolean;
-    /** 仅 miniprogram：目标小程序的页面路径（如 pages/index/index?id=1），留空则打开首页 */
-    path?: string;
+    /** 仅 miniprogram：目标小程序的页面路径（如 pages/index/index?id=1），留空/null 则打开首页 */
+    path?: string | null;
     /** 仅 miniprogram：目标小程序版本，默认 release */
     envVersion?: "develop" | "trial" | "release";
     /** 仅 miniprogram：传给目标小程序的额外数据，对方从 onLaunch/onShow 读取 */
-    extraData?: Record<string, unknown>;
+    extraData?: Record<string, unknown> | null;
 }
 
 /**
@@ -78,7 +78,7 @@ function doNavigate(type: NavigateType, value: string, options: NavigateOptions
                 appId: value,
                 path: options.path || "",
                 envVersion: options.envVersion,
-                extraData: options.extraData,
+                extraData: options.extraData ?? undefined,
                 fail,
             });
             break;