@hlw-uni/mp-vue 2.1.70 → 2.1.97

package/src/utils/ad/README.md

@@ -0,0 +1,114 @@
+# 广告模块 (Ad Utility & Component)
+
+提供微信小程序**插屏广告 (Interstitial Ad)** 与 **激励视频广告 (Rewarded Video Ad)** 的注册、预加载与展示播放能力，并提供了开箱即用的高层封装组件 `<hlw-reward-ad>`。
+
+---
+
+## 1. 推荐：高层组件 `<hlw-reward-ad>`
+
+组件内部全面封装并接管了激励视频广告的完整生命周期管理：
+* **自动预加载**：组件挂载或广告 ID（`unitId`）变更时，在后台自动完成首帧广告的静默加载。
+* **Loading 状态处理**：拉起广告时自动弹出全局模态 Loading，防止穿透及多重点击。
+* **智能断点续看 (中途退出拦截)**：当用户中途关闭广告时，组件内会自动拦截并弹出二级确认对话框（“继续观看”与“取消”），选择继续将自动递归重新拉起播放。
+* **关闭后自动滚加载**：当一次广告播放流关闭（完成或中途取消）后，组件立即在后台重新静默预加载下一个广告，保证下一次秒开。
+
+### 引入组件 (easycom / 直接引用)
+
+```html
+<template>
+    <hlw-reward-ad :unit-id="rewardUnitId" @onHandle="handleRewardAd">
+        <hlw-button type="primary" round>点击观看广告获取金币</hlw-button>
+    </hlw-reward-ad>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import type { AdRes } from "@hlw-uni/mp-vue";
+
+const rewardUnitId = ref("adunit-xxx");
+
+function handleRewardAd(res: AdRes) {
+    if (res.success && res.isEnded) {
+        // 用户已成功并且完整看完激励视频广告
+        hlw.$msg.success("观看完成，奖励已发放！");
+    } else if (res.err) {
+        // 播放出错
+        hlw.$msg.toast("广告播放失败，请稍后重试");
+    } else {
+        // 用户主动中途退出并拒绝继续观看，或其它拉起失败情况
+        hlw.$msg.toast("播放中途退出或拉起失败");
+    }
+}
+</script>
+```
+
+---
+
+## 2. 底层接口 (Low-Level APIs)
+
+在不需要使用标准 UI 组件而需要通过代码细粒度控盘的自定义场景下，可以直接导入并调用底层方法。
+
+```ts
+import { 
+    setPopupAd, 
+    showPopupAd, 
+    setRewardAd, 
+    showRewardAd, 
+    confirmRewardAd 
+} from "@hlw-uni/mp-vue";
+```
+
+### 插屏广告 (Interstitial Ad)
+
+```ts
+// 1. 初始化并注册插屏广告单元，提供可选的关闭回调
+setPopupAd("adunit-popup-id", (success) => {
+    console.log("插屏广告被关闭，是否播放成功:", success);
+});
+
+// 2. 延迟拉起展示插屏广告 (默认延迟 3000 毫秒展示)
+await showPopupAd(1000);
+```
+
+### 激励视频广告 (Rewarded Video Ad)
+
+```ts
+// 1. 注册并预加载激励视频广告单元
+await setRewardAd("adunit-reward-id");
+
+// 2. 立即拉起播放广告
+const res = await showRewardAd();
+
+if (res.success && res.isEnded) {
+    // 成功发放奖励
+} else {
+    // 处理退出或报错
+}
+```
+
+---
+
+## 3. API 列表
+
+| 方法名 | 参数 | 返回值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `setPopupAd(adId, done?)` | `adId: string, done?: (ok: boolean) => void` | `boolean` | 创建/拉取缓存的插屏广告实例。 |
+| `showPopupAd(delay?)` | `delay?: number` | `Promise<boolean>` | 延迟展示已配置的插屏广告（默认 3000ms）。 |
+| `setRewardAd(adId, done?)` | `adId: string, done?: (res: AdRes) => void` | `Promise<AdRes>` | 预加载激励视频广告实例，并在 `onClose` 事件回调中自动加入重新静默预加载功能。 |
+| `showRewardAd(onShowSuccess?)` | `onShowSuccess?: () => void` | `Promise<AdRes>` | 立即拉起展示激励视频，拉起失败时自动执行 `load()` 并二次重试。 |
+| `confirmRewardAd()` | 无 | `Promise<boolean>` | 内置的通用二级确认模态框，内置灰色取消文字（`#999999`）与蓝色确认文字（`#3b82f6`）。 |
+
+---
+
+## 4. 类型定义
+
+```typescript
+export interface AdRes {
+    /** 广告是否正常加载或成功展示完成 */
+    success: boolean;
+    /** 激励视频是否完全播放完毕 (仅激励视频有此属性) */
+    isEnded: boolean;
+    /** 加载或展示失败时的错误对象 */
+    err?: any;
+}
+```

package/src/utils/ad/index.ts

@@ -0,0 +1,234 @@
+/**
+ * 小程序广告工具。
+ * 提供插屏广告 (Interstitial Ad) 与激励视频广告 (Rewarded Video Ad) 的注册、缓存与展示能力。
+ */
+
+declare const uni: any;
+
+/**
+ * 广告播放/加载结果数据结构。
+ */
+export interface AdRes {
+    /** 广告是否正常加载或成功展示完成 */
+    success: boolean;
+    /** 激励视频是否完全播放完毕 (仅激励视频有此属性) */
+    isEnded: boolean;
+    /** 加载或展示失败时的错误对象 */
+    err?: any;
+}
+
+// 缓存不同 Unit ID 的广告实例，防止重复创建导致内存泄露或回调叠加
+const adInstances = new Map<string, any>();
+
+// 当前激活的广告单元 ID 与回调函数句柄
+let activePopupId = "";
+let activeRewardId = "";
+
+let popupCallback: ((ok: boolean) => void) | undefined;
+let rewardCallback: ((res: AdRes) => void) | undefined;
+
+let rewardPromise: Promise<AdRes> | null = null;
+let rewardResolve: ((res: AdRes) => void) | null = null;
+
+/**
+ * 统一触发激励视频广告结束回调并销毁当前的 Promise 句柄
+ */
+function resolveReward(res: AdRes) {
+    rewardCallback?.(res);
+    rewardResolve?.(res);
+    rewardResolve = null;
+    rewardPromise = null;
+}
+
+/**
+ * 配置/预加载插屏广告
+ * 
+ * @param adId 广告单元 ID
+ * @param done 广告关闭后的回调（可选）
+ * @returns 是否配置成功
+ */
+export function setPopupAd(adId: string, done?: (ok: boolean) => void): boolean {
+    popupCallback = done;
+    if (!adId || !uni.createInterstitialAd) return false;
+
+    activePopupId = adId;
+    if (!adInstances.has(adId)) {
+        try {
+            const ad = uni.createInterstitialAd({ adUnitId: adId });
+            ad.onLoad?.(() => console.log(`[Ad] Interstitial loaded: ${adId}`));
+            ad.onError?.((err: any) => {
+                console.error("[Ad] Interstitial load error:", err);
+                if (activePopupId === adId) popupCallback?.(false);
+            });
+            ad.onClose?.(() => {
+                if (activePopupId === adId) popupCallback?.(true);
+            });
+            adInstances.set(adId, ad);
+        } catch (e) {
+            console.error("[Ad] Interstitial creation failed:", e);
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * 延迟展示已配置的插屏广告
+ * 
+ * @param delay 延迟毫秒数，默认 3000ms
+ * @returns 返回 Promise，指示是否成功显示且被关闭
+ */
+export function showPopupAd(delay = 3000): Promise<boolean> {
+    return new Promise((resolve) => {
+        const ad = adInstances.get(activePopupId);
+        if (!ad) {
+            resolve(false);
+            return;
+        }
+
+        const originalDone = popupCallback;
+        popupCallback = (ok: boolean) => {
+            originalDone?.(ok);
+            resolve(ok);
+        };
+
+        setTimeout(
+            () => {
+                ad.show().catch((err: any) => {
+                    console.error("[Ad] Interstitial show error:", err);
+                    popupCallback?.(false);
+                });
+            },
+            Math.max(0, delay),
+        );
+    });
+}
+
+/**
+ * 配置/预加载激励视频广告
+ * 
+ * @param adId 广告单元 ID
+ * @param done 播放结束的回调（可选）
+ * @returns 返回 Promise<AdRes>
+ */
+export function setRewardAd(adId: string, done?: (res: AdRes) => void): Promise<AdRes> {
+    rewardCallback = done;
+    rewardPromise = new Promise((resolve) => {
+        rewardResolve = resolve;
+    });
+
+    if (!adId || !uni.createRewardedVideoAd) {
+        resolveReward({ success: false, isEnded: false });
+        return rewardPromise;
+    }
+
+    activeRewardId = adId;
+    if (!adInstances.has(adId)) {
+        try {
+            const ad = uni.createRewardedVideoAd({ adUnitId: adId });
+            ad.onLoad?.(() => console.log(`[Ad] Rewarded video loaded: ${adId}`));
+            ad.onError?.((err: any) => {
+                console.error("[Ad] Rewarded video load error:", err);
+                if (activeRewardId === adId) {
+                    resolveReward({ success: false, isEnded: false, err });
+                }
+            });
+            ad.onClose?.((res: { isEnded?: boolean }) => {
+                if (activeRewardId === adId) {
+                    const ended = !!res?.isEnded;
+                    resolveReward({ success: ended, isEnded: ended });
+                    // 播放结束后立即在后台静默预加载下一个广告，以保证后续拉起流畅且支持重试逻辑
+                    ad.load().catch((err: any) => {
+                        console.warn("[Ad] Silent preload after close failed:", err);
+                    });
+                }
+            });
+            adInstances.set(adId, ad);
+        } catch (e) {
+            console.error("[Ad] Rewarded video creation failed:", e);
+            resolveReward({ success: false, isEnded: false, err: e });
+        }
+    }
+    return rewardPromise;
+}
+
+/**
+ * 立即播放已加载的激励视频广告
+ * 
+ * @param onShowSuccess 广告成功拉起播放时的回调（常用于关闭 Loading 等待提示）
+ * @returns 返回 Promise<AdRes>，指示广告是否正常播放完毕
+ */
+export function showRewardAd(onShowSuccess?: () => void): Promise<AdRes> {
+    const ad = adInstances.get(activeRewardId);
+    if (!ad) {
+        return Promise.resolve({ success: false, isEnded: false });
+    }
+
+    const current =
+        rewardPromise ||
+        new Promise<AdRes>((resolve) => {
+            rewardResolve = resolve;
+        });
+    rewardPromise = current;
+
+    ad.show()
+        .then(() => {
+            onShowSuccess?.();
+        })
+        .catch(() => {
+            ad.load()
+                .then(() => {
+                    ad.show()
+                        .then(() => {
+                            onShowSuccess?.();
+                        })
+                        .catch((err: any) => {
+                            console.error("[Ad] Rewarded video show error:", err);
+                            resolveReward({ success: false, isEnded: false, err });
+                        });
+                })
+                .catch((err: any) => {
+                    console.error("[Ad] Rewarded video load error:", err);
+                    resolveReward({ success: false, isEnded: false, err });
+                });
+        });
+
+    return current;
+}
+
+/**
+ * 弹窗提示需要看完广告才有奖励。
+ * 提供“继续观看”和“取消”按钮。
+ * @returns 返回 Promise<boolean>，用户点击“继续”返回 true，点击“取消”返回 false
+ */
+export function confirmRewardAd(): Promise<boolean> {
+    return new Promise((resolve) => {
+        uni.showModal({
+            title: "提示",
+            content: "需要看完广告才有奖励哦",
+            cancelText: "取消",
+            confirmText: "继续观看",
+            cancelColor: "#999999",
+            confirmColor: "#3b82f6",
+            success: (res: any) => {
+                resolve(!!res.confirm);
+            },
+            fail: () => {
+                resolve(false);
+            },
+        });
+    });
+}
+
+/**
+ * @deprecated 推荐直接从库导入独立函数使用 (例如：import { showRewardAd } from '@hlw-uni/mp-vue')
+ */
+export function useHlwAd() {
+    return {
+        setPopupAd,
+        showPopupAd,
+        setRewardAd,
+        showRewardAd,
+        confirmRewardAd,
+    };
+}

package/src/{composables/utils → utils/common}/index.ts

@@ -44,7 +44,7 @@ export function withQuery(url: string, qs: string): string {
 }
 
 /**
- * 将键值对对象转换为 URL 编码的 Query String。
+ * 将键值对对象转换为 URL 编码 of Query String。
  * 会自动过滤值为 `undefined` 或 `null` 的键。
  * @param data 需要转换的键值对数据对象
  * @returns 格式化后的 Query String 字符串
@@ -275,29 +275,3 @@ export async function saveVideoUrl(url: string, progress?: (value: number) => vo
         return false;
     }
 }
-
-/**
- * 获取系统通用工具方法的 hook。
- * 
- * @example
- * ```ts
- * const { copy, saveImageUrl } = useUtils();
- * copy('hello');
- * ```
- */
-export function useUtils() {
-    return {
-        withQuery,
-        toQuery,
-        signText,
-        toNumber,
-        toBoolean,
-        copy,
-        paste,
-        saveImage,
-        saveVideoFile,
-        download,
-        saveImageUrl,
-        saveVideoUrl,
-    };
-}

package/src/{composables → utils}/device/index.ts

@@ -1,8 +1,8 @@
 /**
- * useDevice - 设备信息与接口 query
+ * 设备信息与接口 query
  * 提供一致的、缓存后的多端设备系统信息接口。
  */
-import { toQuery } from "../utils";
+import { toQuery } from "../common";
 
 /**
  * 完整设备系统信息接口，包含小程序环境与宿主系统的关键元数据。
@@ -18,7 +18,7 @@ export interface DeviceInfo {
     app_version_code: string;
     /** 小程序来源渠道 */
     app_channel: string;
-    /** 设备品牌。如：apple、huawei */
+    /** 设备 brand。如：apple、huawei */
     device_brand: string;
     /** 设备型号 */
     device_model: string;
@@ -167,14 +167,6 @@ function getAppid(device: Record<string, unknown>) {
     }
 }
 
-/**
- * 读取或延迟初始化缓存的设备信息。
- */
-function getDevice() {
-    deviceCache ??= collectDevice();
-    return deviceCache;
-}
-
 /**
  * 抽取供接口调用的缩略版设备 query 字段。
  */
@@ -203,17 +195,18 @@ function getQueryInfo(info: DeviceInfo): DeviceQueryInfo {
 }
 
 /**
- * 访问当前设备配置信息的 hooks。
- * 
- * @returns 包含 `info` (原始数据) 和 `query` (用于 HTTP 报头/URL query 的 urlencoded 字符串)
+ * 获取缓存后的设备信息数据。
  */
-export function useDevice() {
-    const info = getDevice();
+export function getDevice(): DeviceInfo {
+    deviceCache ??= collectDevice();
+    return deviceCache;
+}
 
-    return {
-        info,
-        query: toQuery(getQueryInfo(info)),
-    };
+/**
+ * 获取接口请求专用的设备信息 query 字符串。
+ */
+export function getDeviceQuery(): string {
+    return toQuery(getQueryInfo(getDevice()));
 }
 
 /**
@@ -222,4 +215,3 @@ export function useDevice() {
 export function clearDeviceCache(): void {
     deviceCache = null;
 }
-

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export * from "./ad";
+export * from "./common";
+export * from "./navigator";
+export * from "./device";
+export * from "./request";

package/src/{composables → utils}/navigator/index.ts

@@ -1,5 +1,5 @@
 /**
- * useNavigate - uni-app 路由跳转工具
+ * uni-app 路由跳转工具
  * 封装并统一原生的页面跳转、重定向、Switch Tab、返回、以及打开外部小程序或 WebView 等方法。
  */
 
@@ -60,7 +60,7 @@ function failHandler(target: string, options: NavigateOptions = {}) {
  * @param url 跳转目标路径或小程序 AppId
  * @param options 额外的控制参数
  */
-function navigate(type: NavigateType = "navigateTo", url = "", options: NavigateOptions = {}) {
+export function navigate(type: NavigateType = "navigateTo", url = "", options: NavigateOptions = {}) {
     if (type === "navigateBack") {
         uni.navigateBack({ delta: options.delta || 1, fail: failHandler("返回上一页", options) });
         return;
@@ -113,36 +113,35 @@ function navigate(type: NavigateType = "navigateTo", url = "", options: Navigate
         return;
     }
 
-    uni.navigateTo({ url, fail: onFail });
+    uni.navigateTo({ url, animationType: "none", 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),
-    };
+/** 保留当前页面，跳转到应用内的某个页面 */
+export function navigateTo(url: string, options?: NavigateOptions) {
+    return navigate("navigateTo", url, options);
 }
 
+/** 关闭当前页面，跳转到应用内的某个页面 */
+export function redirectTo(url: string, options?: NavigateOptions) {
+    return navigate("redirectTo", url, options);
+}
+
+/** 跳转到 switchTab 页面，并关闭其他所有非 tabBar 页面 */
+export function switchTab(url: string, options?: NavigateOptions) {
+    return navigate("switchTab", url, options);
+}
+
+/** 关闭所有页面，打开到应用内的某个页面 */
+export function reLaunch(url: string, options?: NavigateOptions) {
+    return navigate("reLaunch", url, options);
+}
+
+/** 关闭当前页面，返回上一页面或多级页面 */
+export function navigateBack(delta = 1, options: NavigateOptions = {}) {
+    return navigate("navigateBack", "", { ...options, delta });
+}
+
+/** 打开另一个小程序 */
+export function navigateToMiniProgram(appId: string, options?: NavigateOptions) {
+    return navigate("miniprogram", appId, options);
+}

package/src/{composables → utils}/request/client.ts

@@ -214,7 +214,7 @@ class UniRequestClient implements RequestClient {
                 filePath: config.filePath,
                 fileName,
                 credentials: config.credentials,
-            });
+              });
 
         return new Promise((resolve, reject) => {
             uni.uploadFile({
@@ -311,17 +311,9 @@ function isAbsolute(url: string): boolean {
 const requestClient = new UniRequestClient();
 
 /**
- * 获取全局请求客户端单例。
- * 
- * @example
- * ```ts
- * const http = useRequest();
- * http.setBaseURL('https://api.example.com');
- * ```
+ * 全局请求客户端单例。
  */
-export function useRequest(): RequestClient {
-    return requestClient;
-}
+export const request: RequestClient = requestClient;
 
 /**
  * 文件上传 composable。

package/src/{composables → utils}/request/index.ts

@@ -1,4 +1,4 @@
-export { useRequest, useUpload } from "./client";
+export { request, useUpload } from "./client";
 export { BaseService, ServiceNamespace, ServicePrefix, PluginService } from "./service";
 export type { RequestClient } from "./client";
 export type {

package/src/{composables → utils}/request/service.ts

@@ -1,4 +1,4 @@
-import { useRequest } from "./client";
+import { request } from "./client";
 import type { ApiResponse, RequestConfig } from "./types";
 
 /**
@@ -52,9 +52,9 @@ export class BaseService {
      * @returns 响应结果 Promise
      */
     request<T = unknown>(options: ServiceRequestConfig): Promise<ApiResponse<T>> {
-        return useRequest().request<T>({
+        return request.request<T>({
             ...options,
-            url: useRequest().resolveServiceUrl(this.namespace ?? "", options.url, this.servicePrefix ?? ""),
+            url: request.resolveServiceUrl(this.namespace ?? "", options.url, this.servicePrefix ?? ""),
         });
     }
 
@@ -70,7 +70,7 @@ export class BaseService {
     /**
      * 快捷发送 POST 请求。
      * @param url 请求相对路径
-     * @param data 请求携带的 body
+     * @param data 请求携带 the body
      */
     post<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "POST", data });
@@ -79,7 +79,7 @@ export class BaseService {
     /**
      * 快捷发送 PUT 请求。
      * @param url 请求相对路径
-     * @param data 请求携带的 body
+     * @param data 请求携带 the body
      */
     put<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "PUT", data });
@@ -130,4 +130,3 @@ export function PluginService(target: any) {
         configurable: true
     });
 }
-

package/src/{composables → utils}/request/types.ts

@@ -90,4 +90,3 @@ export interface UploadResult {
     /** 上传成功后云端资源的可访问 URL 或文件路径 */
     data: string;
 }
-

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

@@ -1,42 +0,0 @@
-/**
- * 小程序广告工具。
- * 提供插屏广告 (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>;
-    setAdReward: (adId: string, done?: AdDone) => Promise<AdRes>;
-    showAdReward: () => Promise<AdRes>;
-};
-export {};

package/dist/composables/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * Composables 统一导出
- */
-export * from './request';
-export { useMsg, type HlwMsg, type ToastOptions, type ModalOptions, type ToastIcon } from './msg';
-export { useDevice, clearDeviceCache, type DeviceInfo, type DeviceQueryInfo, } from './device';
-export { useRefs } from './refs';
-export { useShare, type ShareConfig, } from './share';
-export { useHlwAd, type AdRes } from './ad';
-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';