@hlw-uni/mp-vue 1.2.26 → 2.0.0

package/src/composables/theme/index.ts

@@ -1,11 +1,16 @@
-import { ref, onMounted, onUnmounted } from "vue";
-import { useColor } from "@hlw-uni/mp-core";
+import { computed } from "vue";
+import { useColor } from "@/composables/color";
+import { useThemeStore } from "../../stores/theme";
 
 const { varsToStyle } = useColor();
 import { getCurrentFontVars } from "./font";
 import { getCurrentThemeVars } from "./palette";
 import { getCurrentAppearanceVars } from "./appearance";
 
+/**
+ * @deprecated 历史事件名；现已改用 pinia store 响应式驱动，emit 不再有效。
+ * 保留 export 仅为不破坏外部 import（不影响功能）。
+ */
 export const THEME_CHANGE_EVENT = "hlw:theme-change";
 
 /**
@@ -23,16 +28,26 @@ export function buildThemeStyle(): string {
     });
 }
 
+/**
+ * 获取主题样式字符串，用于注入 <page-meta :page-style>。
+ *
+ * 实现走 pinia store 响应式：store.scale / primaryColor / appearance 任一变化
+ * → computed 重算 → page-meta 自动 setData。
+ *
+ * 注：早期版本用 uni.$emit + onMounted+uni.$on 事件总线驱动，在 vue3 + 小程序部分
+ * 基础库下 emit 后 ref 不响应（导致字号 / 主题色 / 外观切换不生效）。已改成响应式驱动。
+ */
 export function useThemePageStyle() {
-    const themePageStyle = ref(buildThemeStyle());
-
-    const onThemeChange = () => {
-        themePageStyle.value = buildThemeStyle();
-    };
-
-    onMounted(() => uni.$on(THEME_CHANGE_EVENT, onThemeChange));
-    onUnmounted(() => uni.$off(THEME_CHANGE_EVENT, onThemeChange));
-
+    const store = useThemeStore();
+    const themePageStyle = computed(() => {
+        // 显式 track 三个响应字段，触发 computed 重算
+        // setScale / setTheme / setAppearance 内部已先 set storage 再改 ref，
+        // 所以 buildThemeStyle 从 storage 读到的一定是最新值
+        void store.scale;
+        void store.primaryColor;
+        void store.appearance;
+        return buildThemeStyle();
+    });
     return { themePageStyle };
 }
 

package/src/composables/theme/palette.ts

@@ -1,4 +1,4 @@
-import { useColor } from "@hlw-uni/mp-core";
+import { useColor } from "@/composables/color";
 
 const { hexToRgba, darkenHex } = useColor();
 

package/src/composables/utils/index.ts

@@ -0,0 +1,160 @@
+/**
+ * 小程序通用工具。
+ */
+
+export interface DownloadFileOptions {
+    /** 下载地址 */
+    url: string;
+    /** 文件保存路径，可选 */
+    filePath?: string;
+    /** HTTP 请求头，可选 */
+    header?: Record<string, string>;
+    /** 下载进度回调，可选 */
+    onProgress?: (progress: number, totalBytesWritten: number, totalBytesExpectedToWrite: number) => void;
+}
+
+export interface DownloadFileResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 临时文件路径 */
+    tempFilePath?: string;
+    /** 状态码 */
+    statusCode?: number;
+    /** 错误信息 */
+    errMsg?: string;
+}
+
+export type TapEvent = { currentTarget?: { dataset?: Record<string, any> } };
+
+/**
+ * 剪贴板、下载与相册保存工具集合。
+ */
+export function useUtils() {
+    /**
+     * 复制文本到剪贴板，可选显示成功提示。
+     */
+    function copy(data: string, showToast = true): Promise<boolean> {
+        return new Promise((resolve) => {
+            uni.setClipboardData({
+                data,
+                showToast: false,
+                success: () => {
+                    if (showToast) {
+                        uni.showToast({ title: "复制成功", icon: "none", duration: 1500 });
+                    }
+                    resolve(true);
+                },
+                fail: () => resolve(false),
+            });
+        });
+    }
+
+    /**
+     * 从事件 dataset 的 data-copy 字段读取文本并复制。
+     */
+    function copyFromEvent(event: TapEvent) {
+        const dataset = event?.currentTarget?.dataset;
+        const text = dataset?.copy;
+        if (text == null || text === "") return;
+        const showToast = dataset?.copyToast !== "false";
+        copy(String(text), showToast);
+    }
+
+    /**
+     * 读取当前剪贴板文本内容。
+     */
+    function paste(): Promise<string> {
+        return new Promise((resolve) => {
+            uni.getClipboardData({
+                success: (res) => resolve(res.data),
+                fail: () => resolve(""),
+            });
+        });
+    }
+
+    /**
+     * 将本地图片保存到系统相册。
+     */
+    function saveImage(filePath: string): Promise<boolean> {
+        return new Promise((resolve) => {
+            uni.saveImageToPhotosAlbum({
+                filePath,
+                success: () => {
+                    uni.showToast({ title: "保存成功", icon: "success" });
+                    resolve(true);
+                },
+                fail: (err) => {
+                    if (err.errMsg.includes("auth deny") || err.errMsg.includes("authorize")) {
+                        uni.showModal({
+                            title: "提示",
+                            content: "需要授权相册权限",
+                            confirmText: "去设置",
+                            success: (res) => {
+                                if (res.confirm) uni.openSetting();
+                            },
+                        });
+                    } else {
+                        uni.showToast({ title: "保存失败", icon: "none" });
+                    }
+                    resolve(false);
+                },
+            });
+        });
+    }
+
+    /**
+     * 下载文件并返回下载结果。
+     */
+    function downloadFile(options: DownloadFileOptions): Promise<DownloadFileResult> {
+        return new Promise((resolve) => {
+            const task = uni.downloadFile({
+                url: options.url,
+                filePath: options.filePath,
+                header: options.header,
+                success: (res) => {
+                    if (res.statusCode === 200) {
+                        resolve({ success: true, tempFilePath: res.tempFilePath, statusCode: res.statusCode });
+                    } else {
+                        resolve({ success: false, statusCode: res.statusCode, errMsg: `下载失败，状态码：${res.statusCode}` });
+                    }
+                },
+                fail: (err) => resolve({ success: false, errMsg: err.errMsg }),
+            });
+
+            if (options.onProgress) {
+                task.onProgressUpdate((res) => {
+                    options.onProgress!(res.progress, res.totalBytesWritten, res.totalBytesExpectedToWrite);
+                });
+            }
+        });
+    }
+
+    /**
+     * 下载远程图片并直接保存到相册。
+     */
+    async function downloadAndSaveImage(url: string, onProgress?: (progress: number) => void): Promise<boolean> {
+        try {
+            uni.showLoading({ title: "下载中...", mask: true });
+
+            const result = await downloadFile({
+                url,
+                onProgress: onProgress ? (progress) => onProgress(progress) : undefined,
+            });
+
+            uni.hideLoading();
+
+            if (!result.success || !result.tempFilePath) {
+                uni.showToast({ title: result.errMsg || "下载失败", icon: "none" });
+                return false;
+            }
+
+            return await saveImage(result.tempFilePath);
+        } catch {
+            uni.hideLoading();
+            uni.showToast({ title: "操作失败", icon: "none" });
+            return false;
+        }
+    }
+
+    return { copy, copyFromEvent, paste, saveImage, downloadFile, downloadAndSaveImage };
+}

package/src/composables/validate/index.ts

@@ -0,0 +1,58 @@
+/**
+ * useValidate - 校验工具 composable
+ */
+export function useValidate() {
+    /** 中国大陆手机号格式校验。 */
+    function phone(value: string): boolean {
+        return /^1[3-9]\d{9}$/.test(value);
+    }
+
+    /** 校验邮箱地址格式。 */
+    function email(value: string): boolean {
+        return /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(value);
+    }
+
+    /** 校验是否为合法 URL。 */
+    function url(value: string): boolean {
+        try {
+            new URL(value);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /** 18 位身份证号格式校验。 */
+    function idCard(value: string): boolean {
+        return /^[1-9]\d{5}(18|19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$/.test(value);
+    }
+
+    /** 普通民用车牌号格式校验。 */
+    function carNumber(value: string): boolean {
+        return /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-Z0-9]{5}$/.test(value);
+    }
+
+    /** 至少 8 位且同时包含字母和数字的密码校验。 */
+    function password(value: string): boolean {
+        return /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/.test(value);
+    }
+
+    /** 判断值是否为空字符串、空数组、空对象或 null/undefined。 */
+    function empty(value: unknown): boolean {
+        if (value == null) return true;
+        if (typeof value === "string") return value.trim() === "";
+        if (Array.isArray(value)) return value.length === 0;
+        if (typeof value === "object") return Object.keys(value).length === 0;
+        return false;
+    }
+
+    return {
+        phone,
+        email,
+        url,
+        idCard,
+        carNumber,
+        password,
+        empty,
+    };
+}

package/src/directives/copy.ts

@@ -0,0 +1,50 @@
+/**
+ * v-copy 指令 - 点击自动复制
+ *
+ * 用法：
+ *   <view v-copy="text">...</view>
+ *   <text v-copy="userId">{{ userId }}</text>
+ */
+import type { Directive, DirectiveBinding, VNode } from 'vue'
+
+/**
+ * 将文本复制到剪贴板，并显示成功提示。
+ */
+function copyText(data: string) {
+    uni.setClipboardData({
+        data,
+        showToast: false,
+        success: () => uni.showToast({ title: '复制成功', icon: 'none', duration: 1500 }),
+    })
+}
+
+/**
+ * 向 vnode 注入 onTap 事件，在点击时执行复制逻辑。
+ */
+function injectTap(vnode: VNode, binding: DirectiveBinding) {
+    if (!vnode.props) (vnode as any).props = {}
+    const props = vnode.props as Record<string, any>
+    const prev = props.onTap
+
+    props.onTap = (e: any) => {
+        prev?.(e)
+        const value = binding.value
+        if (value == null || value === '') return
+        copyText(String(value))
+    }
+}
+
+export const vCopy: Directive = {
+    /**
+     * 在指令创建时注入点击事件。
+     */
+    created(el: any, binding: DirectiveBinding, vnode: VNode) {
+        injectTap(vnode, binding)
+    },
+    /**
+     * 在绑定值更新前重新注入点击事件。
+     */
+    beforeUpdate(el: any, binding: DirectiveBinding, vnode: VNode) {
+        injectTap(vnode, binding)
+    },
+}

package/src/directives/index.ts

@@ -0,0 +1 @@
+export { vCopy } from './copy'

package/src/hlw.ts

@@ -0,0 +1,37 @@
+/**
+ * hlw - 全局命名空间工厂
+ * 提供 $msg、$device、$http、$utils、$color 的统一访问入口。
+ *
+ * 注意：广告能力请直接 `import { useAd } from "@hlw-uni/mp-vue"`，不再通过 hlw.$ad 暴露。
+ */
+import { useMsg } from '@/composables/msg';
+import { useDevice, type DeviceInfo } from '@/composables/device';
+import { http } from '@/composables/http';
+import { useUtils } from '@/composables/utils';
+import { useColor } from '@/composables/color';
+
+export interface HlwInstance {
+  $msg: ReturnType<typeof useMsg>;
+  $device: DeviceInfo;
+  $http: typeof http;
+  $utils: ReturnType<typeof useUtils>;
+  $color: ReturnType<typeof useColor>;
+}
+
+let _msg: ReturnType<typeof useMsg> | null = null;
+let _device: ReturnType<typeof useDevice> | null = null;
+let _utils: ReturnType<typeof useUtils> | null = null;
+let _color: ReturnType<typeof useColor> | null = null;
+
+export const hlw: HlwInstance = {
+  /** 延迟创建消息提示实例。 */
+  get $msg() { return (_msg ??= useMsg()); },
+  /** 延迟读取并缓存设备信息。 */
+  get $device() { return (_device ??= useDevice()).value!; },
+  /** 复用全局 HTTP 实例。 */
+  $http: http,
+  /** 延迟创建通用工具实例。 */
+  get $utils() { return (_utils ??= useUtils()); },
+  /** 延迟创建颜色工具实例。 */
+  get $color() { return (_color ??= useColor()); },
+};

package/src/index.ts

@@ -1,27 +1,28 @@
 /**
- * @hlw-uni/mp-vue package root exports
+ * @hlw-uni/mp-vue 统一导出
  *
- * Note:
- * Components are resolved through easycom using `@hlw-uni/mp-vue/src/components/...`.
- * The package root only exports plain TS modules so uni-app does not try to bundle
- * compiled SFC runtime helpers from the library entry.
+ * 2.0 起合并了原 @hlw-uni/mp-core 全部内容。
+ * 业务方一处 import，无需再分包：
+ *   import { useAd, useMsg, useColor, useThemePageStyle, ... } from "@hlw-uni/mp-vue";
+ *
+ * UI 组件（hlw-page / hlw-button / hlw-ad 等）走 easycom 自动注册，不在这里 export。
  */
 
-export type { FontScale, FontPreset, ThemeColor } from "./composables/theme";
+// Composables / 工具 / Theme
+export * from "./composables";
+
+// 类型
 export type { HlwMenuItem } from "./components/hlw-menu/types";
 export type { HlwPagingRef, HlwPagingInstance } from "./components/hlw-paging/types";
-export {
-    FONT_PRESETS,
-    FONT_SCALE_KEY,
-    DEFAULT_THEMES,
-    THEME_COLOR_KEY,
-    THEME_SEMANTIC_COLORS,
-    THEME_CHANGE_EVENT,
-    getCurrentFontScale,
-    getCurrentFontVars,
-    getCurrentThemeColor,
-    getCurrentThemeVars,
-    buildThemeStyle,
-    useThemePageStyle,
-} from "./composables/theme";
+
+// Pinia store
 export { useThemeStore } from "./stores/theme";
+
+// App 根上下文
+export { useApp, setupDefaultInterceptors } from "./app";
+
+// hlw 全局命名空间
+export { hlw, type HlwInstance } from "./hlw";
+
+// 指令
+export { vCopy } from "./directives";