mp-weixin-back 0.0.11 → 0.0.13

package/client.d.ts

@@ -1,6 +1,10 @@
 declare module 'mp-weixin-back-helper' {
   type Config = {
-   /**
+    /**
+     * 初始化时是否监听手势返回，默认值为`true`
+     */
+    initialValue: boolean
+    /**
      * 是否阻止默认的回退事件，默认为 false
      */
     preventDefault: boolean
@@ -10,10 +14,19 @@ declare module 'mp-weixin-back-helper' {
     frequency: number
   }
 
-  function onPageBack(
-    callback:() => void,
-    params: Partial<Config>
-  )
+  function onPageBack(callback: () => void, params?: Partial<Config>)
+
+  /**
+   * 开启监听手势滑动事件
+   */
+  function activeMpBack()
+
+  /**
+   * 禁用监听手势滑动事件
+   */
+  function inactiveMpBack()
 
   export default onPageBack
-}
+
+  export { activeMpBack, inactiveMpBack }
+}

package/dist/index.cjs

@@ -33,16 +33,33 @@ function compositionWalk(context, code, sfc, id) {
     pageBackFnName: "onPageBack",
     hasImportRef: false,
     backConfig: { ...context.config },
-    callbackCode: ""
+    onPageBackBodyAst: [],
+    onPageBackCallNodeToRemove: null,
+    activeFnName: "activeMpBack",
+    inActiveFnName: "inactiveMpBack"
   };
+  const activeFnCallsToModify = [];
+  const inActiveFnCallsToModify = [];
   if (setupAst) {
     astKit.walkAST(setupAst, {
       enter(node) {
         if (node.type === "ImportDeclaration") {
           if (node.source.value.includes(virtualFileId)) {
-            const importSpecifier = node.specifiers[0];
+            const importDefaultSpecifiers = node.specifiers.filter(
+              (i) => i.type === "ImportDefaultSpecifier"
+            );
+            const importDefaultSpecifier = importDefaultSpecifiers[0];
             pageInfo.hasPageBack = true;
-            pageInfo.pageBackFnName = importSpecifier.local.name;
+            pageInfo.pageBackFnName = importDefaultSpecifier.local.name;
+            const importSpecifiers = node.specifiers.filter((i) => i.type === "ImportSpecifier");
+            importSpecifiers.map((specifiers) => {
+              if (specifiers.imported.type === "Identifier" && specifiers.imported.name === "activeMpBack") {
+                pageInfo.activeFnName = specifiers.local.name;
+              }
+              if (specifiers.imported.type === "Identifier" && specifiers.imported.name === "inactiveMpBack") {
+                pageInfo.inActiveFnName = specifiers.local.name;
+              }
+            });
           }
           if (node.source.value === "vue") {
             node.specifiers.some((specifier) => {
@@ -55,6 +72,7 @@ function compositionWalk(context, code, sfc, id) {
           }
         }
         if (node.type === "ExpressionStatement" && node.expression.type === "CallExpression" && node.expression.callee.loc?.identifierName === pageInfo.pageBackFnName) {
+          pageInfo.onPageBackCallNodeToRemove = node;
           const callback = node.expression.arguments[0];
           const backArguments = node.expression.arguments[1];
           if (backArguments?.type === "ObjectExpression") {
@@ -65,30 +83,77 @@ function compositionWalk(context, code, sfc, id) {
             Object.assign(pageInfo.backConfig, config);
           }
           if (callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression")) {
-            const body = callback.body;
-            if (body.type === "BlockStatement") {
-              pageInfo.callbackCode += body.body.map(
-                // @ts-ignore
-                (statement) => (generate__default.default ? generate__default.default : generate__default)(statement).code
-              ).join("");
-            }
+            pageInfo.onPageBackBodyAst = callback.body.body;
           }
+          return;
+        }
+        if (node.type === "ExpressionStatement" && node.expression.type === "CallExpression" && node.expression.callee.loc?.identifierName === pageInfo.activeFnName) {
+          activeFnCallsToModify.push({
+            start: node.expression.start,
+            end: node.expression.end,
+            original: sfc.scriptSetup.loc.source.substring(
+              node.expression.start,
+              node.expression.end
+            ),
+            name: pageInfo.activeFnName
+          });
+        }
+        if (node.type === "ExpressionStatement" && node.expression.type === "CallExpression" && node.expression.callee.loc?.identifierName === pageInfo.inActiveFnName) {
+          inActiveFnCallsToModify.push({
+            start: node.expression.start,
+            end: node.expression.end,
+            original: sfc.scriptSetup.loc.source.substring(
+              node.expression.start,
+              node.expression.end
+            ),
+            name: pageInfo.inActiveFnName
+          });
         }
       }
     });
   }
   if (!pageInfo.hasPageBack)
     return code;
+  if (pageInfo.onPageBackCallNodeToRemove) {
+    const scriptSetupOffset = sfc.scriptSetup.loc.start.offset;
+    const nodeToRemove = pageInfo.onPageBackCallNodeToRemove;
+    const globalStart = scriptSetupOffset + nodeToRemove.start;
+    const globalEnd = scriptSetupOffset + nodeToRemove.end;
+    codeMs.remove(globalStart, globalEnd);
+  }
+  let callbackCode = "";
+  if (pageInfo.onPageBackBodyAst.length > 0) {
+    const tempAstRoot = {
+      type: "BlockStatement",
+      body: pageInfo.onPageBackBodyAst
+    };
+    astKit.walkAST(tempAstRoot, {
+      enter(node) {
+        if (node.type === "CallExpression" && node.callee.type === "Identifier") {
+          const createIdentifier = (name) => ({ type: "Identifier", name });
+          if (node.callee.name === pageInfo.activeFnName) {
+            node.arguments.unshift(createIdentifier("__MP_WEIXIN_ACTIVEBACK__"));
+          } else if (node.callee.name === pageInfo.inActiveFnName) {
+            node.arguments.unshift(createIdentifier("__MP_WEIXIN_INACTIVEBACK__"));
+          }
+        }
+      }
+    });
+    callbackCode = pageInfo.onPageBackBodyAst.map((statement) => (generate__default.default ? generate__default.default : generate__default)(statement).code).join("\n");
+  }
   if (code.includes("<page-container")) {
     context.log.debugLog(`${context.getPageById(id)}\u9875\u9762\u5DF2\u6709page-container\u7EC4\u4EF6\uFF0C\u6CE8\u5165\u5931\u8D25`);
     return code;
   }
   if (!pageInfo.backConfig.preventDefault) {
-    pageInfo.callbackCode += "uni.navigateBack({ delta: 1 });";
+    callbackCode += "uni.navigateBack({ delta: 1 });";
   }
+  const importUseMpWeixinBack = `import { useMpWeixinBack } from '${virtualFileId}'`;
   const importRefFromVue = !pageInfo.hasImportRef ? `import { ref } from 'vue'` : "";
   const stateFrequency = "let __MP_BACK_FREQUENCY__ = 1;";
-  const statePageContainerVar = "const __MP_BACK_SHOW_PAGE_CONTAINER__ = ref(true);";
+  const statePageContainerVar = `
+    const { __MP_BACK_SHOW_PAGE_CONTAINER__, __MP_WEIXIN_ACTIVEBACK__, __MP_WEIXIN_INACTIVEBACK__ } = useMpWeixinBack(${pageInfo.backConfig.initialValue})
+  `;
   const configBack = (() => {
     const onPageBack = pageInfo.backConfig.onPageBack;
     if (!onPageBack)
@@ -104,13 +169,16 @@ function compositionWalk(context, code, sfc, id) {
   })();
   const stateBeforeLeave = `
     const onBeforeLeave = () => {
+      if (!__MP_BACK_SHOW_PAGE_CONTAINER__.value) {
+        return
+      }
       if (__MP_BACK_FREQUENCY__ < ${pageInfo.backConfig.frequency}) {
         __MP_BACK_SHOW_PAGE_CONTAINER__.value = false
         setTimeout(() => __MP_BACK_SHOW_PAGE_CONTAINER__.value = true, 0);
         __MP_BACK_FREQUENCY__++
       }
       ${configBack}
-      ${pageInfo.callbackCode}
+      ${callbackCode}
     };
   `;
   const { template, scriptSetup } = sfc;
@@ -130,10 +198,31 @@ function compositionWalk(context, code, sfc, id) {
   const scriptMagicString = new MagicString__default(scriptOffsets.content);
   scriptMagicString.prepend(
     ` ${importRefFromVue}
+      ${importUseMpWeixinBack}
       ${stateFrequency}
       ${statePageContainerVar}
       ${stateBeforeLeave} `
   );
+  activeFnCallsToModify.forEach((call) => {
+    const fnCallRegex = new RegExp(`${call.name}\\(([^)]*)\\)`, "g");
+    const newCall = call.original.replace(fnCallRegex, (_match, args) => {
+      if (!args.trim()) {
+        return `${call.name}(__MP_WEIXIN_ACTIVEBACK__)`;
+      }
+      return `${call.name}(__MP_WEIXIN_ACTIVEBACK__, ${args})`;
+    });
+    scriptMagicString.overwrite(call.start, call.end, newCall);
+  });
+  inActiveFnCallsToModify.forEach((call) => {
+    const fnCallRegex = new RegExp(`${call.name}\\(([^)]*)\\)`, "g");
+    const newCall = call.original.replace(fnCallRegex, (_match, args) => {
+      if (!args.trim()) {
+        return `${call.name}(__MP_WEIXIN_INACTIVEBACK__)`;
+      }
+      return `${call.name}(__MP_WEIXIN_INACTIVEBACK__, ${args})`;
+    });
+    scriptMagicString.overwrite(call.start, call.end, newCall);
+  });
   codeMs.overwrite(scriptOffsets.start, scriptOffsets.end, scriptMagicString.toString());
   return codeMs.toString();
 }
@@ -413,6 +502,7 @@ class pageContext {
 function MpBackPlugin(userOptions = {}) {
   let context;
   const defaultOptions = {
+    initialValue: true,
     preventDefault: false,
     frequency: 1,
     debug: false
@@ -437,7 +527,33 @@ function MpBackPlugin(userOptions = {}) {
         return;
       }
       if (id === virtualFileId) {
-        return `export default function onPageBack() {}`;
+        return `
+          import { ref } from 'vue'
+          export default function onPageBack() {}
+          export function activeMpBack(fn = null) {
+            fn?.()
+          }
+          export function inactiveMpBack(fn = null) {
+            fn?.()
+          }
+          export function useMpWeixinBack(initialValue = true) {
+            const __MP_BACK_SHOW_PAGE_CONTAINER__ = ref(initialValue)
+
+            const __MP_WEIXIN_ACTIVEBACK__ = () => {
+              __MP_BACK_SHOW_PAGE_CONTAINER__.value = true
+            }
+
+            const __MP_WEIXIN_INACTIVEBACK__ = () => {
+              __MP_BACK_SHOW_PAGE_CONTAINER__.value = false
+            }
+
+            return {
+              __MP_BACK_SHOW_PAGE_CONTAINER__,
+              __MP_WEIXIN_ACTIVEBACK__,
+              __MP_WEIXIN_INACTIVEBACK__
+            }
+          }
+        `;
       }
     },
     async transform(code, id) {

package/dist/index.d.cts

@@ -2,6 +2,10 @@ import { Plugin } from 'vite';
 
 type UserOptions = Partial<Config>;
 type Config = {
+    /**
+     * 初始化时是否监听手势返回，默认值为`true`
+     */
+    initialValue: boolean;
     /**
      * 是否阻止默认的回退事件，默认为 false
      */

package/dist/index.d.mts

@@ -2,6 +2,10 @@ import { Plugin } from 'vite';
 
 type UserOptions = Partial<Config>;
 type Config = {
+    /**
+     * 初始化时是否监听手势返回，默认值为`true`
+     */
+    initialValue: boolean;
     /**
      * 是否阻止默认的回退事件，默认为 false
      */

package/dist/index.d.ts

@@ -2,6 +2,10 @@ import { Plugin } from 'vite';
 
 type UserOptions = Partial<Config>;
 type Config = {
+    /**
+     * 初始化时是否监听手势返回，默认值为`true`
+     */
+    initialValue: boolean;
     /**
      * 是否阻止默认的回退事件，默认为 false
      */

package/dist/index.mjs

@@ -23,16 +23,33 @@ function compositionWalk(context, code, sfc, id) {
     pageBackFnName: "onPageBack",
     hasImportRef: false,
     backConfig: { ...context.config },
-    callbackCode: ""
+    onPageBackBodyAst: [],
+    onPageBackCallNodeToRemove: null,
+    activeFnName: "activeMpBack",
+    inActiveFnName: "inactiveMpBack"
   };
+  const activeFnCallsToModify = [];
+  const inActiveFnCallsToModify = [];
   if (setupAst) {
     walkAST(setupAst, {
       enter(node) {
         if (node.type === "ImportDeclaration") {
           if (node.source.value.includes(virtualFileId)) {
-            const importSpecifier = node.specifiers[0];
+            const importDefaultSpecifiers = node.specifiers.filter(
+              (i) => i.type === "ImportDefaultSpecifier"
+            );
+            const importDefaultSpecifier = importDefaultSpecifiers[0];
             pageInfo.hasPageBack = true;
-            pageInfo.pageBackFnName = importSpecifier.local.name;
+            pageInfo.pageBackFnName = importDefaultSpecifier.local.name;
+            const importSpecifiers = node.specifiers.filter((i) => i.type === "ImportSpecifier");
+            importSpecifiers.map((specifiers) => {
+              if (specifiers.imported.type === "Identifier" && specifiers.imported.name === "activeMpBack") {
+                pageInfo.activeFnName = specifiers.local.name;
+              }
+              if (specifiers.imported.type === "Identifier" && specifiers.imported.name === "inactiveMpBack") {
+                pageInfo.inActiveFnName = specifiers.local.name;
+              }
+            });
           }
           if (node.source.value === "vue") {
             node.specifiers.some((specifier) => {
@@ -45,6 +62,7 @@ function compositionWalk(context, code, sfc, id) {
           }
         }
         if (node.type === "ExpressionStatement" && node.expression.type === "CallExpression" && node.expression.callee.loc?.identifierName === pageInfo.pageBackFnName) {
+          pageInfo.onPageBackCallNodeToRemove = node;
           const callback = node.expression.arguments[0];
           const backArguments = node.expression.arguments[1];
           if (backArguments?.type === "ObjectExpression") {
@@ -55,30 +73,77 @@ function compositionWalk(context, code, sfc, id) {
             Object.assign(pageInfo.backConfig, config);
           }
           if (callback && (callback.type === "ArrowFunctionExpression" || callback.type === "FunctionExpression")) {
-            const body = callback.body;
-            if (body.type === "BlockStatement") {
-              pageInfo.callbackCode += body.body.map(
-                // @ts-ignore
-                (statement) => (generate.default ? generate.default : generate)(statement).code
-              ).join("");
-            }
+            pageInfo.onPageBackBodyAst = callback.body.body;
           }
+          return;
+        }
+        if (node.type === "ExpressionStatement" && node.expression.type === "CallExpression" && node.expression.callee.loc?.identifierName === pageInfo.activeFnName) {
+          activeFnCallsToModify.push({
+            start: node.expression.start,
+            end: node.expression.end,
+            original: sfc.scriptSetup.loc.source.substring(
+              node.expression.start,
+              node.expression.end
+            ),
+            name: pageInfo.activeFnName
+          });
+        }
+        if (node.type === "ExpressionStatement" && node.expression.type === "CallExpression" && node.expression.callee.loc?.identifierName === pageInfo.inActiveFnName) {
+          inActiveFnCallsToModify.push({
+            start: node.expression.start,
+            end: node.expression.end,
+            original: sfc.scriptSetup.loc.source.substring(
+              node.expression.start,
+              node.expression.end
+            ),
+            name: pageInfo.inActiveFnName
+          });
         }
       }
     });
   }
   if (!pageInfo.hasPageBack)
     return code;
+  if (pageInfo.onPageBackCallNodeToRemove) {
+    const scriptSetupOffset = sfc.scriptSetup.loc.start.offset;
+    const nodeToRemove = pageInfo.onPageBackCallNodeToRemove;
+    const globalStart = scriptSetupOffset + nodeToRemove.start;
+    const globalEnd = scriptSetupOffset + nodeToRemove.end;
+    codeMs.remove(globalStart, globalEnd);
+  }
+  let callbackCode = "";
+  if (pageInfo.onPageBackBodyAst.length > 0) {
+    const tempAstRoot = {
+      type: "BlockStatement",
+      body: pageInfo.onPageBackBodyAst
+    };
+    walkAST(tempAstRoot, {
+      enter(node) {
+        if (node.type === "CallExpression" && node.callee.type === "Identifier") {
+          const createIdentifier = (name) => ({ type: "Identifier", name });
+          if (node.callee.name === pageInfo.activeFnName) {
+            node.arguments.unshift(createIdentifier("__MP_WEIXIN_ACTIVEBACK__"));
+          } else if (node.callee.name === pageInfo.inActiveFnName) {
+            node.arguments.unshift(createIdentifier("__MP_WEIXIN_INACTIVEBACK__"));
+          }
+        }
+      }
+    });
+    callbackCode = pageInfo.onPageBackBodyAst.map((statement) => (generate.default ? generate.default : generate)(statement).code).join("\n");
+  }
   if (code.includes("<page-container")) {
     context.log.debugLog(`${context.getPageById(id)}\u9875\u9762\u5DF2\u6709page-container\u7EC4\u4EF6\uFF0C\u6CE8\u5165\u5931\u8D25`);
     return code;
   }
   if (!pageInfo.backConfig.preventDefault) {
-    pageInfo.callbackCode += "uni.navigateBack({ delta: 1 });";
+    callbackCode += "uni.navigateBack({ delta: 1 });";
   }
+  const importUseMpWeixinBack = `import { useMpWeixinBack } from '${virtualFileId}'`;
   const importRefFromVue = !pageInfo.hasImportRef ? `import { ref } from 'vue'` : "";
   const stateFrequency = "let __MP_BACK_FREQUENCY__ = 1;";
-  const statePageContainerVar = "const __MP_BACK_SHOW_PAGE_CONTAINER__ = ref(true);";
+  const statePageContainerVar = `
+    const { __MP_BACK_SHOW_PAGE_CONTAINER__, __MP_WEIXIN_ACTIVEBACK__, __MP_WEIXIN_INACTIVEBACK__ } = useMpWeixinBack(${pageInfo.backConfig.initialValue})
+  `;
   const configBack = (() => {
     const onPageBack = pageInfo.backConfig.onPageBack;
     if (!onPageBack)
@@ -94,13 +159,16 @@ function compositionWalk(context, code, sfc, id) {
   })();
   const stateBeforeLeave = `
     const onBeforeLeave = () => {
+      if (!__MP_BACK_SHOW_PAGE_CONTAINER__.value) {
+        return
+      }
       if (__MP_BACK_FREQUENCY__ < ${pageInfo.backConfig.frequency}) {
         __MP_BACK_SHOW_PAGE_CONTAINER__.value = false
         setTimeout(() => __MP_BACK_SHOW_PAGE_CONTAINER__.value = true, 0);
         __MP_BACK_FREQUENCY__++
       }
       ${configBack}
-      ${pageInfo.callbackCode}
+      ${callbackCode}
     };
   `;
   const { template, scriptSetup } = sfc;
@@ -120,10 +188,31 @@ function compositionWalk(context, code, sfc, id) {
   const scriptMagicString = new MagicString(scriptOffsets.content);
   scriptMagicString.prepend(
     ` ${importRefFromVue}
+      ${importUseMpWeixinBack}
       ${stateFrequency}
       ${statePageContainerVar}
       ${stateBeforeLeave} `
   );
+  activeFnCallsToModify.forEach((call) => {
+    const fnCallRegex = new RegExp(`${call.name}\\(([^)]*)\\)`, "g");
+    const newCall = call.original.replace(fnCallRegex, (_match, args) => {
+      if (!args.trim()) {
+        return `${call.name}(__MP_WEIXIN_ACTIVEBACK__)`;
+      }
+      return `${call.name}(__MP_WEIXIN_ACTIVEBACK__, ${args})`;
+    });
+    scriptMagicString.overwrite(call.start, call.end, newCall);
+  });
+  inActiveFnCallsToModify.forEach((call) => {
+    const fnCallRegex = new RegExp(`${call.name}\\(([^)]*)\\)`, "g");
+    const newCall = call.original.replace(fnCallRegex, (_match, args) => {
+      if (!args.trim()) {
+        return `${call.name}(__MP_WEIXIN_INACTIVEBACK__)`;
+      }
+      return `${call.name}(__MP_WEIXIN_INACTIVEBACK__, ${args})`;
+    });
+    scriptMagicString.overwrite(call.start, call.end, newCall);
+  });
   codeMs.overwrite(scriptOffsets.start, scriptOffsets.end, scriptMagicString.toString());
   return codeMs.toString();
 }
@@ -403,6 +492,7 @@ class pageContext {
 function MpBackPlugin(userOptions = {}) {
   let context;
   const defaultOptions = {
+    initialValue: true,
     preventDefault: false,
     frequency: 1,
     debug: false
@@ -427,7 +517,33 @@ function MpBackPlugin(userOptions = {}) {
         return;
       }
       if (id === virtualFileId) {
-        return `export default function onPageBack() {}`;
+        return `
+          import { ref } from 'vue'
+          export default function onPageBack() {}
+          export function activeMpBack(fn = null) {
+            fn?.()
+          }
+          export function inactiveMpBack(fn = null) {
+            fn?.()
+          }
+          export function useMpWeixinBack(initialValue = true) {
+            const __MP_BACK_SHOW_PAGE_CONTAINER__ = ref(initialValue)
+
+            const __MP_WEIXIN_ACTIVEBACK__ = () => {
+              __MP_BACK_SHOW_PAGE_CONTAINER__.value = true
+            }
+
+            const __MP_WEIXIN_INACTIVEBACK__ = () => {
+              __MP_BACK_SHOW_PAGE_CONTAINER__.value = false
+            }
+
+            return {
+              __MP_BACK_SHOW_PAGE_CONTAINER__,
+              __MP_WEIXIN_ACTIVEBACK__,
+              __MP_WEIXIN_INACTIVEBACK__
+            }
+          }
+        `;
       }
     },
     async transform(code, id) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mp-weixin-back",
   "type": "module",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "监听微信小程序的手势返回和页面默认导航栏的返回",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/readme.md

@@ -1,82 +1,151 @@
-### 功能描述
+# mp-weixin-back
 
-监听手势返回和页面默认导航栏的返回事件
+## 功能概述
 
-### 在项目中使用
+`mp-weixin-back` 是一个专门用于监听微信小程序`手势返回`、`导航栏返回事件`、`navigateBack`的工具库，提供灵活的配置选项和简洁的 API。
 
-#### 下载
+## 📦 安装
 
-```ts
+```bash
 npm install mp-weixin-back
+# 或
+yarn add mp-weixin-back
 ```
 
-#### 使用
+## ⚙️ Vite 配置
 
-`vite.config.ts` 中配置
+在 `vite.config.ts` 中添加插件：
 
 ```ts
+import { defineConfig } from 'vite'
 import mpBackPlugin from 'mp-weixin-back'
 
 export default defineConfig({
-  plugins: [mpBackPlugin()],
+  plugins: [
+    mpBackPlugin({
+      // 可选配置项
+      preventDefault: false, // 是否阻止默认返回行为，设置成 true 则不会返回上一层
+      frequency: 1, // 阻止次数，需要一直拦截则设置一个很大的值即可，如：9999
+      debug: false, // 调试模式，默认为 false
+      onPageBack: () => {
+        console.log('返回事件触发')
+      }, // 统一钩子，事件触发时执行
+    }),
+  ],
 })
 ```
 
-具体的配置为：
-
-```ts
-type Config = {
-  /**
-   * 是否阻止默认的回退事件，默认为 false
-   */
-  preventDefault: boolean
-  /**
-   * 阻止次数，默认是 `1`
-   */
-  frequency: number
-  /**
-   * 页面回退时触发
-   */
-  onPageBack?: (params: BackParams) => void
-}
-```
+## 🚀 快速开始
 
-在 vue3 中使用
+### 基本使用
 
 ```ts
+<script setup>
 import onPageBack from 'mp-weixin-back-helper'
 
+// 简单监听返回事件
 onPageBack(() => {
-  console.log('触发了手势返回')
+  console.log('检测到返回操作（手势或导航栏返回）')
+  // 在这里添加你的处理逻辑
 })
+</script>
 ```
 
-onPageBack 的类型定义为：
+### 高级配置
 
 ```ts
-type Config = {
-  /**
-   * 是否阻止默认的回退事件，默认为 false
-   */
-  preventDefault: boolean
-  /**
-   * 阻止次数，默认是 `1`
-   */
-  frequency: number
-}
-
-function onPageBack(callback: () => void, params: Partial<Config>)
+// 带配置的监听
+onPageBack(
+  () => {
+    console.log('返回事件被触发')
+    // 自定义处理逻辑
+  },
+  {
+    initialValue: false, // 立即生效，默认值为`true`
+    preventDefault: true, // 阻止默认返回行为
+    frequency: 2, // 阻止次数为2次
+  }
+)
 ```
 
-#### 引入类型
+## 📚 API 文档
+
+### `onPageBack(callback, config?)`
+
+监听页面返回事件
+
+| 参数     | 类型         | 必填 | 说明                     |
+| -------- | ------------ | ---- | ------------------------ |
+| callback | `() => void` | 是   | 返回事件触发时的回调函数 |
+| options  | Object       | 否   | 监听器配置选项           |
+
+#### 配置选项
+
+| 参数           | 类型    | 默认值 | 说明                                            |
+| -------------- | ------- | ------ | ----------------------------------------------- |
+| preventDefault | boolean | false  | 是否阻止默认返回行为（true 时页面不会实际返回） |
+| frequency      | number  | 1      | 阻止次数                                        |
+| initialValue   | boolean | true   | 是否立即启用监听（设为 false 时需手动激活）     |
+
+### 辅助方法
+
+#### `activeMpBack()`
+
+启用返回事件监听（需在`<script setup>`中执行）
+
+#### `inactiveMpBack()`
+
+禁用返回事件监听（需在`<script setup>`中执行）
+
+举例：
 
-在项目目录中的`src/env.d.ts` 或`src/shime-uni.d.ts` 文件中引入
+```html
+<template>
+  <div>
+    <!-- 页面代码 -->
+    <button @click="toggleListener(true)">开启</button>
+    <button @click="toggleListener(false)">禁用</button>
+  </div>
+</template>
 
+<script setup>
+  import onPageBack, { activeMpBack, inactiveMpBack } from 'mp-weixin-back-helper'
+
+  const toggleListener = (enable) => {
+    enable ? activeMpBack() : inactiveMpBack()
+  }
+</script>
 ```
-/// <reference types="mp-weixin-back/client" />
+
+## 🎯 选项式 API 支持（未完善）
+
+组件内直接声明
+
+在 Vue 组件的选项对象中直接定义 onPageBack 方法：
+
+```html
+<template>
+  <div class="container">
+    <div>当前页面内容</div>
+  </div>
+</template>
+
+<script>
+  export default {
+    // 读取 vite 中的配置
+    onPageBack() {
+      console.log('检测到返回操作')
+      // 业务逻辑处理
+    },
+  }
+</script>
 ```
 
-或在 `tsconfig.json` 的 `compilerOptions` 下配置
+## 🛠 类型支持
+
+### 类型声明配置
+
+在 `tsconfig.json` 中添加：
 
 ```json
 {
@@ -86,9 +155,19 @@ function onPageBack(callback: () => void, params: Partial<Config>)
 }
 ```
 
-### todolist
+或通过声明文件引用：
+
+```typescript
+// env.d.ts
+/// <reference types="mp-weixin-back/client" />
+```
+
+## ❓ 常见问题
+
+### Q1: 如何实现多页面独立配置？
+
+每个页面单独调用 `onPageBack` 时传入不同的配置参数即可实现页面级定制。
+
+### Q2: 全局配置与页面配置的优先级？
 
-- [ ] 兼容 uniapp 的 Vue2 项目
-- [ ] debug 模式
-- [ ] 热更新 pages.json 文件
-- [ ] 单元测试
+页面级配置会覆盖全局配置，建议将通用配置放在全局，特殊需求在页面单独设置。

package/shims-vue.d.ts

@@ -0,0 +1,6 @@
+// shims-vue.d.ts
+declare module '*.vue' {
+  import { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, any>
+  export default component
+}

package/src/index.ts

@@ -7,6 +7,7 @@ function MpBackPlugin(userOptions: UserOptions = {}): Plugin {
   let context: pageContext
 
   const defaultOptions: Config = {
+    initialValue: true,
     preventDefault: false,
     frequency: 1,
     debug: false,
@@ -33,7 +34,33 @@ function MpBackPlugin(userOptions: UserOptions = {}): Plugin {
       }
       // 导出一个对象
       if (id === virtualFileId) {
-        return `export default function onPageBack() {}`
+        return `
+          import { ref } from 'vue'
+          export default function onPageBack() {}
+          export function activeMpBack(fn = null) {
+            fn?.()
+          }
+          export function inactiveMpBack(fn = null) {
+            fn?.()
+          }
+          export function useMpWeixinBack(initialValue = true) {
+            const __MP_BACK_SHOW_PAGE_CONTAINER__ = ref(initialValue)
+
+            const __MP_WEIXIN_ACTIVEBACK__ = () => {
+              __MP_BACK_SHOW_PAGE_CONTAINER__.value = true
+            }
+
+            const __MP_WEIXIN_INACTIVEBACK__ = () => {
+              __MP_BACK_SHOW_PAGE_CONTAINER__.value = false
+            }
+
+            return {
+              __MP_BACK_SHOW_PAGE_CONTAINER__,
+              __MP_WEIXIN_ACTIVEBACK__,
+              __MP_WEIXIN_INACTIVEBACK__
+            }
+          }
+        `
       }
     },
     async transform(code, id) {

package/test/data/index-utils.vue

@@ -0,0 +1,29 @@
+<template>
+  <div>我是默认的界面</div>
+  <button id="button" @click="disableMpBack"></button>
+  <button id="button2" @click="activeMpBack"></button>
+</template>
+
+<script setup>
+import onPageBack, { activeMpBack as mpppacitve, inactiveMpBack } from 'mp-weixin-back-helper'
+
+onPageBack(
+  () => {
+    console.log('触发了手势返回')
+  },
+  {
+    initialValue: false,
+  }
+)
+
+const activeMpBack = () => {
+  console.log('执行了activeMpBack')
+  mpppacitve()
+}
+
+const disableMpBack = () => {
+  inactiveMpBack()
+}
+</script>
+
+<style></style>

package/test/generate.spec.ts

@@ -1,31 +1,64 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { mount } from '@vue/test-utils'
-// @ts-ignore
 import IndexSetup from './data/index-setup.vue'
-// @ts-ignore
+import IndexUtils from './data/index-utils.vue'
 import IndexDefault from './data/index-default.vue'
 
 describe('generate page-container components', () => {
-  it('setup compisitionAPI', async () => {
-    const wrapper = mount(IndexSetup)
-    await wrapper.vm.$nextTick()
-
-    const pageContainerRef = wrapper.find('page-container')
-    expect(pageContainerRef.exists()).toBe(true)
-    expect(wrapper.vm.__MP_BACK_SHOW_PAGE_CONTAINER__).toBe(true)
-    expect(wrapper.vm.onBeforeLeave()).toBe(true)
+  let logSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    logSpy.mockRestore()
+  })
+
+  describe('setup compositionAPI', () => {
+    it('default case', async () => {
+      const wrapper = mount(IndexSetup)
+      await wrapper.vm.$nextTick()
+
+      const pageContainerRef = wrapper.find('page-container')
+      expect(pageContainerRef.exists()).toBe(true)
+      expect(wrapper.vm.__MP_BACK_SHOW_PAGE_CONTAINER__).toBe(true)
+      expect(typeof wrapper.vm.onBeforeLeave).toBe('function')
+    })
+
+    it('utils case', async () => {
+      const wrapper = mount(IndexUtils)
+      await wrapper.vm.$nextTick()
+
+      const pageContainerRef = wrapper.find('page-container')
+      expect(pageContainerRef.exists()).toBe(true)
+      expect(wrapper.vm.__MP_BACK_SHOW_PAGE_CONTAINER__).toBe(false)
+      expect(typeof wrapper.vm.onBeforeLeave).toBe('function')
+
+      await wrapper.find('#button2').trigger('click')
+      await new Promise(resolve => setTimeout(resolve, 0))
+
+      expect(logSpy).toHaveBeenCalledWith('执行了activeMpBack')
+
+      expect(wrapper.vm.__MP_BACK_SHOW_PAGE_CONTAINER__).toBe(true)
+
+      await wrapper.find('#button').trigger('click')
+      await new Promise(resolve => setTimeout(resolve, 0))
+
+      expect(wrapper.vm.__MP_BACK_SHOW_PAGE_CONTAINER__).toBe(false)
+    })
   })
 
-  it('default optionsAPI', async () => {
-    const wrapper = mount(IndexDefault)
-    await wrapper.vm.$nextTick()
-    const pageContainerRef = wrapper.find('page-container')
-    expect(pageContainerRef.exists()).toBe(true)
-    // @ts-ignore
-    expect(wrapper.vm.__MP_BACK_SHOW_PAGE_CONTAINER__).toBe(true)
-    // @ts-ignore
-    expect(wrapper.vm.__MP_BACK_FREQUENCY__).toBe(1)
-    // @ts-ignore
-    expect(wrapper.vm.onBeforeLeave()).toBe(true)
+  describe('optionsAPI', () => {
+    it('default case', async () => {
+      const wrapper = mount(IndexDefault)
+      await wrapper.vm.$nextTick()
+
+      const pageContainerRef = wrapper.find('page-container')
+      expect(pageContainerRef.exists()).toBe(true)
+      expect(wrapper.vm.__MP_BACK_SHOW_PAGE_CONTAINER__).toBe(true)
+      expect(wrapper.vm.__MP_BACK_FREQUENCY__).toBe(1)
+      expect(wrapper.vm.onBeforeLeave()).toBe(true)
+    })
   })
 })

package/types/index.ts

@@ -1,6 +1,10 @@
 export type UserOptions = Partial<Config>
 
 export type Config = {
+  /**
+   * 初始化时是否监听手势返回，默认值为`true`
+   */
+  initialValue: boolean
   /**
    * 是否阻止默认的回退事件，默认为 false
    */

package/utils/index.ts

@@ -1,7 +1,6 @@
 import { parse } from '@vue/compiler-sfc'
 import { pageContext } from '../src/context'
 import { vueWalker } from './walker'
-import type { SFCDescriptor } from '@vue/compiler-sfc'
 
 export async function transformVueFile(this: pageContext, code: string, id: string) {
   try {

package/utils/walker.ts

@@ -4,7 +4,9 @@ import { babelParse, walkAST } from 'ast-kit'
 import { pageContext } from '../src/context'
 import { virtualFileId } from './constant'
 import type {
+  WithStatement,
   BlockStatement,
+  Statement,
   FunctionExpression,
   Node,
   ObjectExpression,
@@ -29,17 +31,42 @@ function compositionWalk(context: pageContext, code: string, sfc: any, id: strin
     pageBackFnName: 'onPageBack',
     hasImportRef: false,
     backConfig: { ...context.config },
-    callbackCode: '',
+    onPageBackBodyAst: [] as Statement[],
+    onPageBackCallNodeToRemove: null as Node | null,
+    activeFnName: 'activeMpBack',
+    inActiveFnName: 'inactiveMpBack',
   }
 
+  const activeFnCallsToModify: any[] = []
+  const inActiveFnCallsToModify: any[] = []
+
   if (setupAst) {
     walkAST<Node>(setupAst, {
       enter(node) {
         if (node.type === 'ImportDeclaration') {
           if (node.source.value.includes(virtualFileId)) {
-            const importSpecifier = node.specifiers[0]
+            const importDefaultSpecifiers = node.specifiers.filter(
+              (i) => i.type === 'ImportDefaultSpecifier'
+            )
+            const importDefaultSpecifier = importDefaultSpecifiers[0]
             pageInfo.hasPageBack = true
-            pageInfo.pageBackFnName = importSpecifier.local.name
+            pageInfo.pageBackFnName = importDefaultSpecifier.local.name
+
+            const importSpecifiers = node.specifiers.filter((i) => i.type === 'ImportSpecifier')
+            importSpecifiers.map((specifiers) => {
+              if (
+                specifiers.imported.type === 'Identifier' &&
+                specifiers.imported.name === 'activeMpBack'
+              ) {
+                pageInfo.activeFnName = specifiers.local.name
+              }
+              if (
+                specifiers.imported.type === 'Identifier' &&
+                specifiers.imported.name === 'inactiveMpBack'
+              ) {
+                pageInfo.inActiveFnName = specifiers.local.name
+              }
+            })
           }
           if (node.source.value === 'vue') {
             node.specifiers.some((specifier) => {
@@ -57,6 +84,8 @@ function compositionWalk(context: pageContext, code: string, sfc: any, id: strin
           node.expression.type === 'CallExpression' &&
           node.expression.callee.loc?.identifierName === pageInfo.pageBackFnName
         ) {
+          // 记录下整个 onPageBack(...) 语句节点，以便后续移除
+          pageInfo.onPageBackCallNodeToRemove = node
           const callback = node.expression.arguments[0]
           const backArguments = node.expression.arguments[1]
 
@@ -72,16 +101,43 @@ function compositionWalk(context: pageContext, code: string, sfc: any, id: strin
             callback &&
             (callback.type === 'ArrowFunctionExpression' || callback.type === 'FunctionExpression')
           ) {
-            const body = callback.body
-            if (body.type === 'BlockStatement') {
-              pageInfo.callbackCode += body.body
-                .map(
-                  // @ts-ignore
-                  (statement) => (generate.default ? generate.default : generate)(statement).code
-                )
-                .join('')
-            }
+            pageInfo.onPageBackBodyAst = callback.body.body
           }
+
+          // 跳过此节点的子节点遍历，因为我们将手动处理其内部逻辑
+          return
+        }
+
+        if (
+          node.type === 'ExpressionStatement' &&
+          node.expression.type === 'CallExpression' &&
+          node.expression.callee.loc?.identifierName === pageInfo.activeFnName
+        ) {
+          activeFnCallsToModify.push({
+            start: node.expression.start,
+            end: node.expression.end,
+            original: sfc.scriptSetup!.loc.source.substring(
+              node.expression.start,
+              node.expression.end
+            ),
+            name: pageInfo.activeFnName,
+          })
+        }
+
+        if (
+          node.type === 'ExpressionStatement' &&
+          node.expression.type === 'CallExpression' &&
+          node.expression.callee.loc?.identifierName === pageInfo.inActiveFnName
+        ) {
+          inActiveFnCallsToModify.push({
+            start: node.expression.start,
+            end: node.expression.end,
+            original: sfc.scriptSetup!.loc.source.substring(
+              node.expression.start,
+              node.expression.end
+            ),
+            name: pageInfo.inActiveFnName,
+          })
         }
       },
     })
@@ -90,18 +146,59 @@ function compositionWalk(context: pageContext, code: string, sfc: any, id: strin
   // 没有引入mp-weixin-back-helper
   if (!pageInfo.hasPageBack) return code
 
+  if (pageInfo.onPageBackCallNodeToRemove) {
+    const scriptSetupOffset = sfc.scriptSetup!.loc.start.offset
+    const nodeToRemove = pageInfo.onPageBackCallNodeToRemove as any
+    const globalStart = scriptSetupOffset + nodeToRemove.start
+    const globalEnd = scriptSetupOffset + nodeToRemove.end
+    codeMs.remove(globalStart, globalEnd)
+  }
+
+  let callbackCode = ''
+  if (pageInfo.onPageBackBodyAst.length > 0) {
+    // 包装成一个临时的 AST 根节点以供遍历
+    const tempAstRoot = {
+      type: 'BlockStatement',
+      body: pageInfo.onPageBackBodyAst,
+    } as WithStatement
+
+    walkAST(tempAstRoot, {
+      enter(node: any) {
+        if (node.type === 'CallExpression' && node.callee.type === 'Identifier') {
+          const createIdentifier = (name: string) => ({ type: 'Identifier', name })
+
+          if (node.callee.name === pageInfo.activeFnName) {
+            node.arguments.unshift(createIdentifier('__MP_WEIXIN_ACTIVEBACK__'))
+          } else if (node.callee.name === pageInfo.inActiveFnName) {
+            node.arguments.unshift(createIdentifier('__MP_WEIXIN_INACTIVEBACK__'))
+          }
+        }
+      },
+    })
+
+    callbackCode = pageInfo.onPageBackBodyAst
+      // @ts-ignore
+      .map((statement) => (generate.default ? generate.default : generate)(statement).code)
+      .join('\n')
+  }
+
   if (code.includes('<page-container')) {
     context.log.debugLog(`${context.getPageById(id)}页面已有page-container组件，注入失败`)
     return code
   }
 
   if (!pageInfo.backConfig.preventDefault) {
-    pageInfo.callbackCode += 'uni.navigateBack({ delta: 1 });'
+    callbackCode += 'uni.navigateBack({ delta: 1 });'
   }
 
+  const importUseMpWeixinBack = `import { useMpWeixinBack } from '${virtualFileId}'`
   const importRefFromVue = !pageInfo.hasImportRef ? `import { ref } from 'vue'` : ''
   const stateFrequency = 'let __MP_BACK_FREQUENCY__ = 1;'
-  const statePageContainerVar = 'const __MP_BACK_SHOW_PAGE_CONTAINER__ = ref(true);'
+
+  const statePageContainerVar = `
+    const { __MP_BACK_SHOW_PAGE_CONTAINER__, __MP_WEIXIN_ACTIVEBACK__, __MP_WEIXIN_INACTIVEBACK__ } = useMpWeixinBack(${pageInfo.backConfig.initialValue})
+  `
+
   // 获取传入插件的统一方法
   const configBack = (() => {
     const onPageBack = pageInfo.backConfig.onPageBack
@@ -115,15 +212,19 @@ function compositionWalk(context: pageContext, code: string, sfc: any, id: strin
     }
     return `(function ${onPageBack})()`
   })()
+
   const stateBeforeLeave = `
     const onBeforeLeave = () => {
+      if (!__MP_BACK_SHOW_PAGE_CONTAINER__.value) {
+        return
+      }
       if (__MP_BACK_FREQUENCY__ < ${pageInfo.backConfig.frequency}) {
         __MP_BACK_SHOW_PAGE_CONTAINER__.value = false
         setTimeout(() => __MP_BACK_SHOW_PAGE_CONTAINER__.value = true, 0);
         __MP_BACK_FREQUENCY__++
       }
       ${configBack}
-      ${pageInfo.callbackCode}
+      ${callbackCode}
     };
   `
   const { template, scriptSetup } = sfc
@@ -147,10 +248,43 @@ function compositionWalk(context: pageContext, code: string, sfc: any, id: strin
   const scriptMagicString = new MagicString(scriptOffsets.content)
   scriptMagicString.prepend(
     ` ${importRefFromVue}
+      ${importUseMpWeixinBack}
       ${stateFrequency}
       ${statePageContainerVar}
       ${stateBeforeLeave} `
   )
+
+  // 应用 activeMpBack 调用的修改
+  activeFnCallsToModify.forEach((call) => {
+    // 使用正则匹配函数调用结构，确保我们只修改括号内的内容
+    const fnCallRegex = new RegExp(`${call.name}\\(([^)]*)\\)`, 'g')
+    const newCall = call.original.replace(fnCallRegex, (_match: any, args: string) => {
+      // 如果原调用没有参数
+      if (!args.trim()) {
+        return `${call.name}(__MP_WEIXIN_ACTIVEBACK__)`
+      }
+      // 如果有参数，添加新参数
+      return `${call.name}(__MP_WEIXIN_ACTIVEBACK__, ${args})`
+    })
+
+    scriptMagicString.overwrite(call.start, call.end, newCall)
+  })
+
+  inActiveFnCallsToModify.forEach((call) => {
+    // 使用正则匹配函数调用结构，确保我们只修改括号内的内容
+    const fnCallRegex = new RegExp(`${call.name}\\(([^)]*)\\)`, 'g')
+    const newCall = call.original.replace(fnCallRegex, (_match: any, args: string) => {
+      // 如果原调用没有参数
+      if (!args.trim()) {
+        return `${call.name}(__MP_WEIXIN_INACTIVEBACK__)`
+      }
+      // 如果有参数，添加新参数
+      return `${call.name}(__MP_WEIXIN_INACTIVEBACK__, ${args})`
+    })
+
+    scriptMagicString.overwrite(call.start, call.end, newCall)
+  })
+
   codeMs.overwrite(scriptOffsets.start, scriptOffsets.end, scriptMagicString.toString())
 
   return codeMs.toString()
@@ -284,7 +418,7 @@ function optionsWalk(context: pageContext, code: string, sfc: any, id: string) {
         ],
       },
     }
-      ; (exportDefaultNode as ObjectExpression).properties.push(addData)
+    ;(exportDefaultNode as ObjectExpression).properties.push(addData)
   }
 
   // 获取传入插件的统一方法
@@ -340,7 +474,7 @@ function optionsWalk(context: pageContext, code: string, sfc: any, id: string) {
     },
   } as ObjectMethod
   if (methodsNode) {
-    ; (methodsNode as ObjectExpression).properties.push(newMethodsProperty)
+    ;(methodsNode as ObjectExpression).properties.push(newMethodsProperty)
   } else if (exportDefaultNode) {
     const addMethods: ObjectProperty = {
       type: 'ObjectProperty',
@@ -355,7 +489,7 @@ function optionsWalk(context: pageContext, code: string, sfc: any, id: string) {
         properties: [newMethodsProperty],
       },
     }
-      ; (exportDefaultNode as ObjectExpression).properties.push(addMethods)
+    ;(exportDefaultNode as ObjectExpression).properties.push(addMethods)
   }
 
   const { template, script } = sfc

package/vite.config.ts

@@ -3,7 +3,16 @@ import vue from '@vitejs/plugin-vue'
 import mpBack from './dist/index.mjs'
 
 export default defineConfig({
-  plugins: [mpBack(), vue()],
+  plugins: [
+    mpBack(),
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag.startsWith('page-') || tag.startsWith('mp-'),
+        },
+      },
+    }),
+  ],
   test: {
     environment: 'happy-dom',
   },