@hlw-uni/mp-vue 2.1.70 → 2.1.97

package/src/composables/ad/README.md

@@ -1,58 +0,0 @@
-# ad 调用文档
-
-`useHlwAd` 封装微信小程序插屏广告和激励视频广告。仅在存在 `wx` 且对应广告 API 可用时生效。
-
-## 引入
-
-```ts
-import { useHlwAd } from "@hlw-uni/mp-vue";
-```
-
-## 插屏广告
-
-```ts
-const ad = useHlwAd();
-
-ad.setAdPopup("adunit-popup-id", (ok) => {
-    console.log("插屏广告关闭", ok);
-});
-
-await ad.showAdPopup(1000);
-```
-
-## 激励视频
-
-```ts
-const ad = useHlwAd();
-
-ad.setAdReward("adunit-reward-id", (res) => {
-    if (res.ok) {
-        // 用户完整看完激励视频
-    }
-});
-
-const result = await ad.showAdReward();
-
-if (result.ok) {
-    // 发放奖励
-}
-```
-
-## API
-
-| 方法 | 说明 |
-| --- | --- |
-| `setAdPopup(adId, done?)` | 创建插屏广告实例 |
-| `showAdPopup(delay?)` | 延迟展示插屏广告，默认 3000ms |
-| `setAdReward(adId, done?)` | 创建激励视频实例 |
-| `showAdReward()` | 展示激励视频，失败时会尝试 load 后再 show |
-
-## 类型
-
-```ts
-interface AdRes {
-    ok: boolean;
-    isEnded?: boolean;
-    err?: unknown;
-}
-```

package/src/composables/ad/index.ts

@@ -1,227 +0,0 @@
-/**
- * 小程序广告工具。
- * 提供插屏广告 (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;
-
-// 缓存不同 Unit ID 的广告实例
-const popupCache = new Map<string, any>();
-const rewardCache = new Map<string, any>();
-
-let activePopupAdId = "";
-let popupDone: ((ok: boolean) => void) | undefined;
-
-let activeRewardAdId = "";
-let rewardDone: AdDone | undefined;
-let rewardPromise: Promise<AdRes> | null = null;
-let rewardResolve: ((res: AdRes) => void) | null = null;
-
-/**
- * 获取当前环境的小程序全局 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);
-    rewardResolve = null;
-    rewardPromise = 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() {
-    /**
-     * 配置/预加载插屏广告。
-     * 
-     * @param adId 广告单元 ID
-     * @param done 广告关闭后的回调（可选）
-     * @returns 是否配置成功
-     */
-    function setAdPopup(adId: string, done?: (ok: boolean) => void): boolean {
-        popupDone = done;
-        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) => {
-            const ad = popupCache.get(activePopupAdId);
-            if (!ad) {
-                resolve(false);
-                return;
-            }
-
-            const done = popupDone;
-            popupDone = (ok: boolean) => {
-                done?.(ok);
-                resolve(ok);
-            };
-
-            setTimeout(() => {
-                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;
-        });
-
-        if (!adId) {
-            finish({ ok: false });
-            return rewardPromise;
-        }
-
-        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> {
-        const ad = rewardCache.get(activeRewardAdId);
-        if (!ad) {
-            return Promise.resolve({ ok: false });
-        }
-
-        const current = rewardPromise || new Promise<AdRes>((resolve) => {
-            rewardResolve = resolve;
-        });
-        rewardPromise = current;
-
-        ad.show().catch(() => {
-            ad.load()
-                .then(() => ad.show())
-                .catch((err: unknown) => {
-                    console.error("[HlwAd] Rewarded video show error:", err);
-                    finish({ ok: false, err });
-                });
-        });
-
-        return current;
-    }
-
-    return {
-        setAdPopup,
-        showAdPopup,
-        setAdReward,
-        showAdReward,
-    };
-}
-

package/src/composables/device/README.md

@@ -1,50 +0,0 @@
-# device 调用文档
-
-`useDevice` 采集并缓存设备、窗口、宿主和小程序信息，同时提供常用设备字段组成的 query 字符串。
-
-## 引入
-
-```ts
-import { useDevice, clearDeviceCache } from "@hlw-uni/mp-vue";
-```
-
-## 基础用法
-
-```ts
-const { info, query } = useDevice();
-
-console.log(info.appid);
-console.log(info.device_model);
-console.log(query);
-```
-
-`useDevice` 内部会优先读取 `uni.getDeviceInfo`、`uni.getWindowInfo`、`uni.getAppBaseInfo`，旧环境会回退到 `uni.getSystemInfoSync`。
-
-## 清除缓存
-
-```ts
-clearDeviceCache();
-```
-
-切换账号、切换宿主环境或需要重新采集设备信息时可以手动清理缓存。
-
-## 返回值
-
-| 字段 | 说明 |
-| --- | --- |
-| `info` | 完整 `DeviceInfo` |
-| `query` | 常用设备字段组成的 URL query 字符串 |
-
-## 常用字段
-
-| 字段 | 说明 |
-| --- | --- |
-| `appid` | 小程序 appId |
-| `device_brand` | 设备品牌 |
-| `device_model` | 设备型号 |
-| `device_id` | 设备 ID |
-| `platform` | 平台类型 |
-| `system` | 系统版本 |
-| `sdk_version` | 基础库版本 |
-| `screen_width` | 屏幕宽度 |
-| `screen_height` | 屏幕高度 |

package/src/composables/index.ts

@@ -1,38 +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";
-
-

package/src/composables/msg/README.md

@@ -1,79 +0,0 @@
-# msg 调用文档
-
-`useMsg` 统一封装 toast、loading、modal 和简单进度展示。
-
-## 引入
-
-```ts
-import { useMsg } from "@hlw-uni/mp-vue";
-```
-
-## 基础用法
-
-```ts
-const msg = useMsg();
-
-msg.toast("保存中");
-msg.success("保存成功");
-msg.error("保存失败");
-
-msg.showLoading("加载中...");
-msg.hideLoading();
-```
-
-## 确认弹窗
-
-```ts
-const ok = await msg.confirm({
-    title: "删除确认",
-    content: "确定删除这条记录吗？",
-    confirmText: "删除",
-});
-
-if (ok) {
-    // 用户点击确认
-}
-```
-
-`modal` 是 `confirm` 的语义别名。
-
-## API
-
-| 方法 | 说明 |
-| --- | --- |
-| `toast(opts | string)` | 普通提示 |
-| `success(message)` | 成功提示 |
-| `error(message)` | 失败提示 |
-| `fail(message)` | `error` 的别名 |
-| `showLoading(message?)` | 显示全局 loading |
-| `hideLoading()` | 关闭全局 loading |
-| `confirm(opts)` | 确认弹窗，返回 `Promise<boolean>` |
-| `modal(opts)` | `confirm` 的别名 |
-| `setLoadingBar(progress)` | 用导航标题模拟进度 |
-
-## ToastOptions
-
-```ts
-interface ToastOptions {
-    message: string;
-    icon?: "success" | "fail" | "exception" | "none";
-    image?: string;
-    duration?: number;
-    mask?: boolean;
-    position?: "top" | "center" | "bottom";
-}
-```
-
-## ModalOptions
-
-```ts
-interface ModalOptions {
-    title?: string;
-    content: string;
-    confirmText?: string;
-    cancelText?: string;
-    confirmColor?: string;
-    cancelColor?: string;
-    showCancel?: boolean;
-}
-```

package/src/composables/navigator/README.md

@@ -1,71 +0,0 @@
-# navigator 调用文档
-
-`useNavigate` 统一封装 uni-app 页面跳转、tab 跳转、返回和打开其他小程序。
-
-## 引入
-
-```ts
-import { useNavigate } from "@hlw-uni/mp-vue";
-```
-
-## 基础用法
-
-```ts
-const nav = useNavigate();
-
-nav.to("/pages/detail/index?id=1");
-nav.redirect("/pages/login/index");
-nav.tab("/pages/index/index");
-nav.reLaunch("/pages/index/index");
-nav.back();
-```
-
-## 打开其他小程序
-
-```ts
-nav.miniProgram("wx1234567890", {
-    path: "pages/index/index?id=1",
-    envVersion: "release",
-    extraData: {
-        from: "hlw",
-    },
-});
-```
-
-## 通用跳转
-
-```ts
-nav.navigate("navigateTo", "/pages/detail/index?id=1", {
-    silent: true,
-    onFail: (message) => {
-        console.log(message);
-    },
-});
-```
-
-## API
-
-| 方法 | 说明 |
-| --- | --- |
-| `navigate(type, url, options?)` | 通用跳转入口 |
-| `to(url, options?)` | `uni.navigateTo` |
-| `redirect(url, options?)` | `uni.redirectTo` |
-| `tab(url, options?)` | `uni.switchTab` |
-| `reLaunch(url, options?)` | `uni.reLaunch` |
-| `back(delta?, options?)` | `uni.navigateBack` |
-| `miniProgram(appId, options?)` | `uni.navigateToMiniProgram` |
-
-## NavigateOptions
-
-```ts
-interface NavigateOptions {
-    silent?: boolean;
-    onFail?: (message: string) => void;
-    delta?: number;
-    path?: string;
-    envVersion?: "develop" | "trial" | "release";
-    extraData?: Record<string, unknown>;
-}
-```
-
-`webview` 类型当前只提示 `H5：{url}`，具体 web-view 承载页由业务项目实现。

package/src/composables/refs/README.md

@@ -1,40 +0,0 @@
-# refs 调用文档
-
-`useRefs` 用于 `v-for` 场景批量收集组件或元素引用。
-
-## 引入
-
-```ts
-import { useRefs } from "@hlw-uni/mp-vue";
-```
-
-## 基础用法
-
-```vue
-<template>
-    <hlw-popup
-        v-for="item in list"
-        :key="item.id"
-        :ref="setRefs(item.id)"
-    />
-</template>
-
-<script setup lang="ts">
-import { useRefs } from "@hlw-uni/mp-vue";
-
-const { refs, setRefs } = useRefs();
-
-function open(id: string) {
-    refs.value[id]?.open?.();
-}
-</script>
-```
-
-## 返回值
-
-| 字段 | 说明 |
-| --- | --- |
-| `refs` | `Record<string, any>` 的响应式引用集合 |
-| `setRefs(key)` | 返回可绑定到模板 `ref` 的回调函数 |
-
-组件更新前和卸载时，内部会自动清空引用集合，避免旧引用残留。

package/src/composables/request/README.md

@@ -1,124 +0,0 @@
-# request 调用文档
-
-`request` 模块封装 `uni.request`、请求拦截器、响应拦截器、错误拦截器、上传和服务类组织方式。
-
-## 引入
-
-```ts
-import {
-    useRequest,
-    useUpload,
-    BaseService,
-    ServiceNamespace,
-    ServicePrefix,
-} from "@hlw-uni/mp-vue";
-```
-
-## useRequest
-
-```ts
-const request = useRequest();
-
-request.setBaseURL("https://api.example.com");
-
-const offRequest = request.onRequest((config) => {
-    config.headers = {
-        ...config.headers,
-        "x-token": uni.getStorageSync("token"),
-    };
-    return config;
-});
-
-const res = await request.get<{ name: string }>("/user/profile");
-
-offRequest();
-```
-
-## API
-
-| 方法 | 说明 |
-| --- | --- |
-| `request(config)` | 发起完整配置请求 |
-| `get(url, data?)` | GET 请求 |
-| `post(url, data?)` | POST 请求 |
-| `put(url, data?)` | PUT 请求 |
-| `del(url, data?)` | DELETE 请求 |
-| `setBaseURL(url)` | 设置全局基础地址 |
-| `onRequest(fn)` | 注册请求拦截器，返回取消函数 |
-| `onResponse(fn)` | 注册响应拦截器，返回取消函数 |
-| `onError(fn)` | 注册错误拦截器，返回取消函数 |
-| `upload(config)` | 上传文件 |
-| `resolveServiceUrl(namespace, url, servicePrefix?)` | 生成服务类请求地址 |
-
-## 响应格式
-
-```ts
-interface ApiResponse<T = unknown> {
-    code: number;
-    data: T;
-    info: string;
-}
-```
-
-## useUpload
-
-```ts
-const { uploading, upload } = useUpload();
-
-const result = await upload({
-    type: "local",
-    server: "https://api.example.com/upload",
-    url: "https://api.example.com/upload",
-    filePath: tempFilePath,
-    header: {
-        "x-token": uni.getStorageSync("token"),
-    },
-});
-
-console.log(uploading.value, result.data);
-```
-
-上传类型：
-
-| 类型 | 说明 |
-| --- | --- |
-| `local` | 直接上传到业务接口 |
-| `cos` | 腾讯云 COS 表单上传 |
-| `oss` | 阿里云 OSS 表单上传 |
-| `qiniu` | 七牛云表单上传 |
-| `alist` | Alist 上传 |
-
-## BaseService
-
-```ts
-@ServicePrefix("api")
-@ServiceNamespace("user")
-class UserService extends BaseService {
-    profile() {
-        return this.get<{ nickname: string }>("/profile");
-    }
-
-    update(data: { nickname: string }) {
-        return this.post("/update", data);
-    }
-}
-
-const userService = new UserService();
-const profile = await userService.profile();
-```
-
-上面的 `profile()` 会请求 `/api/user/profile`。如果传入绝对地址，例如 `https://example.com/a`，则不会拼接前缀。
-
-## UploadConfig
-
-```ts
-interface UploadConfig {
-    server: string;
-    filePath: string;
-    fileName?: string;
-    type: string;
-    credentials?: Record<string, string>;
-    header?: Record<string, string>;
-    url?: string;
-}
-```