@hlw-uni/mp-vue 2.1.52 → 2.1.55

package/src/composables/device/index.ts

@@ -1,8 +1,7 @@
 /**
- * useDevice — 设备信息 composable（单例缓存）
- * 使用微信 3.7.0+ 推荐的新 API 替代废弃的 getSystemInfoSync
+ * useDevice - 设备信息与接口 query
  */
-import { ref } from "vue";
+import { useUtils } from "../utils";
 
 export interface DeviceInfo {
     /** 小程序 appId */
@@ -63,106 +62,134 @@ export interface DeviceInfo {
     version: string;
 }
 
-const _info = ref<DeviceInfo | null>(null);
+export type DeviceQueryInfo = Pick<DeviceInfo,
+    | "appid"
+    | "device_brand"
+    | "device_model"
+    | "device_id"
+    | "device_type"
+    | "device_orientation"
+    | "platform"
+    | "system"
+    | "os"
+    | "version"
+    | "sdk_version"
+    | "host_name"
+    | "host_version"
+    | "host_language"
+    | "language"
+    | "app_version"
+    | "app_version_code"
+    | "screen_width"
+    | "screen_height"
+>;
 
-/**
- * 安全调用 uni API，失败时返回空对象，避免平台差异导致中断。
- */
-function tryCall(fn: (() => unknown) | undefined): Record<string, unknown> {
-    try { return (fn?.() ?? {}) as Record<string, unknown>; } catch { return {}; }
+let deviceCache: DeviceInfo | null = null;
+
+function readSafe(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);
+function collectDevice(): DeviceInfo {
+    // @ts-ignore - 新 API 在旧版 @dcloudio/types 中可能未声明。
+    let device = readSafe(uni.getDeviceInfo);
     // @ts-ignore
-    let windowInfo = tryCall(uni.getWindowInfo);
-    let appBaseInfo = tryCall(uni.getAppBaseInfo);
+    let window = readSafe(uni.getWindowInfo);
+    let app = readSafe(uni.getAppBaseInfo);
 
-    if (!deviceInfo.brand && !deviceInfo.model) {
-        const sys = tryCall(() => uni.getSystemInfoSync());
-        deviceInfo = { ...sys };
-        windowInfo = { ...sys };
-        appBaseInfo = { ...sys };
+    if (!device.brand && !device.model) {
+        const system = readSafe(() => uni.getSystemInfoSync());
+        device = { ...system };
+        window = { ...system };
+        app = { ...system };
     }
 
-    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) || "";
+    const system = (device.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) || "",
+        appid: getAppid(device),
+        app_name: (app.appName as string) || "",
+        app_version: (app.appVersion as string) || "",
+        app_version_code: (app.appVersionCode as string) || "",
+        app_channel: (app.appChannel as string) || "",
+        device_brand: (device.brand as string) || "",
+        device_model: (device.model as string) || "",
+        device_id: (device.deviceId as string) || "",
+        device_type: (device.deviceType as string) || "",
+        device_orientation: (window.deviceOrientation as "portrait" | "landscape") || "portrait",
+        brand: (device.brand as string) || "",
+        model: (device.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) || "",
+        pixel_ratio: (window.pixelRatio as number) || 0,
+        screen_width: (window.screenWidth as number) || 0,
+        screen_height: (window.screenHeight as number) || 0,
+        window_width: (window.windowWidth as number) || 0,
+        window_height: (window.windowHeight as number) || 0,
+        status_bar_height: (window.statusBarHeight as number) || 0,
+        sdk_version: (app.SDKVersion as string) || "",
+        host_name: (app.hostName as string) || "",
+        host_version: (app.hostVersion as string) || "",
+        host_language: (app.hostLanguage as string) || "",
+        host_theme: (app.hostTheme as string) || "",
+        platform: (device.platform as string) || "",
+        language: (app.language as string) || "",
+        version: (app.version as string) || "",
     };
 }
 
-/**
- * 确保设备信息只在首次访问时采集一次。
- */
-function ensure() {
-    if (!_info.value) {
-        _info.value = collect();
+function getAppid(device: Record<string, unknown>) {
+    try {
+        const account = uni.getAccountInfoSync() as { miniProgram?: { appId?: string } };
+        return account?.miniProgram?.appId || "";
+    } catch {
+        return (device.appId as string) || "";
     }
 }
 
-/**
- * 获取单例缓存的设备信息。
- */
-export function useDevice() {
-    ensure();
-    return _info;
+function getDevice() {
+    deviceCache ??= collectDevice();
+    return deviceCache;
 }
 
-/**
- * 把 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("&");
+function getQueryInfo(info: DeviceInfo): DeviceQueryInfo {
+    return {
+        appid: info.appid,
+        device_brand: info.device_brand,
+        device_model: info.device_model,
+        device_id: info.device_id,
+        device_type: info.device_type,
+        device_orientation: info.device_orientation,
+        platform: info.platform,
+        system: info.system,
+        os: info.os,
+        version: info.version,
+        sdk_version: info.sdk_version,
+        host_name: info.host_name,
+        host_version: info.host_version,
+        host_language: info.host_language,
+        language: info.language,
+        app_version: info.app_version,
+        app_version_code: info.app_version_code,
+        screen_width: info.screen_width,
+        screen_height: info.screen_height,
+    };
+}
+
+export function useDevice() {
+    const info = getDevice();
+    const { toQuery } = useUtils();
+
+    return {
+        info,
+        query: toQuery(getQueryInfo(info)),
+    };
 }
 
-/**
- * 手动清除缓存（切换账号等场景可能需要）
- */
 export function clearDeviceCache(): void {
-    _info.value = null;
+    deviceCache = null;
 }

package/src/composables/index.ts

@@ -1,51 +1,22 @@
 /**
  * Composables 统一导出
  */
-export * from "./http";
-export { useLoading } from "./loading";
+export * from "./request";
 export { useMsg, type HlwMsg, type ToastOptions, type ModalOptions, type ToastIcon } from "./msg";
-export { useDevice, deviceToQuery, clearDeviceCache, type DeviceInfo } from "./device";
-export { useRefs } from "./refs";
-export { usePageMeta } from "./page-meta";
-export { useStorage, type StorageInstance } from "./storage";
-export { useValidate } from "./validate";
-export { useFormat } from "./format";
 export {
-    useAd,
-    setConfigAd,
-    destroyAds,
-    type AdType,
-    type AdConfig,
-    type AdError,
-    type AdAdapter,
-    type AdCloseResult,
-} from "./ad";
+    useDevice,
+    clearDeviceCache,
+    type DeviceInfo,
+    type DeviceQueryInfo,
+} from "./device";
+export { useRefs } from "./refs";
 export {
     useShare,
-    useShareConfig,
-    setConfigShare,
     type ShareConfig,
-    type ShareConfigResolver,
-    type ShareFrom,
-    type ShareAppMessageContent,
-    type ShareTimelineContent,
-    type ShareConfigMap,
-    type ShareConfigAdapter,
-    type PageShareItem,
-    type PageShareFallback,
-    type SharePayload,
 } from "./share";
-export {
-    useContact,
-    setConfigContact,
-    type ContactConfig,
-    type ContactAdapter,
-    type ContactBindProps,
-} from "./contact";
-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 { useHlwAd, type AdRes } from "./ad";
+export { useUtils, type DownloadOpt, type DownloadRes } from "./utils";
+export { useNavigate, type NavigateType, type NavigateOptions } from "./navigator";
 
 // Theme（mp-vue 自带）
 export type { FontScale, FontPreset } from "./theme";

package/src/composables/msg/README.md

@@ -0,0 +1,79 @@
+# 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

@@ -0,0 +1,71 @@
+# 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/navigator/index.ts

@@ -1,104 +1,104 @@
 /**
- * 路由/跳转能力 —— 包装 uni-app 各类 jump API 为一个统一对象
- *
- * 使用：
- *   const { navigate } = useRouter();
- *   navigate(tool.jump_type, tool.jump_value);
- *
- * 未装 vue-router 也能用；命名风格对齐 Vue Router，熟悉的 push/replace/back
- * 会在后续迭代中补齐。
+ * useNavigate - uni-app 跳转工具
  */
-
-/** 已知的跳转类型；保留 `(string & {})` 允许任意自定义值向下兼容 */
 export type NavigateType =
     | "navigateTo"
     | "redirectTo"
     | "switchTab"
     | "reLaunch"
-    | "webview"
+    | "navigateBack"
     | "miniprogram"
+    | "webview"
     | (string & {});
 
 export interface NavigateOptions {
-    /** 失败回调，收到 uni 返回的错误信息 */
-    onFail?: (errMsg: string) => void;
-    /** 是否禁用默认的 Toast 错误提示，默认 false */
     silent?: boolean;
-    /** 仅 miniprogram：目标小程序的页面路径（如 pages/index/index?id=1），留空/null 则打开首页 */
-    path?: string | null;
-    /** 仅 miniprogram：目标小程序版本，默认 release */
+    onFail?: (message: string) => void;
+    delta?: number;
+    path?: string;
     envVersion?: "develop" | "trial" | "release";
-    /** 仅 miniprogram：传给目标小程序的额外数据，对方从 onLaunch/onShow 读取 */
-    extraData?: Record<string, unknown> | null;
+    extraData?: Record<string, unknown>;
 }
 
-/**
- * 根据 type + value 调用对应的 uni API，屏蔽参数差异。
- *
- * 对应关系：
- * - `navigateTo`（默认） → uni.navigateTo
- * - `redirectTo`          → uni.redirectTo
- * - `switchTab`           → uni.switchTab（value 必须是 tabBar 页）
- * - `reLaunch`            → uni.reLaunch
- * - `webview`             → 默认 Toast 提示，上层需接入 web-view 承载页
- * - `miniprogram`         → uni.navigateToMiniProgram，value 格式 `appid:path`
- */
-function doNavigate(type: NavigateType, value: string, options: NavigateOptions = {}): void {
-    const { onFail, silent = false } = options;
+type UniFail = { errMsg?: string };
 
-    if (!value) {
-        if (!silent) uni.showToast({ title: "跳转目标未配置", icon: "none" });
-        onFail?.("跳转目标未配置");
-        return;
+function fail(message: string, options: NavigateOptions = {}) {
+    if (!options.silent) {
+        uni.showToast({ title: message, icon: "none" });
     }
+    options.onFail?.(message);
+}
 
-    const fail = (err?: { errMsg?: string }) => {
-        const msg = err?.errMsg || `无法跳转：${value}`;
-        if (!silent) uni.showToast({ title: msg, icon: "none" });
-        onFail?.(msg);
+function failHandler(target: string, options: NavigateOptions = {}) {
+    return (error?: UniFail) => {
+        fail(error?.errMsg || `无法跳转：${target}`, options);
     };
+}
 
-    switch (type) {
-        case "switchTab":
-            uni.switchTab({ url: value, fail });
-            break;
-        case "redirectTo":
-            uni.redirectTo({ url: value, fail });
-            break;
-        case "reLaunch":
-            uni.reLaunch({ url: value, fail });
-            break;
-        case "webview":
-            // H5 需要上层承载页接入；这里仅 Toast 告知
-            if (!silent) uni.showToast({ title: `H5：${value}`, icon: "none" });
-            break;
-        case "miniprogram": {
-            // @ts-ignore 部分平台 navigateToMiniProgram 定义可能缺失
-            uni.navigateToMiniProgram?.({
-                appId: value,
-                path: options.path || "",
-                envVersion: options.envVersion,
-                extraData: options.extraData ?? undefined,
-                fail,
-            });
-            break;
+function navigate(type: NavigateType = "navigateTo", url = "", options: NavigateOptions = {}) {
+    if (type === "navigateBack") {
+        uni.navigateBack({ delta: options.delta || 1, fail: failHandler("返回上一页", options) });
+        return;
+    }
+
+    if (!url) {
+        fail("跳转目标未配置", options);
+        return;
+    }
+
+    const onFail = failHandler(url, options);
+
+    if (type === "redirectTo") {
+        uni.redirectTo({ url, fail: onFail });
+        return;
+    }
+
+    if (type === "switchTab") {
+        uni.switchTab({ url, fail: onFail });
+        return;
+    }
+
+    if (type === "reLaunch") {
+        uni.reLaunch({ url, fail: onFail });
+        return;
+    }
+
+    if (type === "miniprogram") {
+        const openMiniProgram = uni.navigateToMiniProgram as
+            | ((options: UniApp.NavigateToMiniProgramOptions) => void)
+            | undefined;
+
+        if (!openMiniProgram) {
+            fail("当前平台不支持打开小程序", options);
+            return;
         }
-        case "navigateTo":
-        default:
-            uni.navigateTo({ url: value, fail });
-            break;
+
+        openMiniProgram({
+            appId: url,
+            path: options.path || "",
+            envVersion: options.envVersion || "release",
+            extraData: options.extraData,
+            fail: onFail,
+        });
+        return;
+    }
+
+    if (type === "webview") {
+        fail(`H5：${url}`, options);
+        return;
     }
+
+    uni.navigateTo({ url, fail: onFail });
 }
 
-/**
- * 路由 composable：返回跳转方法集合。
- *
- * @example
- *   const { navigate } = useRouter();
- *   navigate("switchTab", "/pages/index/index");
- */
-export function useRouter() {
+export function useNavigate() {
     return {
-        navigate: doNavigate,
+        navigate,
+        to: (url: string, options?: NavigateOptions) => navigate("navigateTo", url, options),
+        redirect: (url: string, options?: NavigateOptions) => navigate("redirectTo", url, options),
+        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),
     };
 }

package/src/composables/refs/README.md

@@ -0,0 +1,40 @@
+# 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` 的回调函数 |
+
+组件更新前和卸载时，内部会自动清空引用集合，避免旧引用残留。