@hlw-uni/mp-vue 2.0.0 → 2.0.4

package/dist/app.d.ts

@@ -10,7 +10,7 @@ export interface InterceptorOptions {
     /** Token 来源函数 */
     getToken?: () => string;
     /** 登录失效时的处理函数 */
-    onUnauthorized?: () => void;
+    onLogout?: () => void;
     /** 接口业务错误码是否自动 toast */
     autoToastError?: boolean;
 }
@@ -28,6 +28,6 @@ export declare function useApp(): {
 /**
  * 注册默认请求、响应和错误拦截器。
  */
-export declare function setupDefaultInterceptors(options?: InterceptorOptions & {
+export declare function setupInterceptors(options?: InterceptorOptions & {
     sigSecret?: string;
 }): void;

package/dist/composables/_internal/unwrap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Adapter 返回值解包：兼容业务方传「已解包 T」或「ThinkAdmin envelope { code, data }」。
+ *
+ * 业务方写法：
+ *   setConfigAd({ getConfig: getAdConfig })            // 直接传 envelope-returning 函数
+ *   setConfigAd({ getConfig: async () => myUnwrapped })  // 也支持已解包
+ *
+ * 鸭子类型识别：raw 是对象且有 number 类型的 code 字段 → 当 envelope 处理。
+ */
+export type AdapterPayload<T> = T | null | {
+    code: number;
+    data?: T;
+    info?: string;
+};
+export declare function unwrapPayload<T>(raw: AdapterPayload<T>): T | null;

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

@@ -1,47 +1,6 @@
+import { AdapterPayload } from '../_internal/unwrap';
 import { Ref } from 'vue';
-/**
- * useAd —— 完整的广告业务封装
- *
- * 内置了：
- *   - 6 个 unit_id 配置（store 缓存，调 getConfig 拉一次）
- *   - 激励视频：广告加载 loading → onShown 自动关闭 → 中途关闭挽留 modal → 看完调业务方的 claim 发奖
- *   - 插屏：一行调用
- *   - 底层 SDK 适配（onLoad / offClose / show 兜底 / 实例缓存）
- *
- * 业务侧使用方式：
- *
- *   1. 在 App.vue 注入「全局」回调（拿配置 + 校验登录）：
- *
- *      import { configAd } from "@hlw-uni/mp-vue";
- *      import { getAdConfig } from "@/api/ad";
- *      import { useUserStore } from "@/store";
- *
- *      configAd({
- *          getConfig: async () => {
- *              const res = await getAdConfig();
- *              return res.code === 1 && res.data ? res.data : null;
- *          },
- *          isAuth: () => !!useUserStore().token,
- *      });
- *
- *   2. 任意页面拉配置 / 用 unit_id 渲染：
- *
- *      const { config, loadConfig, showPopup } = useAd();
- *      await loadConfig();
- *      <hlw-ad type="banner" :unit-id="config.banner" />
- *
- *   3. 看广告领奖励（业务方按场景传不同的 claim 接口）：
- *
- *      const ok = await showReward(async () => {
- *          const res = await claimAdReward();
- *          return res.code === 1
- *              ? { ok: true, reward: res.data?.reward }
- *              : { ok: false, msg: res.info };
- *      });
- *
- *      // 不传 claim 就是纯展示，看完即返回 true
- *      const ok = await showReward();
- */
+
 /** 6 种广告类型 */
 export type AdType = "banner" | "grid" | "custom" | "video" | "reward" | "popup";
 /** 广告配置 —— 字段名跟后端表列名对齐（plugin_qz_mp.{type}_unit_id） */
@@ -58,10 +17,18 @@ export interface AdError {
     errCode: number;
     errMsg: string;
 }
-/** 业务回调注入接口 —— configAd 时由项目提供 */
+/**
+ * 业务回调注入接口 —— setConfigAd 时由项目提供。
+ *
+ * getConfig 支持两种返回：
+ *   - 已解包：直接返回 AdConfig 或 null
+ *   - ThinkAdmin envelope：返回 { code, data } 对象，库自动按 code===1 解包
+ *
+ * 业务方可以直接传 envelope-returning 的接口函数引用：
+ *   setConfigAd({ getConfig: getAdConfig })
+ */
 export interface AdAdapter {
-    /** 拉取广告配置；返回 null 表示拉失败，store 不更新 */
-    getConfig: () => Promise<AdConfig | null>;
+    getConfig: () => Promise<AdapterPayload<AdConfig>>;
     /** 是否已登录；不传 = 不校验（showReward 调用前会问一次） */
     isAuth?: () => boolean;
 }
@@ -92,7 +59,7 @@ export type AdClaimFn = (closeRes: AdCloseResult) => Promise<AdClaimResult>;
  * 注入业务回调，应用启动时调用一次。
  * 不调用也不会崩，但 loadConfig / showReward 会无效。
  */
-export declare function configAd(a: AdAdapter): void;
+export declare function setConfigAd(a: AdAdapter): void;
 export declare function useAd(): {
     config: Ref<{
         banner_unit_id: string;

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

@@ -1,4 +1,6 @@
+import { AdapterPayload } from '../_internal/unwrap';
 import { ComputedRef } from 'vue';
+
 /** 后端返回的客服配置（按 button open-type=contact 标准属性命名） */
 export interface ContactConfig {
     send_message_title: string;
@@ -6,10 +8,12 @@ export interface ContactConfig {
     send_message_img: string;
     show_message_card: boolean;
 }
-/** Adapter 注入接口 */
+/**
+ * Adapter 注入接口 —— getConfig 支持「已解包」或「ThinkAdmin envelope」两种返回。
+ * 业务方可以直接传 envelope-returning 接口：setConfigContact({ getConfig: getContactConfig })
+ */
 export interface ContactAdapter {
-    /** 拉取客服配置；返回 null 表示拉失败，store 不更新 */
-    getConfig: () => Promise<ContactConfig | null>;
+    getConfig: () => Promise<AdapterPayload<ContactConfig>>;
 }
 /** v-bind 到 button 的 camelCase props（微信原生属性约定） */
 export interface ContactBindProps {
@@ -21,7 +25,7 @@ export interface ContactBindProps {
 /**
  * 注入业务回调（应用启动时调用一次；不调用则 useContact 始终返回空字段）。
  */
-export declare function configContact(a: ContactAdapter): void;
+export declare function setConfigContact(a: ContactAdapter): void;
 /**
  * 返回 v-bind 友好的客服配置 computed（首次调用会异步拉一次配置）。
  */

package/dist/composables/index.d.ts

@@ -10,9 +10,9 @@ export { usePageMeta } from './page-meta';
 export { useStorage, type StorageInstance } from './storage';
 export { useValidate } from './validate';
 export { useFormat } from './format';
-export { useAd, configAd, destroyAds, confirmReward, type AdType, type AdConfig, type AdError, type AdAdapter, type AdCloseResult, type AdClaimResult, type AdClaimFn, } from './ad';
-export { useShare, useShareConfig, configShare, type ShareConfig, type ShareConfigResolver, type ShareFrom, type ShareAppMessageContent, type ShareTimelineContent, type ShareConfigMap, type ShareConfigAdapter, type PageShareItem, type PageShareFallback, type SharePayload, } from './share';
-export { useContact, configContact, type ContactConfig, type ContactAdapter, type ContactBindProps, } from './contact';
+export { useAd, setConfigAd, destroyAds, confirmReward, type AdType, type AdConfig, type AdError, type AdAdapter, type AdCloseResult, type AdClaimResult, type AdClaimFn, } from './ad';
+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';

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

@@ -1,3 +1,5 @@
+import { AdapterPayload } from '../_internal/unwrap';
+
 export interface ShareAppMessageContent {
     /** 分享标题 */
     title?: string;
@@ -36,10 +38,12 @@ export interface PageShareItem {
 }
 /** 后端返回的页面 key → 配置映射 */
 export type ShareConfigMap = Record<string, PageShareItem>;
-/** Adapter 注入接口 */
+/**
+ * Adapter 注入接口 —— getConfig 支持「已解包」或「ThinkAdmin envelope」两种返回值。
+ * 业务方可以直接传 envelope-returning 接口：setConfigShare({ getConfig: getShareConfig })
+ */
 export interface ShareConfigAdapter {
-    /** 拉取分享配置；返回 null 表示拉失败 */
-    getConfig: () => Promise<ShareConfigMap | null>;
+    getConfig: () => Promise<AdapterPayload<ShareConfigMap>>;
 }
 /** 页面声明的兜底文案 / 跳转路径 */
 export interface PageShareFallback {
@@ -59,7 +63,7 @@ export interface SharePayload {
 /**
  * 注入业务回调（应用启动时调用一次；不调用则始终用 fallback）。
  */
-export declare function configShare(a: ShareConfigAdapter): void;
+export declare function setConfigShare(a: ShareConfigAdapter): void;
 /**
  * 业务级分享配置 helper —— 返回 resolver，可直接喂 onShareAppMessage / onShareTimeline。
  * 后端配置异步加载，加载完成前先用 fallback、加载完后自动切到后端值。

package/dist/index.d.ts

@@ -11,6 +11,6 @@ export * from './composables';
 export type { HlwMenuItem } from './components/hlw-menu/types';
 export type { HlwPagingRef, HlwPagingInstance } from './components/hlw-paging/types';
 export { useThemeStore } from './stores/theme';
-export { useApp, setupDefaultInterceptors } from './app';
+export { useApp, setupInterceptors } from './app';
 export { hlw, type HlwInstance } from './hlw';
 export { vCopy } from './directives';

package/dist/index.js

@@ -619,6 +619,15 @@ var __publicField = (obj, key, value) => {
     }
     return { date, fileSize, phone, money };
   }
+  function unwrapPayload(raw) {
+    if (raw == null)
+      return null;
+    if (typeof raw === "object" && "code" in raw && typeof raw.code === "number") {
+      const env = raw;
+      return env.code === 1 && env.data ? env.data : null;
+    }
+    return raw;
+  }
   const EMPTY = {
     banner_unit_id: "",
     grid_unit_id: "",
@@ -628,7 +637,7 @@ var __publicField = (obj, key, value) => {
     popup_unit_id: ""
   };
   let adapter$1 = null;
-  function configAd(a) {
+  function setConfigAd(a) {
     adapter$1 = a;
   }
   const useAdStore = pinia.defineStore("hlw_ad", () => {
@@ -647,11 +656,11 @@ var __publicField = (obj, key, value) => {
       if (loaded.value && !force)
         return;
       if (!(adapter$1 == null ? void 0 : adapter$1.getConfig)) {
-        console.warn("[useAd] adapter.getConfig 未注入；先调用 configAd()");
+        console.warn("[useAd] adapter.getConfig 未注入；先调用 setConfigAd()");
         return;
       }
       try {
-        const cfg = await adapter$1.getConfig();
+        const cfg = unwrapPayload(await adapter$1.getConfig());
         if (cfg) {
           store.config = cfg;
           store.loaded = true;
@@ -877,7 +886,7 @@ var __publicField = (obj, key, value) => {
   let shareAdapter = null;
   const shareCache = vue.ref(null);
   let sharePending = null;
-  function configShare(a) {
+  function setConfigShare(a) {
     shareAdapter = a;
   }
   function loadShareConfig() {
@@ -886,10 +895,11 @@ var __publicField = (obj, key, value) => {
     if (sharePending)
       return sharePending;
     if (!(shareAdapter == null ? void 0 : shareAdapter.getConfig)) {
-      console.warn("[useShareConfig] adapter.getConfig 未注入；先调用 configShare()");
+      console.warn("[useShareConfig] adapter.getConfig 未注入；先调用 setConfigShare()");
       return Promise.resolve();
     }
-    sharePending = shareAdapter.getConfig().then((cfg) => {
+    sharePending = shareAdapter.getConfig().then((raw) => {
+      const cfg = unwrapPayload(raw);
       if (cfg)
         shareCache.value = cfg;
     }).catch((e) => {
@@ -915,7 +925,7 @@ var __publicField = (obj, key, value) => {
   let adapter = null;
   const config = vue.ref(null);
   let pending = null;
-  function configContact(a) {
+  function setConfigContact(a) {
     adapter = a;
   }
   function loadConfig() {
@@ -924,10 +934,11 @@ var __publicField = (obj, key, value) => {
     if (pending)
       return pending;
     if (!(adapter == null ? void 0 : adapter.getConfig)) {
-      console.warn("[useContact] adapter.getConfig 未注入；先调用 configContact()");
+      console.warn("[useContact] adapter.getConfig 未注入；先调用 setConfigContact()");
       return Promise.resolve();
     }
-    pending = adapter.getConfig().then((cfg) => {
+    pending = adapter.getConfig().then((raw) => {
+      const cfg = unwrapPayload(raw);
       if (cfg)
         config.value = cfg;
     }).catch((e) => {
@@ -1774,7 +1785,7 @@ var __publicField = (obj, key, value) => {
     }
   }
   let _sigSecret = "";
-  function setupDefaultInterceptors(options = {}) {
+  function setupInterceptors(options = {}) {
     const opts = { ..._defaultOpts, ...options };
     if (opts.sigSecret)
       _sigSecret = opts.sigSecret;
@@ -1835,7 +1846,7 @@ var __publicField = (obj, key, value) => {
     const offError = http.onError((err) => {
       var _a;
       if (err.message.includes("401")) {
-        (_a = opts.onUnauthorized) == null ? void 0 : _a.call(opts);
+        (_a = opts.onLogout) == null ? void 0 : _a.call(opts);
       }
     });
     _interceptorCleanup = [offRequest, offResponse, offError];
@@ -1889,9 +1900,6 @@ var __publicField = (obj, key, value) => {
   exports2.alistAdapter = alistAdapter;
   exports2.buildThemeStyle = buildThemeStyle;
   exports2.clearDeviceCache = clearDeviceCache;
-  exports2.configAd = configAd;
-  exports2.configContact = configContact;
-  exports2.configShare = configShare;
   exports2.confirmReward = confirmReward;
   exports2.cosAdapter = cosAdapter;
   exports2.destroyAds = destroyAds;
@@ -1910,7 +1918,10 @@ var __publicField = (obj, key, value) => {
   exports2.ossAdapter = ossAdapter;
   exports2.qiniuAdapter = qiniuAdapter;
   exports2.resolveAppearance = resolveAppearance;
-  exports2.setupDefaultInterceptors = setupDefaultInterceptors;
+  exports2.setConfigAd = setConfigAd;
+  exports2.setConfigContact = setConfigContact;
+  exports2.setConfigShare = setConfigShare;
+  exports2.setupInterceptors = setupInterceptors;
   exports2.useAd = useAd;
   exports2.useApp = useApp;
   exports2.useColor = useColor;

package/dist/index.mjs

@@ -618,6 +618,15 @@ function useFormat() {
   }
   return { date, fileSize, phone, money };
 }
+function unwrapPayload(raw) {
+  if (raw == null)
+    return null;
+  if (typeof raw === "object" && "code" in raw && typeof raw.code === "number") {
+    const env = raw;
+    return env.code === 1 && env.data ? env.data : null;
+  }
+  return raw;
+}
 const EMPTY = {
   banner_unit_id: "",
   grid_unit_id: "",
@@ -627,7 +636,7 @@ const EMPTY = {
   popup_unit_id: ""
 };
 let adapter$1 = null;
-function configAd(a) {
+function setConfigAd(a) {
   adapter$1 = a;
 }
 const useAdStore = defineStore("hlw_ad", () => {
@@ -646,11 +655,11 @@ function useAd() {
     if (loaded.value && !force)
       return;
     if (!(adapter$1 == null ? void 0 : adapter$1.getConfig)) {
-      console.warn("[useAd] adapter.getConfig 未注入；先调用 configAd()");
+      console.warn("[useAd] adapter.getConfig 未注入；先调用 setConfigAd()");
       return;
     }
     try {
-      const cfg = await adapter$1.getConfig();
+      const cfg = unwrapPayload(await adapter$1.getConfig());
       if (cfg) {
         store.config = cfg;
         store.loaded = true;
@@ -876,7 +885,7 @@ function useShare(config2) {
 let shareAdapter = null;
 const shareCache = ref(null);
 let sharePending = null;
-function configShare(a) {
+function setConfigShare(a) {
   shareAdapter = a;
 }
 function loadShareConfig() {
@@ -885,10 +894,11 @@ function loadShareConfig() {
   if (sharePending)
     return sharePending;
   if (!(shareAdapter == null ? void 0 : shareAdapter.getConfig)) {
-    console.warn("[useShareConfig] adapter.getConfig 未注入；先调用 configShare()");
+    console.warn("[useShareConfig] adapter.getConfig 未注入；先调用 setConfigShare()");
     return Promise.resolve();
   }
-  sharePending = shareAdapter.getConfig().then((cfg) => {
+  sharePending = shareAdapter.getConfig().then((raw) => {
+    const cfg = unwrapPayload(raw);
     if (cfg)
       shareCache.value = cfg;
   }).catch((e) => {
@@ -914,7 +924,7 @@ function useShareConfig(pageKey, fallback) {
 let adapter = null;
 const config = ref(null);
 let pending = null;
-function configContact(a) {
+function setConfigContact(a) {
   adapter = a;
 }
 function loadConfig() {
@@ -923,10 +933,11 @@ function loadConfig() {
   if (pending)
     return pending;
   if (!(adapter == null ? void 0 : adapter.getConfig)) {
-    console.warn("[useContact] adapter.getConfig 未注入；先调用 configContact()");
+    console.warn("[useContact] adapter.getConfig 未注入；先调用 setConfigContact()");
     return Promise.resolve();
   }
-  pending = adapter.getConfig().then((cfg) => {
+  pending = adapter.getConfig().then((raw) => {
+    const cfg = unwrapPayload(raw);
     if (cfg)
       config.value = cfg;
   }).catch((e) => {
@@ -1773,7 +1784,7 @@ function buildSignString(url) {
   }
 }
 let _sigSecret = "";
-function setupDefaultInterceptors(options = {}) {
+function setupInterceptors(options = {}) {
   const opts = { ..._defaultOpts, ...options };
   if (opts.sigSecret)
     _sigSecret = opts.sigSecret;
@@ -1834,7 +1845,7 @@ function setupDefaultInterceptors(options = {}) {
   const offError = http.onError((err) => {
     var _a;
     if (err.message.includes("401")) {
-      (_a = opts.onUnauthorized) == null ? void 0 : _a.call(opts);
+      (_a = opts.onLogout) == null ? void 0 : _a.call(opts);
     }
   });
   _interceptorCleanup = [offRequest, offResponse, offError];
@@ -1889,9 +1900,6 @@ export {
   alistAdapter,
   buildThemeStyle,
   clearDeviceCache,
-  configAd,
-  configContact,
-  configShare,
   confirmReward,
   cosAdapter,
   destroyAds,
@@ -1910,7 +1918,10 @@ export {
   ossAdapter,
   qiniuAdapter,
   resolveAppearance,
-  setupDefaultInterceptors,
+  setConfigAd,
+  setConfigContact,
+  setConfigShare,
+  setupInterceptors,
   useAd,
   useApp,
   useColor,

package/package.json

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

package/src/app.ts

@@ -20,7 +20,7 @@ export interface InterceptorOptions {
     /** Token 来源函数 */
     getToken?: () => string;
     /** 登录失效时的处理函数 */
-    onUnauthorized?: () => void;
+    onLogout?: () => void;
     /** 接口业务错误码是否自动 toast */
     autoToastError?: boolean;
 }
@@ -90,7 +90,7 @@ let _sigSecret = '';
 /**
  * 注册默认请求、响应和错误拦截器。
  */
-export function setupDefaultInterceptors(options: InterceptorOptions & { sigSecret?: string } = {}) {
+export function setupInterceptors(options: InterceptorOptions & { sigSecret?: string } = {}) {
     const opts = { ..._defaultOpts, ...options };
     if (opts.sigSecret) _sigSecret = opts.sigSecret;
     if (opts.baseURL) http.setBaseURL(opts.baseURL);
@@ -165,7 +165,7 @@ export function setupDefaultInterceptors(options: InterceptorOptions & { sigSecr
      */
     const offError = http.onError((err: Error) => {
         if (err.message.includes('401')) {
-            opts.onUnauthorized?.();
+            opts.onLogout?.();
         }
     });
 

package/src/composables/_internal/unwrap.ts

@@ -0,0 +1,19 @@
+/**
+ * Adapter 返回值解包：兼容业务方传「已解包 T」或「ThinkAdmin envelope { code, data }」。
+ *
+ * 业务方写法：
+ *   setConfigAd({ getConfig: getAdConfig })            // 直接传 envelope-returning 函数
+ *   setConfigAd({ getConfig: async () => myUnwrapped })  // 也支持已解包
+ *
+ * 鸭子类型识别：raw 是对象且有 number 类型的 code 字段 → 当 envelope 处理。
+ */
+export type AdapterPayload<T> = T | null | { code: number; data?: T; info?: string };
+
+export function unwrapPayload<T>(raw: AdapterPayload<T>): T | null {
+    if (raw == null) return null;
+    if (typeof raw === "object" && "code" in raw && typeof (raw as { code: unknown }).code === "number") {
+        const env = raw as { code: number; data?: T };
+        return env.code === 1 && env.data ? env.data : null;
+    }
+    return raw as T;
+}

package/src/composables/ad/index.ts

@@ -11,11 +11,11 @@
  *
  *   1. 在 App.vue 注入「全局」回调（拿配置 + 校验登录）：
  *
- *      import { configAd } from "@hlw-uni/mp-vue";
+ *      import { setConfigAd } from "@hlw-uni/mp-vue";
  *      import { getAdConfig } from "@/api/ad";
  *      import { useUserStore } from "@/store";
  *
- *      configAd({
+ *      setConfigAd({
  *          getConfig: async () => {
  *              const res = await getAdConfig();
  *              return res.code === 1 && res.data ? res.data : null;
@@ -45,6 +45,7 @@
 import { defineStore, storeToRefs } from "pinia";
 import { ref } from "vue";
 import { useMsg, type HlwMsg } from "../msg";
+import { unwrapPayload, type AdapterPayload } from "../_internal/unwrap";
 
 /** 6 种广告类型 */
 export type AdType = "banner" | "grid" | "custom" | "video" | "reward" | "popup";
@@ -65,10 +66,18 @@ export interface AdError {
     errMsg: string;
 }
 
-/** 业务回调注入接口 —— configAd 时由项目提供 */
+/**
+ * 业务回调注入接口 —— setConfigAd 时由项目提供。
+ *
+ * getConfig 支持两种返回：
+ *   - 已解包：直接返回 AdConfig 或 null
+ *   - ThinkAdmin envelope：返回 { code, data } 对象，库自动按 code===1 解包
+ *
+ * 业务方可以直接传 envelope-returning 的接口函数引用：
+ *   setConfigAd({ getConfig: getAdConfig })
+ */
 export interface AdAdapter {
-    /** 拉取广告配置；返回 null 表示拉失败，store 不更新 */
-    getConfig: () => Promise<AdConfig | null>;
+    getConfig: () => Promise<AdapterPayload<AdConfig>>;
     /** 是否已登录；不传 = 不校验（showReward 调用前会问一次） */
     isAuth?: () => boolean;
 }
@@ -114,7 +123,7 @@ let adapter: AdAdapter | null = null;
  * 注入业务回调，应用启动时调用一次。
  * 不调用也不会崩，但 loadConfig / showReward 会无效。
  */
-export function configAd(a: AdAdapter): void {
+export function setConfigAd(a: AdAdapter): void {
     adapter = a;
 }
 
@@ -151,11 +160,11 @@ export function useAd() {
     async function loadConfig(force = false): Promise<void> {
         if (loaded.value && !force) return;
         if (!adapter?.getConfig) {
-            console.warn("[useAd] adapter.getConfig 未注入；先调用 configAd()");
+            console.warn("[useAd] adapter.getConfig 未注入；先调用 setConfigAd()");
             return;
         }
         try {
-            const cfg = await adapter.getConfig();
+            const cfg = unwrapPayload(await adapter.getConfig());
             if (cfg) {
                 store.config = cfg;
                 store.loaded = true;

package/src/composables/contact/index.ts

@@ -7,7 +7,7 @@
  *
  *   1. App.vue / bootstrap 注入回调：
  *
- *      configContact({
+ *      setConfigContact({
  *          getConfig: async () => {
  *              const res = await getContactConfig();
  *              return res.code === 1 ? res.data : null;
@@ -20,6 +20,7 @@
  *      <hlw-button open-type="contact" v-bind="contact">联系客服</hlw-button>
  */
 import { computed, ref } from "vue";
+import { unwrapPayload, type AdapterPayload } from "../_internal/unwrap";
 
 /** 后端返回的客服配置（按 button open-type=contact 标准属性命名） */
 export interface ContactConfig {
@@ -29,10 +30,12 @@ export interface ContactConfig {
     show_message_card: boolean;
 }
 
-/** Adapter 注入接口 */
+/**
+ * Adapter 注入接口 —— getConfig 支持「已解包」或「ThinkAdmin envelope」两种返回。
+ * 业务方可以直接传 envelope-returning 接口：setConfigContact({ getConfig: getContactConfig })
+ */
 export interface ContactAdapter {
-    /** 拉取客服配置；返回 null 表示拉失败，store 不更新 */
-    getConfig: () => Promise<ContactConfig | null>;
+    getConfig: () => Promise<AdapterPayload<ContactConfig>>;
 }
 
 /** v-bind 到 button 的 camelCase props（微信原生属性约定） */
@@ -50,7 +53,7 @@ let pending: Promise<void> | null = null;
 /**
  * 注入业务回调（应用启动时调用一次；不调用则 useContact 始终返回空字段）。
  */
-export function configContact(a: ContactAdapter): void {
+export function setConfigContact(a: ContactAdapter): void {
     adapter = a;
 }
 
@@ -58,11 +61,12 @@ function loadConfig(): Promise<void> {
     if (config.value) return Promise.resolve();
     if (pending) return pending;
     if (!adapter?.getConfig) {
-        console.warn("[useContact] adapter.getConfig 未注入；先调用 configContact()");
+        console.warn("[useContact] adapter.getConfig 未注入；先调用 setConfigContact()");
         return Promise.resolve();
     }
     pending = adapter.getConfig()
-        .then((cfg) => {
+        .then((raw) => {
+            const cfg = unwrapPayload(raw);
             if (cfg) config.value = cfg;
         })
         .catch((e) => {

package/src/composables/index.ts

@@ -12,7 +12,7 @@ export { useValidate } from "./validate";
 export { useFormat } from "./format";
 export {
     useAd,
-    configAd,
+    setConfigAd,
     destroyAds,
     confirmReward,
     type AdType,
@@ -26,7 +26,7 @@ export {
 export {
     useShare,
     useShareConfig,
-    configShare,
+    setConfigShare,
     type ShareConfig,
     type ShareConfigResolver,
     type ShareFrom,
@@ -40,7 +40,7 @@ export {
 } from "./share";
 export {
     useContact,
-    configContact,
+    setConfigContact,
     type ContactConfig,
     type ContactAdapter,
     type ContactBindProps,

package/src/composables/share/index.ts

@@ -7,6 +7,7 @@
  */
 import { onShareAppMessage, onShareTimeline } from '@dcloudio/uni-app';
 import { ref } from 'vue';
+import { unwrapPayload, type AdapterPayload } from '../_internal/unwrap';
 
 export interface ShareAppMessageContent {
     /** 分享标题 */
@@ -88,7 +89,7 @@ export function useShare(config: ShareConfig | ShareConfigResolver) {
  *
  *   1. App.vue / bootstrap 注入回调：
  *
- *      configShare({
+ *      setConfigShare({
  *          getConfig: async () => {
  *              const res = await getShareConfig();
  *              return res.code === 1 ? res.data : null;
@@ -114,10 +115,12 @@ export interface PageShareItem {
 /** 后端返回的页面 key → 配置映射 */
 export type ShareConfigMap = Record<string, PageShareItem>;
 
-/** Adapter 注入接口 */
+/**
+ * Adapter 注入接口 —— getConfig 支持「已解包」或「ThinkAdmin envelope」两种返回值。
+ * 业务方可以直接传 envelope-returning 接口：setConfigShare({ getConfig: getShareConfig })
+ */
 export interface ShareConfigAdapter {
-    /** 拉取分享配置；返回 null 表示拉失败 */
-    getConfig: () => Promise<ShareConfigMap | null>;
+    getConfig: () => Promise<AdapterPayload<ShareConfigMap>>;
 }
 
 /** 页面声明的兜底文案 / 跳转路径 */
@@ -144,7 +147,7 @@ let sharePending: Promise<void> | null = null;
 /**
  * 注入业务回调（应用启动时调用一次；不调用则始终用 fallback）。
  */
-export function configShare(a: ShareConfigAdapter): void {
+export function setConfigShare(a: ShareConfigAdapter): void {
     shareAdapter = a;
 }
 
@@ -152,11 +155,12 @@ function loadShareConfig(): Promise<void> {
     if (shareCache.value) return Promise.resolve();
     if (sharePending) return sharePending;
     if (!shareAdapter?.getConfig) {
-        console.warn("[useShareConfig] adapter.getConfig 未注入；先调用 configShare()");
+        console.warn("[useShareConfig] adapter.getConfig 未注入；先调用 setConfigShare()");
         return Promise.resolve();
     }
     sharePending = shareAdapter.getConfig()
-        .then((cfg) => {
+        .then((raw) => {
+            const cfg = unwrapPayload(raw);
             if (cfg) shareCache.value = cfg;
         })
         .catch((e) => {

package/src/index.ts

@@ -19,7 +19,7 @@ export type { HlwPagingRef, HlwPagingInstance } from "./components/hlw-paging/ty
 export { useThemeStore } from "./stores/theme";
 
 // App 根上下文
-export { useApp, setupDefaultInterceptors } from "./app";
+export { useApp, setupInterceptors } from "./app";
 
 // hlw 全局命名空间
 export { hlw, type HlwInstance } from "./hlw";