@hlw-uni/mp-vue 2.1.52 → 2.1.55

package/src/composables/share/index.ts

@@ -1,189 +1,85 @@
-/**
- * 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';
+import {
+    onShareAppMessage as registerShareAppMessage,
+    onShareTimeline as registerShareTimeline,
+} from "@dcloudio/uni-app";
 
-export interface ShareAppMessageContent {
-    /** 分享标题 */
+export interface ShareConfig {
     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 = ShareConfig | (() => ShareConfig);
 
-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;
-    });
+export interface ShareHandlers {
+    onShareAppMessage: (config?: ShareConfigResolver) => void;
+    onShareTimeline: (config?: ShareConfigResolver) => void;
+    showShareMenu: () => void;
 }
 
-/* ============================================================
- * 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;
+function resolveConfig(config?: ShareConfigResolver): ShareConfig {
+    return typeof config === "function" ? config() : (config ?? {});
 }
 
-/** 后端返回的页面 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;
+function buildPayload(base: ShareConfigResolver, extra?: ShareConfigResolver): ShareConfig {
+    const current = {
+        ...resolveConfig(base),
+        ...resolveConfig(extra),
+    };
+    const payload: ShareConfig = {};
+    if (current.title) payload.title = current.title;
+    if (current.path) payload.path = current.path;
+    if (current.imageUrl) payload.imageUrl = current.imageUrl;
+    return payload;
 }
 
-/** 分享 payload —— 同时喂给 onShareAppMessage / onShareTimeline */
-export interface SharePayload {
-    title: string;
-    path: string;
-    imageUrl?: string;
+function showShareMenu(): void {
+    const api = typeof uni !== "undefined" ? (uni as unknown as {
+        showShareMenu?: (options: {
+            withShareTicket?: boolean;
+            menus?: string[];
+            fail?: () => void;
+        }) => void;
+    }) : undefined;
+
+    api?.showShareMenu?.({
+        withShareTicket: true,
+        menus: ["shareAppMessage", "shareTimeline"],
+        fail: () => undefined,
+    });
 }
 
-let shareAdapter: ShareConfigAdapter | null = null;
-const shareCache = ref<ShareConfigMap | null>(null);
-let sharePending: Promise<void> | null = null;
+export function useShare(config: ShareConfigResolver = {}): ShareHandlers {
+    let appMessageRegistered = false;
+    let timelineRegistered = false;
 
-/**
- * 注入业务回调（应用启动时调用一次；不调用则始终用 fallback）。
- */
-export function setConfigShare(a: ShareConfigAdapter): void {
-    shareAdapter = a;
-}
+    const onShareAppMessage = (extra?: ShareConfigResolver) => {
+        if (appMessageRegistered) return;
+        appMessageRegistered = true;
+        showShareMenu();
+        registerShareAppMessage(() => buildPayload(config, extra));
+    };
 
-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;
+    const onShareTimeline = (extra?: ShareConfigResolver) => {
+        if (timelineRegistered) return;
+        timelineRegistered = true;
+        showShareMenu();
+        registerShareTimeline(() => {
+            const payload = buildPayload(config, extra);
+            return {
+                title: payload.title,
+                query: payload.path?.split("?")[1],
+                imageUrl: payload.imageUrl,
+            };
         });
-    return sharePending;
-}
+    };
+
+    onShareAppMessage();
+    onShareTimeline();
 
-/**
- * 业务级分享配置 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;
+    return {
+        onShareAppMessage,
+        onShareTimeline,
+        showShareMenu,
     };
 }

package/src/composables/theme/README.md

@@ -0,0 +1,131 @@
+# theme 调用文档
+
+`theme` 模块提供字体档位、主题色、外观模式、排版 token 和 `page-meta` 样式注入能力。
+
+## 引入
+
+```ts
+import {
+    useThemePageStyle,
+    getCurrentFontScale,
+    getCurrentFontVars,
+    getCurrentThemeColor,
+    getCurrentThemeVars,
+    getCurrentAppearance,
+    getCurrentAppearanceMode,
+    getCurrentAppearanceVars,
+    getCurrentTypographyVars,
+} from "@hlw-uni/mp-vue";
+```
+
+## useThemePageStyle
+
+页面需要把主题 CSS 变量注入到小程序 page 根时使用。
+
+```vue
+<template>
+    <page-meta :page-style="themePageStyle" />
+    <hlw-page>
+        页面内容
+    </hlw-page>
+</template>
+
+<script setup lang="ts">
+import { useThemePageStyle } from "@hlw-uni/mp-vue";
+
+const { themePageStyle } = useThemePageStyle();
+</script>
+```
+
+如果项目启用了 `@hlw-uni/mp-vite-plugin` 的 `themePageMeta`，页面可由插件自动注入 `<page-meta>` 和 `useThemePageStyle`。
+
+## 字体档位
+
+```ts
+const scale = getCurrentFontScale();
+const vars = getCurrentFontVars();
+
+console.log(scale, vars["--font-base"]);
+```
+
+支持的 `FontScale`：
+
+| 值 | 说明 |
+| --- | --- |
+| `small` | 较小 |
+| `compact` | 略小 |
+| `normal` | 标准 |
+| `medium` | 适中 |
+| `large` | 较大 |
+| `xlarge` | 超大 |
+| `xxlarge` | 特大 |
+
+## 主题色
+
+```ts
+const color = getCurrentThemeColor();
+const vars = getCurrentThemeVars();
+
+console.log(color, vars["--primary-color"]);
+```
+
+常用导出：
+
+| 导出 | 说明 |
+| --- | --- |
+| `THEME_COLOR_KEY` | 主题色 storage key |
+| `THEME_SEMANTIC_COLORS` | 语义色 |
+| `DEFAULT_THEMES` | 内置主题色列表 |
+| `getCurrentThemeColor()` | 读取当前主题色 |
+| `getCurrentThemeVars()` | 生成主题色 CSS 变量 |
+
+## 外观模式
+
+```ts
+const appearance = getCurrentAppearance();
+const mode = getCurrentAppearanceMode();
+const vars = getCurrentAppearanceVars();
+
+console.log(appearance, mode, vars["--bg-page"]);
+```
+
+`Appearance` 支持：
+
+| 值 | 说明 |
+| --- | --- |
+| `light` | 浅色模式 |
+| `dark` | 深色模式 |
+| `auto` | 跟随系统 |
+
+## 排版 token
+
+```ts
+const vars = getCurrentTypographyVars();
+
+console.log(vars["--text-title-size"]);
+```
+
+内置语义角色：
+
+| 角色 | 用途 |
+| --- | --- |
+| `title-lg` | 页面大标题 |
+| `title` | 卡片或分区主标题 |
+| `subtitle` | 次级标题 |
+| `body` | 正文 |
+| `desc` | 描述文字 |
+| `caption` | 角标、时间戳等小字 |
+
+## 切换主题
+
+主题状态由 `useThemeStore` 管理，store 会写入 storage，`useThemePageStyle` 会响应 `scale` 和 `primaryColor` 变化。
+
+```ts
+import { useThemeStore } from "@hlw-uni/mp-vue";
+
+const theme = useThemeStore();
+
+theme.setScale("large");
+theme.setTheme("#3b82f6");
+theme.setAppearance("auto");
+```

package/src/composables/theme/index.ts

@@ -1,8 +1,6 @@
 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";
 
@@ -25,6 +23,10 @@ export function buildThemeStyle(): string {
     });
 }
 
+function varsToStyle(vars: Record<string, string>): string {
+    return Object.entries(vars).map(([key, value]) => `${key}:${value}`).join(";") + ";";
+}
+
 /**
  * 获取主题样式字符串，用于注入 <page-meta :page-style>。
  *

package/src/composables/theme/palette.ts

@@ -1,7 +1,3 @@
-import { useColor } from "@/composables/color";
-
-const { hexToRgba, darkenHex } = useColor();
-
 export interface ThemeColor {
     label: string;
     value: string;
@@ -65,3 +61,25 @@ export function getCurrentThemeVars(): Record<string, string> {
         "--info-dark": darkenHex(THEME_SEMANTIC_COLORS.info),
     };
 }
+
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+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),
+    ];
+}
+
+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 darken = (value: number) => Math.max(0, Math.round(value * (1 - amount)));
+    return `#${darken(r).toString(16).padStart(2, "0")}${darken(g).toString(16).padStart(2, "0")}${darken(b).toString(16).padStart(2, "0")}`;
+}

package/src/composables/utils/README.md

@@ -0,0 +1,81 @@
+# utils 调用文档
+
+`useUtils` 提供剪贴板、下载、保存相册、query 拼接和基础类型转换工具。
+
+## 引入
+
+```ts
+import { useUtils } from "@hlw-uni/mp-vue";
+```
+
+## 基础用法
+
+```ts
+const utils = useUtils();
+
+await utils.copy("要复制的文本");
+const text = await utils.paste();
+
+const qs = utils.toQuery({ id: 1, keyword: "测试" });
+const url = utils.withQuery("/pages/search/index", qs);
+
+const age = utils.toNumber("18", 0);
+const enabled = utils.toBoolean("1", false);
+```
+
+## 下载和保存
+
+```ts
+const res = await utils.download({
+    url: "https://example.com/a.png",
+    progress: (value, done, total) => {
+        console.log(value, done, total);
+    },
+});
+
+if (res.ok && res.path) {
+    await utils.saveImage(res.path);
+}
+
+await utils.saveImageUrl("https://example.com/a.png");
+await utils.saveVideoUrl("https://example.com/a.mp4");
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `withQuery(url, qs)` | 为 URL 追加 query |
+| `toQuery(data)` | 对象转 URL query |
+| `signText(url)` | 生成签名原文，query 会排序 |
+| `toNumber(value, defaultValue)` | 安全转数字 |
+| `toBoolean(value, defaultValue)` | 安全转布尔 |
+| `copy(text, tip?)` | 复制文本 |
+| `paste()` | 读取剪贴板 |
+| `saveImage(path)` | 保存本地图片到相册 |
+| `saveVideo(path)` | 保存本地视频到相册 |
+| `download(options)` | 下载文件 |
+| `saveImageUrl(url, progress?)` | 下载远程图片并保存 |
+| `saveVideoUrl(url, progress?)` | 下载远程视频并保存 |
+
+## DownloadOpt
+
+```ts
+interface DownloadOpt {
+    url: string;
+    path?: string;
+    header?: Record<string, string>;
+    progress?: (value: number, done: number, total: number) => void;
+}
+```
+
+## DownloadRes
+
+```ts
+interface DownloadRes {
+    ok: boolean;
+    path?: string;
+    code?: number;
+    msg?: string;
+}
+```