@hlw-uni/mp-vue 1.2.26 → 2.0.0

package/src/composables/ad/index.ts

@@ -0,0 +1,386 @@
+/**
+ * useAd —— 完整的广告业务封装
+ *
+ * 内置了：
+ *   - 6 个 unit_id 配置（store 缓存，调 getConfig 拉一次）
+ *   - 激励视频：广告加载 loading → onShown 自动关闭 → 中途关闭挽留 modal → 看完调业务方的 claim 发奖
+ *   - 插屏：一行调用
+ *   - 底层 SDK 适配（onLoad / offClose / show 兜底 / 实例缓存）
+ *
+ * 业务侧使用方式：
+ *
+ *   1. 在 App.vue 注入「全局」回调（拿配置 + 校验登录）：
+ *
+ *      import { configAd } from "@hlw-uni/mp-vue";
+ *      import { getAdConfig } from "@/api/ad";
+ *      import { useUserStore } from "@/store";
+ *
+ *      configAd({
+ *          getConfig: async () => {
+ *              const res = await getAdConfig();
+ *              return res.code === 1 && res.data ? res.data : null;
+ *          },
+ *          isAuth: () => !!useUserStore().token,
+ *      });
+ *
+ *   2. 任意页面拉配置 / 用 unit_id 渲染：
+ *
+ *      const { config, loadConfig, showPopup } = useAd();
+ *      await loadConfig();
+ *      <hlw-ad type="banner" :unit-id="config.banner" />
+ *
+ *   3. 看广告领奖励（业务方按场景传不同的 claim 接口）：
+ *
+ *      const ok = await showReward(async () => {
+ *          const res = await claimAdReward();
+ *          return res.code === 1
+ *              ? { ok: true, reward: res.data?.reward }
+ *              : { ok: false, msg: res.info };
+ *      });
+ *
+ *      // 不传 claim 就是纯展示，看完即返回 true
+ *      const ok = await showReward();
+ */
+
+import { defineStore, storeToRefs } from "pinia";
+import { ref } from "vue";
+import { useMsg, type HlwMsg } from "../msg";
+
+/** 6 种广告类型 */
+export type AdType = "banner" | "grid" | "custom" | "video" | "reward" | "popup";
+
+/** 广告配置 —— 字段名跟后端表列名对齐（plugin_qz_mp.{type}_unit_id） */
+export interface AdConfig {
+    banner_unit_id: string;
+    grid_unit_id: string;
+    custom_unit_id: string;
+    video_unit_id: string;
+    reward_unit_id: string;
+    popup_unit_id: string;
+}
+
+/** 广告错误对象（onError 回调参数） */
+export interface AdError {
+    errCode: number;
+    errMsg: string;
+}
+
+/** 业务回调注入接口 —— configAd 时由项目提供 */
+export interface AdAdapter {
+    /** 拉取广告配置；返回 null 表示拉失败，store 不更新 */
+    getConfig: () => Promise<AdConfig | null>;
+    /** 是否已登录；不传 = 不校验（showReward 调用前会问一次） */
+    isAuth?: () => boolean;
+}
+
+/** 激励视频关闭回调返回 */
+export interface AdCloseResult {
+    /** 用户是否完整观看 */
+    isEnded: boolean;
+}
+
+/** showReward 的 claim 回调返回契约 */
+export interface AdClaimResult {
+    /** 本次结果：true=成功 / false=失败 */
+    ok: boolean;
+    /** 奖励数（用于 toast 显示 +N 积分；无则不 toast） */
+    reward?: number;
+    /** 失败提示语；不传不弹 toast */
+    msg?: string;
+    /** 仅 isEnded=false 时常用：true 让 mp-core 重新 show 一次（业务方挽留确认后用） */
+    retry?: boolean;
+}
+
+/**
+ * showReward 的 claim 回调签名 —— 业务方按场景实现（领积分、解锁、抽奖等）。
+ * 每次广告关闭后被调用一次（无论是否完整看完），业务方根据 closeRes.isEnded 决定怎么走：
+ *   - isEnded=true  → 调发奖接口 → return { ok: true, reward: N }
+ *   - isEnded=false → 业务自己决定挽留：return { ok: false, retry: true } 让重新 show
+ */
+export type AdClaimFn = (closeRes: AdCloseResult) => Promise<AdClaimResult>;
+
+const EMPTY: AdConfig = {
+    banner_unit_id: "",
+    grid_unit_id: "",
+    custom_unit_id: "",
+    video_unit_id: "",
+    reward_unit_id: "",
+    popup_unit_id: "",
+};
+
+let adapter: AdAdapter | null = null;
+
+/**
+ * 注入业务回调，应用启动时调用一次。
+ * 不调用也不会崩，但 loadConfig / showReward 会无效。
+ */
+export function configAd(a: AdAdapter): void {
+    adapter = a;
+}
+
+const useAdStore = defineStore("hlw_ad", () => {
+    const config = ref<AdConfig>({ ...EMPTY });
+    const loaded = ref(false);
+    return { config, loaded };
+});
+
+/* ============================================================
+ * 内部状态：消息单例 + 广告实例缓存
+ * ============================================================ */
+
+let _msg: HlwMsg | null = null;
+const msg = (): HlwMsg => (_msg ??= useMsg());
+
+interface RewardedEntry {
+    ad: any;
+    /** 同一 unit_id 是否在 load 中，避免并发 */
+    loading: boolean;
+}
+const rewardedCache = new Map<string, RewardedEntry>();
+const interstitialCache = new Map<string, any>();
+
+/* ============================================================
+ * 公共 composable
+ * ============================================================ */
+
+export function useAd() {
+    const store = useAdStore();
+    const { config, loaded } = storeToRefs(store);
+
+    /** 拉取广告配置（小程序冷启动后调一次即可） */
+    async function loadConfig(force = false): Promise<void> {
+        if (loaded.value && !force) return;
+        if (!adapter?.getConfig) {
+            console.warn("[useAd] adapter.getConfig 未注入；先调用 configAd()");
+            return;
+        }
+        try {
+            const cfg = await adapter.getConfig();
+            if (cfg) {
+                store.config = cfg;
+                store.loaded = true;
+            }
+        } catch (e) {
+            console.warn("[useAd] load config failed", e);
+        }
+    }
+
+    /** 取指定类型的 unit_id（hlw-ad 组件 / 业务直接调时用） */
+    function getUnitId(type: AdType): string {
+        return store.config[`${type}_unit_id` as keyof AdConfig] || "";
+    }
+
+    /**
+     * 显示激励视频
+     *
+     * 流程：loading → 广告 UI → 关闭 → 业务 claim 回调（按 closeRes.isEnded 决定怎么走）
+     *
+     * @param claim 关闭后业务回调；不传则纯展示，看完即返回 true、未看完返回 false
+     * @returns true=最终成功；false=未看完且业务放弃 / 配置缺失 / claim 失败
+     */
+    async function showReward(claim?: AdClaimFn): Promise<boolean> {
+        const unitId = getUnitId("reward");
+        if (!unitId) {
+            msg().toast("激励广告未配置");
+            return false;
+        }
+        if (adapter?.isAuth && !adapter.isAuth()) {
+            msg().toast("请先登录");
+            return false;
+        }
+
+        while (true) {
+            const closeRes = await playRewardedOnce(unitId);
+
+            // 没传 claim：默认行为 = 看完了 true / 没看完弹挽留 + 重试 / 放弃 false
+            if (!claim) {
+                if (closeRes.isEnded) return true;
+                const goon = await confirmReward();
+                if (!goon) return false;
+                continue;
+            }
+
+            // 业务方决定怎么走（包括「未看完是否挽留」）
+            try {
+                const r = await claim(closeRes);
+                if (r.retry) continue;
+                if (!r.ok) {
+                    if (r.msg) msg().error(r.msg);
+                    return false;
+                }
+                if (r.reward && r.reward > 0) msg().success(`+${r.reward} 积分`);
+                return true;
+            } catch (e) {
+                console.warn("[useAd] claim failed", e);
+                msg().error("领取失败，请稍后再试");
+                return false;
+            }
+        }
+    }
+
+    /**
+     * 显示插屏广告
+     * @returns true=展示成功；false=配置缺失 / show 失败（如近期已展示过）
+     */
+    async function showPopup(): Promise<boolean> {
+        const unitId = getUnitId("popup");
+        if (!unitId) return false;
+        return await showInterstitialAd(unitId);
+    }
+
+    return {
+        // 状态
+        config,
+        loaded,
+        // 方法
+        loadConfig,
+        getUnitId,
+        showReward,
+        showPopup,
+    };
+}
+
+/* ============================================================
+ * 内部 helper：业务流程层
+ * ============================================================ */
+
+/** 播放一次激励视频，期间显示加载提示，广告 UI 弹出后自动 hide */
+async function playRewardedOnce(unitId: string): Promise<AdCloseResult> {
+    msg().showLoading("广告加载中");
+    let hidden = false;
+    const hide = () => {
+        if (hidden) return;
+        hidden = true;
+        msg().hideLoading();
+    };
+    try {
+        const isEnded = await showRewardedAd(unitId, { onShown: hide });
+        return { isEnded };
+    } finally {
+        // 兜底：如果 onShown 没触发（show 直接 reject 等），最终也得关 loading
+        hide();
+    }
+}
+
+/**
+ * 激励视频中途关闭挽留弹窗 —— 业务方在 claim 回调里也可以复用：
+ *
+ *   showReward(async (closeRes) => {
+ *       if (!closeRes.isEnded) {
+ *           const goon = await confirmReward();
+ *           return { ok: false, retry: goon };
+ *       }
+ *       const r = await claimAdReward();
+ *       return r.code === 1 ? { ok: true, reward: r.data?.reward } : { ok: false, msg: r.info };
+ *   });
+ *
+ * @returns true=用户选「继续观看」 / false=放弃
+ */
+export function confirmReward(): Promise<boolean> {
+    return new Promise((resolve) => {
+        uni.showModal({
+            title: "提示",
+            content: "看完广告才可以领取奖励哦，要继续观看吗？",
+            confirmText: "继续观看",
+            cancelText: "放弃",
+            success: (r) => resolve(!!r.confirm),
+            fail: () => resolve(false),
+        });
+    });
+}
+
+/* ============================================================
+ * 内部 helper：底层 SDK 适配
+ * ============================================================ */
+
+/**
+ * 底层激励视频包装：onClose / onError 解绑 + load + show 兜底
+ *
+ * @param hooks.onShown 广告 UI 已渲染时回调（业务用来关 loading）
+ */
+function showRewardedAd(unitId: string, hooks?: { onShown?: () => void }): Promise<boolean> {
+    return new Promise((resolve) => {
+        let entry = rewardedCache.get(unitId);
+        if (!entry) {
+            const ad: any = uni.createRewardedVideoAd({ adUnitId: unitId });
+            if (!ad) { resolve(false); return; }
+            ad.onError?.((err: AdError) => {
+                console.warn(`[useAd] reward onError (${unitId})`, err);
+            });
+            entry = { ad, loading: false };
+            rewardedCache.set(unitId, entry);
+        }
+        const { ad } = entry;
+
+        let closeHandler: ((res: { isEnded: boolean }) => void) | null = null;
+        let errorHandler: ((err: AdError) => void) | null = null;
+        const cleanup = () => {
+            if (closeHandler) { ad.offClose?.(closeHandler); closeHandler = null; }
+            if (errorHandler) { ad.offError?.(errorHandler); errorHandler = null; }
+        };
+        closeHandler = (res) => {
+            cleanup();
+            resolve(!!(res && res.isEnded));
+        };
+        errorHandler = (err) => {
+            console.warn(`[useAd] reward show error (${unitId})`, err);
+            cleanup();
+            resolve(false);
+        };
+        ad.onClose(closeHandler);
+        ad.onError(errorHandler);
+
+        const doShow = () =>
+            ad.show()
+                .then(() => {
+                    try { hooks?.onShown?.(); } catch (e) { console.warn("[useAd] onShown error", e); }
+                })
+                .catch(() => {
+                    cleanup();
+                    resolve(false);
+                });
+
+        if (entry.loading) {
+            Promise.resolve().then(doShow);
+        } else {
+            entry.loading = true;
+            ad.load()
+                .then(doShow)
+                .catch(doShow)
+                .finally(() => { if (entry) entry.loading = false; });
+        }
+    });
+}
+
+/** 底层插屏广告包装：show 失败兜底 load → 再 show */
+function showInterstitialAd(unitId: string): Promise<boolean> {
+    return new Promise((resolve) => {
+        let ad: any = interstitialCache.get(unitId);
+        if (!ad) {
+            ad = uni.createInterstitialAd({ adUnitId: unitId });
+            if (!ad) { resolve(false); return; }
+            ad.onError?.((err: AdError) => {
+                console.warn(`[useAd] popup onError (${unitId})`, err);
+            });
+            interstitialCache.set(unitId, ad);
+        }
+
+        ad.show()
+            .then(() => resolve(true))
+            .catch(() => {
+                if (typeof ad.load !== "function") { resolve(false); return; }
+                ad.load()
+                    .then(() => ad.show())
+                    .then(() => resolve(true))
+                    .catch(() => resolve(false));
+            });
+    });
+}
+
+/** 销毁全部广告实例并清空缓存（业务一般不用，hot reload 时调） */
+export function destroyAds(): void {
+    rewardedCache.forEach((e) => e.ad?.destroy?.());
+    rewardedCache.clear();
+    interstitialCache.forEach((ad) => ad?.destroy?.());
+    interstitialCache.clear();
+}

package/src/composables/color/index.ts

@@ -0,0 +1,44 @@
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+/**
+ * 解析 6 位十六进制颜色值，返回 RGB 数组。
+ */
+function parseHex(hex: string): [number, number, number] {
+    if (!HEX_RE.test(hex)) throw new Error(`Invalid hex color: ${hex}`);
+    return [
+        parseInt(hex.slice(1, 3), 16),
+        parseInt(hex.slice(3, 5), 16),
+        parseInt(hex.slice(5, 7), 16),
+    ];
+}
+
+/**
+ * 颜色处理工具。
+ */
+export function useColor() {
+    /**
+     * 将 CSS 变量对象拼接成内联 style 字符串。
+     */
+    function varsToStyle(vars: Record<string, string>): string {
+        return Object.entries(vars).map(([k, v]) => `${k}:${v}`).join(";") + ";";
+    }
+
+    /**
+     * 将十六进制颜色转为 rgba 字符串。
+     */
+    function hexToRgba(hex: string, alpha: number): string {
+        const [r, g, b] = parseHex(hex);
+        return `rgba(${r},${g},${b},${alpha})`;
+    }
+
+    /**
+     * 将十六进制颜色按比例压暗。
+     */
+    function darkenHex(hex: string, amount = 0.15): string {
+        const [r, g, b] = parseHex(hex);
+        const d = (c: number) => Math.max(0, Math.round(c * (1 - amount)));
+        return `#${d(r).toString(16).padStart(2, "0")}${d(g).toString(16).padStart(2, "0")}${d(b).toString(16).padStart(2, "0")}`;
+    }
+
+    return { varsToStyle, hexToRgba, darkenHex };
+}

package/src/composables/contact/index.ts

@@ -0,0 +1,88 @@
+/**
+ * useContact —— 客服按钮配置（business-level cache）
+ *
+ * 后端返回 <button open-type="contact"> 的 4 个微信原生属性，模块级缓存共享给所有客服按钮。
+ *
+ * 使用方式（业务侧）：
+ *
+ *   1. App.vue / bootstrap 注入回调：
+ *
+ *      configContact({
+ *          getConfig: async () => {
+ *              const res = await getContactConfig();
+ *              return res.code === 1 ? res.data : null;
+ *          },
+ *      });
+ *
+ *   2. 任意按钮组件：
+ *
+ *      const contact = useContact();
+ *      <hlw-button open-type="contact" v-bind="contact">联系客服</hlw-button>
+ */
+import { computed, ref } from "vue";
+
+/** 后端返回的客服配置（按 button open-type=contact 标准属性命名） */
+export interface ContactConfig {
+    send_message_title: string;
+    send_message_path: string;
+    send_message_img: string;
+    show_message_card: boolean;
+}
+
+/** Adapter 注入接口 */
+export interface ContactAdapter {
+    /** 拉取客服配置；返回 null 表示拉失败，store 不更新 */
+    getConfig: () => Promise<ContactConfig | null>;
+}
+
+/** v-bind 到 button 的 camelCase props（微信原生属性约定） */
+export interface ContactBindProps {
+    sendMessageTitle: string;
+    sendMessagePath: string;
+    sendMessageImg: string;
+    showMessageCard: boolean;
+}
+
+let adapter: ContactAdapter | null = null;
+const config = ref<ContactConfig | null>(null);
+let pending: Promise<void> | null = null;
+
+/**
+ * 注入业务回调（应用启动时调用一次；不调用则 useContact 始终返回空字段）。
+ */
+export function configContact(a: ContactAdapter): void {
+    adapter = a;
+}
+
+function loadConfig(): Promise<void> {
+    if (config.value) return Promise.resolve();
+    if (pending) return pending;
+    if (!adapter?.getConfig) {
+        console.warn("[useContact] adapter.getConfig 未注入；先调用 configContact()");
+        return Promise.resolve();
+    }
+    pending = adapter.getConfig()
+        .then((cfg) => {
+            if (cfg) config.value = cfg;
+        })
+        .catch((e) => {
+            console.warn("[useContact] load config failed", e);
+        })
+        .finally(() => {
+            pending = null;
+        });
+    return pending;
+}
+
+/**
+ * 返回 v-bind 友好的客服配置 computed（首次调用会异步拉一次配置）。
+ */
+export function useContact() {
+    void loadConfig();
+    return computed<ContactBindProps>(() => ({
+        sendMessageTitle: config.value?.send_message_title || "",
+        sendMessagePath:  config.value?.send_message_path  || "",
+        sendMessageImg:   config.value?.send_message_img   || "",
+        showMessageCard:  config.value?.show_message_card  ?? false,
+    }));
+}

package/src/composables/device/index.ts

@@ -0,0 +1,168 @@
+/**
+ * useDevice — 设备信息 composable（单例缓存）
+ * 使用微信 3.7.0+ 推荐的新 API 替代废弃的 getSystemInfoSync
+ */
+import { ref } from "vue";
+
+export interface DeviceInfo {
+    /** 小程序 appId */
+    appid: string;
+    /** 应用名称 */
+    app_name: string;
+    /** 小程序版本号（版本名称） */
+    app_version: string;
+    /** 小程序版本号（版本号） */
+    app_version_code: string;
+    /** 小程序来源渠道 */
+    app_channel: string;
+    /** 设备品牌。如：apple、huawei */
+    device_brand: string;
+    /** 设备型号 */
+    device_model: string;
+    /** 设备 ID */
+    device_id: string;
+    /** 设备类型：phone/pad/pc */
+    device_type: string;
+    /** 设备方向：portrait/landscape */
+    device_orientation: "portrait" | "landscape";
+    /** 手机品牌。H5 不支持 */
+    brand: string;
+    /** 手机型号 */
+    model: string;
+    /** 操作系统版本 */
+    system: string;
+    /** 操作系统版本（简写） */
+    os: string;
+    /** 设备像素比 */
+    pixel_ratio: number;
+    /** 屏幕宽度 (px) */
+    screen_width: number;
+    /** 屏幕高度 (px) */
+    screen_height: number;
+    /** 可用窗口宽度 (px) */
+    window_width: number;
+    /** 可用窗口高度 (px) */
+    window_height: number;
+    /** 状态栏高度 (px) */
+    status_bar_height: number;
+    /** 微信基础库版本 */
+    sdk_version: string;
+    /** 宿主名称。如：WeChat、alipay */
+    host_name: string;
+    /** 宿主版本。如：微信版本号 */
+    host_version: string;
+    /** 宿主语言 */
+    host_language: string;
+    /** 宿主主题：light/dark */
+    host_theme: string;
+    /** 平台类型 weapp/toutiao/h5 */
+    platform: string;
+    /** 客户端语言 */
+    language: string;
+    /** 客户端版本号 */
+    version: string;
+}
+
+const _info = ref<DeviceInfo | null>(null);
+
+/**
+ * 安全调用 uni API，失败时返回空对象，避免平台差异导致中断。
+ */
+function tryCall(fn: (() => unknown) | undefined): Record<string, unknown> {
+    try { return (fn?.() ?? {}) as Record<string, unknown>; } catch { return {}; }
+}
+
+/**
+ * 收集当前设备、窗口与宿主应用信息并归一化字段。
+ */
+function collect(): DeviceInfo {
+    // @ts-ignore — 新 API 在旧版 @dcloudio/types 中可能未声明
+    let deviceInfo = tryCall(uni.getDeviceInfo);
+    // @ts-ignore
+    let windowInfo = tryCall(uni.getWindowInfo);
+    let appBaseInfo = tryCall(uni.getAppBaseInfo);
+
+    if (!deviceInfo.brand && !deviceInfo.model) {
+        const sys = tryCall(() => uni.getSystemInfoSync());
+        deviceInfo = { ...sys };
+        windowInfo = { ...sys };
+        appBaseInfo = { ...sys };
+    }
+
+    let appid = "";
+    try {
+        const accountInfo = uni.getAccountInfoSync() as { miniProgram?: { appId?: string } };
+        appid = accountInfo?.miniProgram?.appId || "";
+    } catch {
+        appid = (deviceInfo.appId as string) || "";
+    }
+
+    const system = (deviceInfo.system as string) || "";
+
+    return {
+        appid,
+        app_name: (appBaseInfo.appName as string) || "",
+        app_version: (appBaseInfo.appVersion as string) || "",
+        app_version_code: (appBaseInfo.appVersionCode as string) || "",
+        app_channel: (appBaseInfo.appChannel as string) || "",
+        device_brand: (deviceInfo.brand as string) || "",
+        device_model: (deviceInfo.model as string) || "",
+        device_id: (deviceInfo.deviceId as string) || "",
+        device_type: (deviceInfo.deviceType as string) || "",
+        device_orientation: (windowInfo.deviceOrientation as "portrait" | "landscape") || "portrait",
+        brand: (deviceInfo.brand as string) || "",
+        model: (deviceInfo.model as string) || "",
+        system,
+        os: system.split(" ")[0] || "",
+        pixel_ratio: (windowInfo.pixelRatio as number) || 0,
+        screen_width: (windowInfo.screenWidth as number) || 0,
+        screen_height: (windowInfo.screenHeight as number) || 0,
+        window_width: (windowInfo.windowWidth as number) || 0,
+        window_height: (windowInfo.windowHeight as number) || 0,
+        status_bar_height: (windowInfo.statusBarHeight as number) || 0,
+        sdk_version: (appBaseInfo.SDKVersion as string) || "",
+        host_name: (appBaseInfo.hostName as string) || "",
+        host_version: (appBaseInfo.hostVersion as string) || "",
+        host_language: (appBaseInfo.hostLanguage as string) || "",
+        host_theme: (appBaseInfo.hostTheme as string) || "",
+        platform: (deviceInfo.platform as string) || "",
+        language: (appBaseInfo.language as string) || "",
+        version: (appBaseInfo.version as string) || "",
+    };
+}
+
+/**
+ * 确保设备信息只在首次访问时采集一次。
+ */
+function ensure() {
+    if (!_info.value) {
+        _info.value = collect();
+    }
+}
+
+/**
+ * 获取单例缓存的设备信息。
+ */
+export function useDevice() {
+    ensure();
+    return _info;
+}
+
+/**
+ * 把 deviceInfo 对象转成 URL query string（不含前导 ?）
+ */
+export function deviceToQuery(): string {
+    ensure();
+    if (!_info.value) return "";
+    return Object.entries(_info.value)
+        .filter(([, v]) => v !== "" && v !== 0)
+        .map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`)
+        .join("&");
+}
+
+/**
+ * 手动清除缓存（切换账号等场景可能需要）
+ */
+export function clearDeviceCache(): void {
+    _info.value = null;
+}