@hlw-uni/mp-vue 1.2.28 → 2.0.2

package/src/composables/loading/index.ts

@@ -0,0 +1,23 @@
+/**
+ * useLoading - 全局 Loading 状态
+ */
+export function useLoading() {
+    /**
+     * 显示全局加载提示。
+     */
+    function showLoading(message = "加载中...") {
+        uni.showLoading({ title: message, mask: true });
+    }
+
+    /**
+     * 关闭全局加载提示。
+     */
+    function hideLoading() {
+        uni.hideLoading();
+    }
+
+    return {
+        showLoading,
+        hideLoading,
+    };
+}

package/src/composables/msg/index.ts

@@ -0,0 +1,132 @@
+/**
+ * useMsg - 消息提示 composable
+ */
+export type ToastIcon = "success" | "fail" | "exception" | "none";
+export type ToastDuration = "short" | "long";
+
+export interface ToastOptions {
+    message: string;
+    icon?: ToastIcon;
+    image?: string;
+    duration?: number;
+    mask?: boolean;
+    position?: "top" | "center" | "bottom";
+}
+
+export interface ModalOptions {
+    title?: string;
+    content: string;
+    confirmText?: string;
+    cancelText?: string;
+    confirmColor?: string;
+    cancelColor?: string;
+}
+
+export interface HlwMsg {
+    toast(opts: ToastOptions | string): void;
+    success(message: string): void;
+    error(message: string): void;
+    fail(message: string): void;
+    showLoading(message?: string): void;
+    hideLoading(): void;
+    confirm(opts: ModalOptions): Promise<boolean>;
+    modal(opts: ModalOptions): Promise<boolean>;
+    setLoadingBar(progress: number): void;
+}
+
+/**
+ * 统一的消息提示与弹窗能力。
+ */
+export function useMsg(): HlwMsg {
+    /**
+     * 显示普通 toast，支持字符串或完整配置。
+     */
+    function toast(opts: ToastOptions | string) {
+        const normalized: ToastOptions = typeof opts === "string" ? { message: opts } : opts;
+        const { message, icon = "none", image, duration = 2000, mask = false, position = "center" } = normalized;
+        uni.showToast({ title: message, icon, image, duration, mask, position });
+    }
+
+    /**
+     * 显示成功提示。
+     */
+    function success(message: string) {
+        uni.showToast({ title: message, icon: "success", duration: 2000 });
+    }
+
+    /**
+     * 显示失败提示。
+     */
+    function error(message: string) {
+        uni.showToast({ title: message, icon: "fail", duration: 2000 });
+    }
+
+    /**
+     * 显示全局 loading。
+     */
+    function showLoading(message = "加载中...") {
+        uni.showLoading({ title: message, mask: true });
+    }
+
+    /**
+     * 关闭全局 loading。
+     */
+    function hideLoading() {
+        uni.hideLoading();
+    }
+
+    /**
+     * 显示确认弹窗，返回用户是否点击确认。
+     */
+    function confirm(opts: ModalOptions): Promise<boolean> {
+        return new Promise((resolve) => {
+            const {
+                title = "提示",
+                content,
+                confirmText = "确定",
+                cancelText = "取消",
+                confirmColor = "#3b82f6",
+                cancelColor = "#999999",
+            } = opts;
+            uni.showModal({
+                title,
+                content,
+                confirmText,
+                cancelText,
+                confirmColor,
+                cancelColor,
+                success: (res) => resolve(res.confirm),
+                fail: () => resolve(false),
+            });
+        });
+    }
+
+    /**
+     * modal 是 confirm 的语义别名。
+     */
+    function modal(opts: ModalOptions): Promise<boolean> {
+        return confirm(opts);
+    }
+
+    /**
+     * 通过标题文本模拟简单进度条展示。
+     */
+    function setLoadingBar(progress: number) {
+        const clamped = Math.max(0, Math.min(100, progress));
+        uni.setNavigationBarTitle({
+            title: `${"■".repeat(Math.round(clamped / 2))}${"□".repeat(50 - Math.round(clamped / 2))} ${clamped}%`,
+        });
+    }
+
+    return {
+        toast,
+        success,
+        error,
+        fail: error,
+        showLoading,
+        hideLoading,
+        confirm,
+        modal,
+        setLoadingBar,
+    };
+}

package/src/composables/navigator/index.ts

@@ -0,0 +1,104 @@
+/**
+ * 路由/跳转能力 —— 包装 uni-app 各类 jump API 为一个统一对象
+ *
+ * 使用：
+ *   const { navigate } = useRouter();
+ *   navigate(tool.jump_type, tool.jump_value);
+ *
+ * 未装 vue-router 也能用；命名风格对齐 Vue Router，熟悉的 push/replace/back
+ * 会在后续迭代中补齐。
+ */
+
+/** 已知的跳转类型；保留 `(string & {})` 允许任意自定义值向下兼容 */
+export type NavigateType =
+    | "navigateTo"
+    | "redirectTo"
+    | "switchTab"
+    | "reLaunch"
+    | "webview"
+    | "miniprogram"
+    | (string & {});
+
+export interface NavigateOptions {
+    /** 失败回调，收到 uni 返回的错误信息 */
+    onFail?: (errMsg: string) => void;
+    /** 是否禁用默认的 Toast 错误提示，默认 false */
+    silent?: boolean;
+    /** 仅 miniprogram：目标小程序的页面路径（如 pages/index/index?id=1），留空则打开首页 */
+    path?: string;
+    /** 仅 miniprogram：目标小程序版本，默认 release */
+    envVersion?: "develop" | "trial" | "release";
+    /** 仅 miniprogram：传给目标小程序的额外数据，对方从 onLaunch/onShow 读取 */
+    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;
+
+    if (!value) {
+        if (!silent) uni.showToast({ title: "跳转目标未配置", icon: "none" });
+        onFail?.("跳转目标未配置");
+        return;
+    }
+
+    const fail = (err?: { errMsg?: string }) => {
+        const msg = err?.errMsg || `无法跳转：${value}`;
+        if (!silent) uni.showToast({ title: msg, icon: "none" });
+        onFail?.(msg);
+    };
+
+    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,
+                fail,
+            });
+            break;
+        }
+        case "navigateTo":
+        default:
+            uni.navigateTo({ url: value, fail });
+            break;
+    }
+}
+
+/**
+ * 路由 composable：返回跳转方法集合。
+ *
+ * @example
+ *   const { navigate } = useRouter();
+ *   navigate("switchTab", "/pages/index/index");
+ */
+export function useRouter() {
+    return {
+        navigate: doNavigate,
+    };
+}

package/src/composables/page-meta/index.ts

@@ -0,0 +1,49 @@
+/**
+ * usePageMeta - 页面元信息 composable
+ */
+export interface PageMeta {
+    title?: string;
+    navigationBarTitleText?: string;
+    navigationBarBackgroundColor?: string;
+    navigationBarTextStyle?: "white" | "black";
+    backgroundColor?: string;
+    enablePullDownRefresh?: boolean;
+}
+
+/**
+ * 页面导航栏与背景元信息工具。
+ */
+export function usePageMeta() {
+    /**
+     * 设置当前页面标题。
+     */
+    function setTitle(title: string) {
+        uni.setNavigationBarTitle({ title });
+    }
+
+    /**
+     * 批量设置页面标题、导航栏和背景样式。
+     */
+    function setOptions(options: PageMeta) {
+        if (options.title || options.navigationBarTitleText) {
+            setTitle(options.title || options.navigationBarTitleText!);
+        }
+        if (options.navigationBarBackgroundColor || options.navigationBarTextStyle) {
+            uni.setNavigationBarColor({
+                frontColor: options.navigationBarTextStyle === "white" ? "#ffffff" : "#000000",
+                backgroundColor: options.navigationBarBackgroundColor ?? "#ffffff",
+            });
+        }
+        if (options.backgroundColor) {
+            uni.setBackgroundColor({ backgroundColor: options.backgroundColor });
+        }
+        if (options.enablePullDownRefresh !== undefined) {
+            uni.setBackgroundTextStyle({ textStyle: "dark" });
+        }
+    }
+
+    return {
+        setTitle,
+        setOptions,
+    };
+}

package/src/composables/refs/index.ts

@@ -0,0 +1,30 @@
+/**
+ * useRefs - 模板 Ref 批量管理
+ *
+ * 用于 v-for 场景下收集一组动态生成的子元素或子组件引用。
+ */
+import { ref, onBeforeUpdate, onUnmounted } from "vue";
+
+/**
+ * 管理动态 ref 集合，适合 v-for 场景。
+ */
+export function useRefs() {
+    const refs = ref<Record<string, any>>({});
+
+    onBeforeUpdate(() => {
+        refs.value = {};
+    });
+
+    onUnmounted(() => {
+        refs.value = {};
+    });
+
+    /**
+     * 按 key 生成 ref 回调并写入 refs 集合。
+     */
+    const setRefs = (key: string) => (el: any) => {
+        if (el) refs.value[key] = el;
+    };
+
+    return { refs, setRefs };
+}

package/src/composables/share/index.ts

@@ -0,0 +1,189 @@
+/**
+ * useShare - 小程序分享 composable
+ *
+ * 两层 API 并存：
+ *   - useShare(config)     —— SDK 层：直接注册 onShareAppMessage / onShareTimeline 钩子
+ *   - useShareConfig(...)  —— 业务层：lazy load 后端配置 + cache + fallback resolver
+ */
+import { onShareAppMessage, onShareTimeline } from '@dcloudio/uni-app';
+import { ref } from 'vue';
+import { unwrapPayload, type AdapterPayload } from '../_internal/unwrap';
+
+export interface ShareAppMessageContent {
+    /** 分享标题 */
+    title?: string;
+    /** 分享路径，必须是以 / 开头的完整路径 */
+    path?: string;
+    /** 自定义图片路径 */
+    imageUrl?: string;
+}
+
+export interface ShareTimelineContent {
+    /** 朋友圈分享标题 */
+    title?: string;
+    /** 页面携带的 query 参数 */
+    query?: string;
+    /** 自定义图片路径 */
+    imageUrl?: string;
+}
+
+export interface ShareConfig extends ShareAppMessageContent {
+    /** 朋友圈专属配置，不填则复用朋友分享配置 */
+    timeline?: ShareTimelineContent;
+}
+
+/**
+ * 分享来源。
+ * - `button` 页面内转发按钮
+ * - `menu` 右上角菜单
+ */
+export type ShareFrom = 'button' | 'menu';
+
+export type ShareConfigResolver = (from: ShareFrom) => ShareConfig;
+
+/**
+ * 注册小程序分享钩子。
+ */
+export function useShare(config: ShareConfig | ShareConfigResolver) {
+    /**
+     * 根据分享来源解析最终分享配置。
+     */
+    const resolve = (from: ShareFrom): ShareConfig =>
+        typeof config === 'function' ? config(from) : config;
+
+    /**
+     * 注册分享给朋友的回调。
+     */
+    onShareAppMessage((options: { from?: string } | undefined) => {
+        const resolved = resolve((options?.from as ShareFrom) ?? 'menu');
+        const payload: ShareAppMessageContent = {};
+        if (resolved.title !== undefined) payload.title = resolved.title;
+        if (resolved.path !== undefined) payload.path = resolved.path;
+        if (resolved.imageUrl !== undefined) payload.imageUrl = resolved.imageUrl;
+        return payload;
+    });
+
+    /**
+     * 注册分享到朋友圈的回调。
+     */
+    onShareTimeline(() => {
+        const resolved = resolve('menu');
+        const timeline = resolved.timeline ?? {};
+        const payload: ShareTimelineContent = {};
+        const title = timeline.title ?? resolved.title;
+        const imageUrl = timeline.imageUrl ?? resolved.imageUrl;
+        if (title !== undefined) payload.title = title;
+        if (timeline.query !== undefined) payload.query = timeline.query;
+        if (imageUrl !== undefined) payload.imageUrl = imageUrl;
+        return payload;
+    });
+}
+
+/* ============================================================
+ * useShareConfig —— 业务层：lazy load 后端聚合配置 + cache + fallback resolver
+ *
+ * 后端按页面 key 聚合返回各页 title / image，前端拉一次缓存全局共用。
+ * 返回的 resolver 同时喂给 onShareAppMessage 和 onShareTimeline。
+ *
+ * 使用方式：
+ *
+ *   1. App.vue / bootstrap 注入回调：
+ *
+ *      setConfigShare({
+ *          getConfig: async () => {
+ *              const res = await getShareConfig();
+ *              return res.code === 1 ? res.data : null;
+ *          },
+ *      });
+ *
+ *   2. 任意页面 setup：
+ *
+ *      const share = useShareConfig("index", {
+ *          title: "兜底标题",
+ *          path: "/pages/index/index",
+ *      });
+ *      onShareAppMessage(share);
+ *      onShareTimeline(share);
+ * ============================================================ */
+
+/** 单页分享配置 */
+export interface PageShareItem {
+    title: string;
+    image: string;
+}
+
+/** 后端返回的页面 key → 配置映射 */
+export type ShareConfigMap = Record<string, PageShareItem>;
+
+/**
+ * Adapter 注入接口 —— getConfig 支持「已解包」或「ThinkAdmin envelope」两种返回值。
+ * 业务方可以直接传 envelope-returning 接口：setConfigShare({ getConfig: getShareConfig })
+ */
+export interface ShareConfigAdapter {
+    getConfig: () => Promise<AdapterPayload<ShareConfigMap>>;
+}
+
+/** 页面声明的兜底文案 / 跳转路径 */
+export interface PageShareFallback {
+    /** 后端 title 为空时用 */
+    title: string;
+    /** 分享跳转路径（必须 / 开头）；path 不走后端，由页面自定义 */
+    path: string;
+    /** 后端 image 为空时用；通常留空让微信自动截图 */
+    image?: string;
+}
+
+/** 分享 payload —— 同时喂给 onShareAppMessage / onShareTimeline */
+export interface SharePayload {
+    title: string;
+    path: string;
+    imageUrl?: string;
+}
+
+let shareAdapter: ShareConfigAdapter | null = null;
+const shareCache = ref<ShareConfigMap | null>(null);
+let sharePending: Promise<void> | null = null;
+
+/**
+ * 注入业务回调（应用启动时调用一次；不调用则始终用 fallback）。
+ */
+export function setConfigShare(a: ShareConfigAdapter): void {
+    shareAdapter = a;
+}
+
+function loadShareConfig(): Promise<void> {
+    if (shareCache.value) return Promise.resolve();
+    if (sharePending) return sharePending;
+    if (!shareAdapter?.getConfig) {
+        console.warn("[useShareConfig] adapter.getConfig 未注入；先调用 setConfigShare()");
+        return Promise.resolve();
+    }
+    sharePending = shareAdapter.getConfig()
+        .then((raw) => {
+            const cfg = unwrapPayload(raw);
+            if (cfg) shareCache.value = cfg;
+        })
+        .catch((e) => {
+            console.warn("[useShareConfig] load failed", e);
+        })
+        .finally(() => {
+            sharePending = null;
+        });
+    return sharePending;
+}
+
+/**
+ * 业务级分享配置 helper —— 返回 resolver，可直接喂 onShareAppMessage / onShareTimeline。
+ * 后端配置异步加载，加载完成前先用 fallback、加载完后自动切到后端值。
+ */
+export function useShareConfig(pageKey: string, fallback: PageShareFallback) {
+    void loadShareConfig();
+    return (): SharePayload => {
+        const remote = shareCache.value?.[pageKey];
+        const title = remote?.title || fallback.title;
+        const image = remote?.image || fallback.image;
+        const payload: SharePayload = { title, path: fallback.path };
+        if (image) payload.imageUrl = image;
+        return payload;
+    };
+}

package/src/composables/storage/index.ts

@@ -0,0 +1,76 @@
+/**
+ * useStorage - 本地存储 composable
+ */
+export interface StorageInstance {
+    get: <T = unknown>(key: string) => T | null;
+    set: <T>(key: string, value: T) => boolean;
+    remove: (key: string) => boolean;
+    clear: () => boolean;
+    info: () => UniApp.GetStorageInfoSuccess | null;
+}
+
+/**
+ * 本地存储读写工具。
+ */
+export function useStorage(): StorageInstance {
+    /**
+     * 读取指定 key 的缓存值。
+     */
+    function get<T = unknown>(key: string): T | null {
+        try {
+            const value = uni.getStorageSync(key);
+            return value ?? null;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * 写入指定 key 的缓存值。
+     */
+    function set<T>(key: string, value: T): boolean {
+        try {
+            uni.setStorageSync(key, value);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * 删除指定 key 的缓存值。
+     */
+    function remove(key: string): boolean {
+        try {
+            uni.removeStorageSync(key);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * 清空全部本地缓存。
+     */
+    function clear(): boolean {
+        try {
+            uni.clearStorageSync();
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * 获取当前缓存使用信息。
+     */
+    function info(): UniApp.GetStorageInfoSuccess | null {
+        try {
+            return uni.getStorageInfoSync();
+        } catch {
+            return null;
+        }
+    }
+
+    return { get, set, remove, clear, info };
+}

package/src/composables/theme/font.ts

@@ -1,4 +1,4 @@
-export type FontScale = "small" | "normal" | "large" | "xlarge";
+export type FontScale = "small" | "compact" | "normal" | "medium" | "large" | "xlarge" | "xxlarge";
 
 export interface FontPreset {
     label: string;
@@ -9,12 +9,19 @@ export const FONT_SCALE_KEY = "hlw_font_scale";
 
 export const FONT_PRESETS: Record<FontScale, FontPreset> = {
     small: {
-        label: "小字体",
+        label: "较小",
         vars: {
             "--font-xs": "16rpx", "--font-sm": "20rpx", "--font-base": "24rpx",
             "--font-md": "28rpx", "--font-lg": "32rpx", "--font-xl": "36rpx",
         },
     },
+    compact: {
+        label: "略小",
+        vars: {
+            "--font-xs": "18rpx", "--font-sm": "22rpx", "--font-base": "26rpx",
+            "--font-md": "30rpx", "--font-lg": "34rpx", "--font-xl": "38rpx",
+        },
+    },
     normal: {
         label: "标准",
         vars: {
@@ -22,26 +29,40 @@ export const FONT_PRESETS: Record<FontScale, FontPreset> = {
             "--font-md": "32rpx", "--font-lg": "36rpx", "--font-xl": "40rpx",
         },
     },
+    medium: {
+        label: "适中",
+        vars: {
+            "--font-xs": "22rpx", "--font-sm": "28rpx", "--font-base": "32rpx",
+            "--font-md": "36rpx", "--font-lg": "42rpx", "--font-xl": "46rpx",
+        },
+    },
     large: {
-        label: "大字体",
+        label: "较大",
         vars: {
             "--font-xs": "24rpx", "--font-sm": "30rpx", "--font-base": "34rpx",
             "--font-md": "40rpx", "--font-lg": "46rpx", "--font-xl": "52rpx",
         },
     },
     xlarge: {
-        label: "超大字体",
+        label: "超大",
         vars: {
             "--font-xs": "28rpx", "--font-sm": "36rpx", "--font-base": "42rpx",
             "--font-md": "48rpx", "--font-lg": "56rpx", "--font-xl": "64rpx",
         },
     },
+    xxlarge: {
+        label: "特大",
+        vars: {
+            "--font-xs": "32rpx", "--font-sm": "42rpx", "--font-base": "48rpx",
+            "--font-md": "56rpx", "--font-lg": "64rpx", "--font-xl": "72rpx",
+        },
+    },
 };
 
 export function getCurrentFontScale(): FontScale {
     try {
         const v = uni.getStorageSync(FONT_SCALE_KEY);
-        if (v === "small" || v === "large" || v === "xlarge") return v;
+        if (v === "small" || v === "compact" || v === "medium" || v === "large" || v === "xlarge" || v === "xxlarge") return v;
     } catch {}
     return "normal";
 }