@hlw-uni/mp-vue 2.1.54 → 2.1.55

package/dist/composables/ad/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 小程序广告工具。
+ */
+export interface AdRes {
+    ok: boolean;
+    isEnded?: boolean;
+    err?: unknown;
+}
+type AdDone = (res: AdRes) => void;
+export declare function useHlwAd(): {
+    setAdPopup: (adId: string, done?: ((ok: boolean) => void) | undefined) => boolean;
+    showAdPopup: (delay?: number) => Promise<boolean>;
+    setAdReward: (adId: string, done?: AdDone) => Promise<AdRes>;
+    showAdReward: () => Promise<AdRes>;
+};
+export {};

package/dist/composables/index.d.ts

@@ -6,6 +6,7 @@ export { useMsg, type HlwMsg, type ToastOptions, type ModalOptions, type ToastIc
 export { useDevice, clearDeviceCache, type DeviceInfo, type DeviceQueryInfo, } from './device';
 export { useRefs } from './refs';
 export { useShare, type ShareConfig, } from './share';
+export { useHlwAd, type AdRes } from './ad';
 export { useUtils, type DownloadOpt, type DownloadRes } from './utils';
 export { useNavigate, type NavigateType, type NavigateOptions } from './navigator';
 export type { FontScale, FontPreset } from './theme';

package/dist/index.js

@@ -34,6 +34,7 @@ var __publicField = (obj, key, value) => {
     buildFormData(ctx) {
       const c = ctx.credentials ?? {};
       return {
+        key: c["key"] ?? ctx.fileName,
         policy: c["policy"] ?? "",
         signature: c["signature"] ?? "",
         OSSAccessKeyId: c["accessKeyId"] ?? "",
@@ -630,8 +631,8 @@ var __publicField = (obj, key, value) => {
   }
   function showShareMenu() {
     var _a;
-    const api = typeof uni !== "undefined" ? uni : void 0;
-    (_a = api == null ? void 0 : api.showShareMenu) == null ? void 0 : _a.call(api, {
+    const api2 = typeof uni !== "undefined" ? uni : void 0;
+    (_a = api2 == null ? void 0 : api2.showShareMenu) == null ? void 0 : _a.call(api2, {
       withShareTicket: true,
       menus: ["shareAppMessage", "shareTimeline"],
       fail: () => void 0
@@ -670,6 +671,137 @@ var __publicField = (obj, key, value) => {
       showShareMenu
     };
   }
+  let popupAd = null;
+  let popupDone;
+  let popupClose = null;
+  let popupError = null;
+  let rewardAd = null;
+  let rewardDone;
+  let rewardPromise = null;
+  let rewardResolve = null;
+  let rewardClose = null;
+  let rewardError = null;
+  function api() {
+    return typeof wx === "undefined" ? null : wx;
+  }
+  function finish(res) {
+    rewardDone == null ? void 0 : rewardDone(res);
+    rewardResolve == null ? void 0 : rewardResolve(res);
+    rewardResolve = null;
+    rewardPromise = null;
+  }
+  function clearReward() {
+    var _a, _b;
+    if (!rewardAd)
+      return;
+    if (rewardClose)
+      (_a = rewardAd.offClose) == null ? void 0 : _a.call(rewardAd, rewardClose);
+    if (rewardError)
+      (_b = rewardAd.offError) == null ? void 0 : _b.call(rewardAd, rewardError);
+    rewardClose = null;
+    rewardError = null;
+  }
+  function useHlwAd() {
+    function clearPopup() {
+      var _a, _b;
+      if (!popupAd)
+        return;
+      if (popupClose)
+        (_a = popupAd.offClose) == null ? void 0 : _a.call(popupAd, popupClose);
+      if (popupError)
+        (_b = popupAd.offError) == null ? void 0 : _b.call(popupAd, popupError);
+      popupClose = null;
+      popupError = null;
+    }
+    function setAdPopup(adId, done) {
+      var _a, _b, _c;
+      popupDone = done;
+      const wxApi = api();
+      if (!adId || !(wxApi == null ? void 0 : wxApi.createInterstitialAd))
+        return false;
+      clearPopup();
+      popupAd = wxApi.createInterstitialAd({ adUnitId: adId });
+      (_a = popupAd.onLoad) == null ? void 0 : _a.call(popupAd, () => {
+      });
+      popupError = (err) => {
+        console.error("插屏广告加载失败", err);
+        popupDone == null ? void 0 : popupDone(false);
+      };
+      popupClose = () => {
+        popupDone == null ? void 0 : popupDone(true);
+      };
+      (_b = popupAd.onError) == null ? void 0 : _b.call(popupAd, popupError);
+      (_c = popupAd.onClose) == null ? void 0 : _c.call(popupAd, popupClose);
+      return true;
+    }
+    function showAdPopup(delay = 3e3) {
+      return new Promise((resolve) => {
+        if (!popupAd) {
+          resolve(false);
+          return;
+        }
+        const done = popupDone;
+        popupDone = (ok) => {
+          done == null ? void 0 : done(ok);
+          resolve(ok);
+        };
+        setTimeout(() => {
+          popupAd.show().catch((err) => {
+            console.error("插屏广告显示失败", err);
+            popupDone == null ? void 0 : popupDone(false);
+          });
+        }, Math.max(0, delay));
+      });
+    }
+    function setAdReward(adId, done) {
+      var _a, _b, _c;
+      rewardDone = done;
+      rewardPromise = new Promise((resolve) => {
+        rewardResolve = resolve;
+      });
+      const wxApi = api();
+      if (!adId || !(wxApi == null ? void 0 : wxApi.createRewardedVideoAd)) {
+        finish({ ok: false });
+        return rewardPromise;
+      }
+      clearReward();
+      rewardAd = wxApi.createRewardedVideoAd({ adUnitId: adId });
+      (_a = rewardAd.onLoad) == null ? void 0 : _a.call(rewardAd, () => {
+      });
+      rewardClose = (res) => {
+        finish({ ok: !!(res == null ? void 0 : res.isEnded), isEnded: !!(res == null ? void 0 : res.isEnded) });
+      };
+      rewardError = (err) => {
+        console.error("激励视频广告加载失败", err);
+        finish({ ok: false, err });
+      };
+      (_b = rewardAd.onClose) == null ? void 0 : _b.call(rewardAd, rewardClose);
+      (_c = rewardAd.onError) == null ? void 0 : _c.call(rewardAd, rewardError);
+      return rewardPromise;
+    }
+    function showAdReward() {
+      if (!rewardAd) {
+        return Promise.resolve({ ok: false });
+      }
+      const current = rewardPromise || new Promise((resolve) => {
+        rewardResolve = resolve;
+      });
+      rewardPromise = current;
+      rewardAd.show().catch(() => {
+        rewardAd.load().then(() => rewardAd.show()).catch((err) => {
+          console.error("激励视频广告显示失败", err);
+          finish({ ok: false, err });
+        });
+      });
+      return current;
+    }
+    return {
+      setAdPopup,
+      showAdPopup,
+      setAdReward,
+      showAdReward
+    };
+  }
   function fail(message, options = {}) {
     var _a;
     if (!options.silent) {
@@ -1200,6 +1332,7 @@ var __publicField = (obj, key, value) => {
   exports2.resolveAppearance = resolveAppearance;
   exports2.useApp = useApp;
   exports2.useDevice = useDevice;
+  exports2.useHlwAd = useHlwAd;
   exports2.useMsg = useMsg;
   exports2.useNavigate = useNavigate;
   exports2.useRefs = useRefs;

package/dist/index.mjs

@@ -33,6 +33,7 @@ const ossAdapter = {
   buildFormData(ctx) {
     const c = ctx.credentials ?? {};
     return {
+      key: c["key"] ?? ctx.fileName,
       policy: c["policy"] ?? "",
       signature: c["signature"] ?? "",
       OSSAccessKeyId: c["accessKeyId"] ?? "",
@@ -629,8 +630,8 @@ function buildPayload(base, extra) {
 }
 function showShareMenu() {
   var _a;
-  const api = typeof uni !== "undefined" ? uni : void 0;
-  (_a = api == null ? void 0 : api.showShareMenu) == null ? void 0 : _a.call(api, {
+  const api2 = typeof uni !== "undefined" ? uni : void 0;
+  (_a = api2 == null ? void 0 : api2.showShareMenu) == null ? void 0 : _a.call(api2, {
     withShareTicket: true,
     menus: ["shareAppMessage", "shareTimeline"],
     fail: () => void 0
@@ -669,6 +670,137 @@ function useShare(config = {}) {
     showShareMenu
   };
 }
+let popupAd = null;
+let popupDone;
+let popupClose = null;
+let popupError = null;
+let rewardAd = null;
+let rewardDone;
+let rewardPromise = null;
+let rewardResolve = null;
+let rewardClose = null;
+let rewardError = null;
+function api() {
+  return typeof wx === "undefined" ? null : wx;
+}
+function finish(res) {
+  rewardDone == null ? void 0 : rewardDone(res);
+  rewardResolve == null ? void 0 : rewardResolve(res);
+  rewardResolve = null;
+  rewardPromise = null;
+}
+function clearReward() {
+  var _a, _b;
+  if (!rewardAd)
+    return;
+  if (rewardClose)
+    (_a = rewardAd.offClose) == null ? void 0 : _a.call(rewardAd, rewardClose);
+  if (rewardError)
+    (_b = rewardAd.offError) == null ? void 0 : _b.call(rewardAd, rewardError);
+  rewardClose = null;
+  rewardError = null;
+}
+function useHlwAd() {
+  function clearPopup() {
+    var _a, _b;
+    if (!popupAd)
+      return;
+    if (popupClose)
+      (_a = popupAd.offClose) == null ? void 0 : _a.call(popupAd, popupClose);
+    if (popupError)
+      (_b = popupAd.offError) == null ? void 0 : _b.call(popupAd, popupError);
+    popupClose = null;
+    popupError = null;
+  }
+  function setAdPopup(adId, done) {
+    var _a, _b, _c;
+    popupDone = done;
+    const wxApi = api();
+    if (!adId || !(wxApi == null ? void 0 : wxApi.createInterstitialAd))
+      return false;
+    clearPopup();
+    popupAd = wxApi.createInterstitialAd({ adUnitId: adId });
+    (_a = popupAd.onLoad) == null ? void 0 : _a.call(popupAd, () => {
+    });
+    popupError = (err) => {
+      console.error("插屏广告加载失败", err);
+      popupDone == null ? void 0 : popupDone(false);
+    };
+    popupClose = () => {
+      popupDone == null ? void 0 : popupDone(true);
+    };
+    (_b = popupAd.onError) == null ? void 0 : _b.call(popupAd, popupError);
+    (_c = popupAd.onClose) == null ? void 0 : _c.call(popupAd, popupClose);
+    return true;
+  }
+  function showAdPopup(delay = 3e3) {
+    return new Promise((resolve) => {
+      if (!popupAd) {
+        resolve(false);
+        return;
+      }
+      const done = popupDone;
+      popupDone = (ok) => {
+        done == null ? void 0 : done(ok);
+        resolve(ok);
+      };
+      setTimeout(() => {
+        popupAd.show().catch((err) => {
+          console.error("插屏广告显示失败", err);
+          popupDone == null ? void 0 : popupDone(false);
+        });
+      }, Math.max(0, delay));
+    });
+  }
+  function setAdReward(adId, done) {
+    var _a, _b, _c;
+    rewardDone = done;
+    rewardPromise = new Promise((resolve) => {
+      rewardResolve = resolve;
+    });
+    const wxApi = api();
+    if (!adId || !(wxApi == null ? void 0 : wxApi.createRewardedVideoAd)) {
+      finish({ ok: false });
+      return rewardPromise;
+    }
+    clearReward();
+    rewardAd = wxApi.createRewardedVideoAd({ adUnitId: adId });
+    (_a = rewardAd.onLoad) == null ? void 0 : _a.call(rewardAd, () => {
+    });
+    rewardClose = (res) => {
+      finish({ ok: !!(res == null ? void 0 : res.isEnded), isEnded: !!(res == null ? void 0 : res.isEnded) });
+    };
+    rewardError = (err) => {
+      console.error("激励视频广告加载失败", err);
+      finish({ ok: false, err });
+    };
+    (_b = rewardAd.onClose) == null ? void 0 : _b.call(rewardAd, rewardClose);
+    (_c = rewardAd.onError) == null ? void 0 : _c.call(rewardAd, rewardError);
+    return rewardPromise;
+  }
+  function showAdReward() {
+    if (!rewardAd) {
+      return Promise.resolve({ ok: false });
+    }
+    const current = rewardPromise || new Promise((resolve) => {
+      rewardResolve = resolve;
+    });
+    rewardPromise = current;
+    rewardAd.show().catch(() => {
+      rewardAd.load().then(() => rewardAd.show()).catch((err) => {
+        console.error("激励视频广告显示失败", err);
+        finish({ ok: false, err });
+      });
+    });
+    return current;
+  }
+  return {
+    setAdPopup,
+    showAdPopup,
+    setAdReward,
+    showAdReward
+  };
+}
 function fail(message, options = {}) {
   var _a;
   if (!options.silent) {
@@ -1200,6 +1332,7 @@ export {
   resolveAppearance,
   useApp,
   useDevice,
+  useHlwAd,
   useMsg,
   useNavigate,
   useRefs,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hlw-uni/mp-vue",
-    "version": "2.1.54",
+    "version": "2.1.55",
     "description": "hlw-uni 小程序运行时 — Vue 组件 + composables + theme + http + 工具集（合并自原 mp-core）",
     "main": "dist/index.js",
     "module": "dist/index.mjs",

package/src/components/hlw-ad/index.vue

@@ -81,12 +81,13 @@ function onError(event: any) {
     background: var(--surface-card, #ffffff);
 }
 
-/* 格子广告：默认右下悬浮；微信硬性规则要求 wrapper 透明无圆角，customStyle 可覆盖 */
+/* 格子广告：默认右侧居中悬浮；微信硬性规则要求 wrapper 透明无圆角，customStyle 可覆盖 */
 .hlw-ad--grid {
     position: fixed;
-    right: 20rpx;
-    bottom: 200rpx;
+    top: 50%;
+    right: 0;
     z-index: 99;
+    transform: translateY(-50%);
     border-radius: 0;
     overflow: visible;
     background: transparent;

package/src/composables/ad/README.md

@@ -0,0 +1,58 @@
+# ad 调用文档
+
+`useHlwAd` 封装微信小程序插屏广告和激励视频广告。仅在存在 `wx` 且对应广告 API 可用时生效。
+
+## 引入
+
+```ts
+import { useHlwAd } from "@hlw-uni/mp-vue";
+```
+
+## 插屏广告
+
+```ts
+const ad = useHlwAd();
+
+ad.setAdPopup("adunit-popup-id", (ok) => {
+    console.log("插屏广告关闭", ok);
+});
+
+await ad.showAdPopup(1000);
+```
+
+## 激励视频
+
+```ts
+const ad = useHlwAd();
+
+ad.setAdReward("adunit-reward-id", (res) => {
+    if (res.ok) {
+        // 用户完整看完激励视频
+    }
+});
+
+const result = await ad.showAdReward();
+
+if (result.ok) {
+    // 发放奖励
+}
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `setAdPopup(adId, done?)` | 创建插屏广告实例 |
+| `showAdPopup(delay?)` | 延迟展示插屏广告，默认 3000ms |
+| `setAdReward(adId, done?)` | 创建激励视频实例 |
+| `showAdReward()` | 展示激励视频，失败时会尝试 load 后再 show |
+
+## 类型
+
+```ts
+interface AdRes {
+    ok: boolean;
+    isEnded?: boolean;
+    err?: unknown;
+}
+```

package/src/composables/ad/index.ts

@@ -0,0 +1,153 @@
+/**
+ * 小程序广告工具。
+ */
+
+declare const wx: any;
+
+export interface AdRes {
+    ok: boolean;
+    isEnded?: boolean;
+    err?: unknown;
+}
+
+type AdDone = (res: AdRes) => void;
+
+let popupAd: any = null;
+let popupDone: ((ok: boolean) => void) | undefined;
+let popupClose: (() => void) | null = null;
+let popupError: ((err: unknown) => void) | null = null;
+
+let rewardAd: any = null;
+let rewardDone: AdDone | undefined;
+let rewardPromise: Promise<AdRes> | null = null;
+let rewardResolve: ((res: AdRes) => void) | null = null;
+let rewardClose: ((res: { isEnded?: boolean }) => void) | null = null;
+let rewardError: ((err: unknown) => void) | null = null;
+
+function api() {
+    return typeof wx === "undefined" ? null : wx;
+}
+
+function finish(res: AdRes) {
+    rewardDone?.(res);
+    rewardResolve?.(res);
+    rewardResolve = null;
+    rewardPromise = null;
+}
+
+function clearReward() {
+    if (!rewardAd) return;
+    if (rewardClose) rewardAd.offClose?.(rewardClose);
+    if (rewardError) rewardAd.offError?.(rewardError);
+    rewardClose = null;
+    rewardError = null;
+}
+
+export function useHlwAd() {
+    function clearPopup() {
+        if (!popupAd) return;
+        if (popupClose) popupAd.offClose?.(popupClose);
+        if (popupError) popupAd.offError?.(popupError);
+        popupClose = null;
+        popupError = null;
+    }
+
+    function setAdPopup(adId: string, done?: (ok: boolean) => void): boolean {
+        popupDone = done;
+        const wxApi = api();
+        if (!adId || !wxApi?.createInterstitialAd) return false;
+
+        clearPopup();
+        popupAd = wxApi.createInterstitialAd({ adUnitId: adId });
+        popupAd.onLoad?.(() => {});
+        popupError = (err: unknown) => {
+            console.error("插屏广告加载失败", err);
+            popupDone?.(false);
+        };
+        popupClose = () => {
+            popupDone?.(true);
+        };
+        popupAd.onError?.(popupError);
+        popupAd.onClose?.(popupClose);
+        return true;
+    }
+
+    function showAdPopup(delay = 3000): Promise<boolean> {
+        return new Promise((resolve) => {
+            if (!popupAd) {
+                resolve(false);
+                return;
+            }
+
+            const done = popupDone;
+            popupDone = (ok: boolean) => {
+                done?.(ok);
+                resolve(ok);
+            };
+
+            setTimeout(() => {
+                popupAd.show().catch((err: unknown) => {
+                    console.error("插屏广告显示失败", err);
+                    popupDone?.(false);
+                });
+            }, Math.max(0, delay));
+        });
+    }
+
+
+    function setAdReward(adId: string, done?: AdDone): Promise<AdRes> {
+        rewardDone = done;
+        rewardPromise = new Promise((resolve) => {
+            rewardResolve = resolve;
+        });
+
+        const wxApi = api();
+        if (!adId || !wxApi?.createRewardedVideoAd) {
+            finish({ ok: false });
+            return rewardPromise;
+        }
+
+        clearReward();
+        rewardAd = wxApi.createRewardedVideoAd({ adUnitId: adId });
+        rewardAd.onLoad?.(() => {});
+        rewardClose = (res: { isEnded?: boolean }) => {
+            finish({ ok: !!res?.isEnded, isEnded: !!res?.isEnded });
+        };
+        rewardError = (err: unknown) => {
+            console.error("激励视频广告加载失败", err);
+            finish({ ok: false, err });
+        };
+        rewardAd.onClose?.(rewardClose);
+        rewardAd.onError?.(rewardError);
+        return rewardPromise;
+    }
+
+    function showAdReward(): Promise<AdRes> {
+        if (!rewardAd) {
+            return Promise.resolve({ ok: false });
+        }
+
+        const current = rewardPromise || new Promise<AdRes>((resolve) => {
+            rewardResolve = resolve;
+        });
+        rewardPromise = current;
+
+        rewardAd.show().catch(() => {
+            rewardAd.load()
+                .then(() => rewardAd.show())
+                .catch((err: unknown) => {
+                    console.error("激励视频广告显示失败", err);
+                    finish({ ok: false, err });
+                });
+        });
+
+        return current;
+    }
+
+    return {
+        setAdPopup,
+        showAdPopup,
+        setAdReward,
+        showAdReward,
+    };
+}

package/src/composables/device/README.md

@@ -0,0 +1,50 @@
+# device 调用文档
+
+`useDevice` 采集并缓存设备、窗口、宿主和小程序信息，同时提供常用设备字段组成的 query 字符串。
+
+## 引入
+
+```ts
+import { useDevice, clearDeviceCache } from "@hlw-uni/mp-vue";
+```
+
+## 基础用法
+
+```ts
+const { info, query } = useDevice();
+
+console.log(info.appid);
+console.log(info.device_model);
+console.log(query);
+```
+
+`useDevice` 内部会优先读取 `uni.getDeviceInfo`、`uni.getWindowInfo`、`uni.getAppBaseInfo`，旧环境会回退到 `uni.getSystemInfoSync`。
+
+## 清除缓存
+
+```ts
+clearDeviceCache();
+```
+
+切换账号、切换宿主环境或需要重新采集设备信息时可以手动清理缓存。
+
+## 返回值
+
+| 字段 | 说明 |
+| --- | --- |
+| `info` | 完整 `DeviceInfo` |
+| `query` | 常用设备字段组成的 URL query 字符串 |
+
+## 常用字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `appid` | 小程序 appId |
+| `device_brand` | 设备品牌 |
+| `device_model` | 设备型号 |
+| `device_id` | 设备 ID |
+| `platform` | 平台类型 |
+| `system` | 系统版本 |
+| `sdk_version` | 基础库版本 |
+| `screen_width` | 屏幕宽度 |
+| `screen_height` | 屏幕高度 |

package/src/composables/index.ts

@@ -14,6 +14,7 @@ export {
     useShare,
     type ShareConfig,
 } from "./share";
+export { useHlwAd, type AdRes } from "./ad";
 export { useUtils, type DownloadOpt, type DownloadRes } from "./utils";
 export { useNavigate, type NavigateType, type NavigateOptions } from "./navigator";
 

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

package/src/composables/request/README.md

@@ -0,0 +1,124 @@
+# request 调用文档
+
+`request` 模块封装 `uni.request`、请求拦截器、响应拦截器、错误拦截器、上传和服务类组织方式。
+
+## 引入
+
+```ts
+import {
+    useRequest,
+    useUpload,
+    BaseService,
+    ServiceNamespace,
+    ServicePrefix,
+} from "@hlw-uni/mp-vue";
+```
+
+## useRequest
+
+```ts
+const request = useRequest();
+
+request.setBaseURL("https://api.example.com");
+
+const offRequest = request.onRequest((config) => {
+    config.headers = {
+        ...config.headers,
+        "x-token": uni.getStorageSync("token"),
+    };
+    return config;
+});
+
+const res = await request.get<{ name: string }>("/user/profile");
+
+offRequest();
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `request(config)` | 发起完整配置请求 |
+| `get(url, data?)` | GET 请求 |
+| `post(url, data?)` | POST 请求 |
+| `put(url, data?)` | PUT 请求 |
+| `del(url, data?)` | DELETE 请求 |
+| `setBaseURL(url)` | 设置全局基础地址 |
+| `onRequest(fn)` | 注册请求拦截器，返回取消函数 |
+| `onResponse(fn)` | 注册响应拦截器，返回取消函数 |
+| `onError(fn)` | 注册错误拦截器，返回取消函数 |
+| `upload(config)` | 上传文件 |
+| `resolveServiceUrl(namespace, url, servicePrefix?)` | 生成服务类请求地址 |
+
+## 响应格式
+
+```ts
+interface ApiResponse<T = unknown> {
+    code: number;
+    data: T;
+    info: string;
+}
+```
+
+## useUpload
+
+```ts
+const { uploading, upload } = useUpload();
+
+const result = await upload({
+    type: "local",
+    server: "https://api.example.com/upload",
+    url: "https://api.example.com/upload",
+    filePath: tempFilePath,
+    header: {
+        "x-token": uni.getStorageSync("token"),
+    },
+});
+
+console.log(uploading.value, result.data);
+```
+
+上传类型：
+
+| 类型 | 说明 |
+| --- | --- |
+| `local` | 直接上传到业务接口 |
+| `cos` | 腾讯云 COS 表单上传 |
+| `oss` | 阿里云 OSS 表单上传 |
+| `qiniu` | 七牛云表单上传 |
+| `alist` | Alist 上传 |
+
+## BaseService
+
+```ts
+@ServicePrefix("api")
+@ServiceNamespace("user")
+class UserService extends BaseService {
+    profile() {
+        return this.get<{ nickname: string }>("/profile");
+    }
+
+    update(data: { nickname: string }) {
+        return this.post("/update", data);
+    }
+}
+
+const userService = new UserService();
+const profile = await userService.profile();
+```
+
+上面的 `profile()` 会请求 `/api/user/profile`。如果传入绝对地址，例如 `https://example.com/a`，则不会拼接前缀。
+
+## UploadConfig
+
+```ts
+interface UploadConfig {
+    server: string;
+    filePath: string;
+    fileName?: string;
+    type: string;
+    credentials?: Record<string, string>;
+    header?: Record<string, string>;
+    url?: string;
+}
+```

package/src/composables/request/adapters/oss.ts

@@ -11,6 +11,7 @@ export const ossAdapter: UploadAdapter = {
     buildFormData(ctx) {
         const c = ctx.credentials ?? {};
         return {
+            key: c["key"] ?? ctx.fileName,
             policy: c["policy"] ?? "",
             signature: c["signature"] ?? "",
             OSSAccessKeyId: c["accessKeyId"] ?? "",

package/src/composables/share/README.md

@@ -0,0 +1,53 @@
+# share 调用文档
+
+`useShare` 注册微信小程序分享给好友和分享到朋友圈，并尝试打开分享菜单。
+
+## 引入
+
+```ts
+import { useShare } from "@hlw-uni/mp-vue";
+```
+
+## 基础用法
+
+```ts
+useShare({
+    title: "好用的小程序",
+    path: "/pages/index/index?from=share",
+    imageUrl: "https://example.com/share.png",
+});
+```
+
+## 动态分享内容
+
+```ts
+const share = useShare(() => ({
+    title: detail.value.title,
+    path: `/pages/detail/index?id=${detail.value.id}`,
+    imageUrl: detail.value.cover,
+}));
+
+share.onShareAppMessage({
+    title: "覆盖好友分享标题",
+});
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `onShareAppMessage(config?)` | 注册好友分享 |
+| `onShareTimeline(config?)` | 注册朋友圈分享 |
+| `showShareMenu()` | 主动显示分享菜单 |
+
+同一个 `useShare` 实例中，好友分享和朋友圈分享各只注册一次。
+
+## ShareConfig
+
+```ts
+interface ShareConfig {
+    title?: string;
+    path?: string;
+    imageUrl?: string;
+}
+```

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/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;
+}
+```