mp-weixin-back 0.0.15 → 0.0.17

package/client.d.ts

@@ -1,32 +1,109 @@
 declare module 'mp-weixin-back-helper' {
-  type Config = {
+  /**
+   * Per-page options for `onPageBack()`.
+   */
+  type OnPageBackOptions = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
      */
-    initialValue: boolean
+    preventDefault?: boolean
+
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
      */
-    preventDefault: boolean
+    frequency?: number
+
     /**
-     * 阻止次数，默认是 `1`
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` and call `activeMpBack()` manually to enable later.
+     * @default true
      */
-    frequency: number
+    initialValue?: boolean
   }
 
-  function onPageBack(callback: () => void, params?: Partial<Config>)
+  /**
+   * Listen to back navigation events (gesture back + navbar back button) on the current page.
+   *
+   * Must be called inside `<script setup>` at the top level.
+   *
+   * @param callback - Function to call when back navigation is detected.
+   * @param options - Optional per-page configuration. Overrides global plugin config.
+   *
+   * @example
+   * // Basic usage
+   * import onPageBack from 'mp-weixin-back-helper'
+   *
+   * onPageBack(() => {
+   *   console.log('back detected')
+   * })
+   *
+   * @example
+   * // Prevent back and show a confirmation dialog
+   * import onPageBack from 'mp-weixin-back-helper'
+   *
+   * onPageBack(
+   *   () => {
+   *     uni.showModal({
+   *       title: '提示',
+   *       content: '确定要返回吗？',
+   *       success: (res) => {
+   *         if (res.confirm) uni.navigateBack()
+   *       },
+   *     })
+   *   },
+   *   { preventDefault: true }
+   * )
+   *
+   * @example
+   * // Start disabled, enable after a button click
+   * import onPageBack, { activeMpBack, inactiveMpBack } from 'mp-weixin-back-helper'
+   *
+   * onPageBack(() => { handleBack() }, { initialValue: false })
+   *
+   * function startListening() { activeMpBack() }
+   * function stopListening() { inactiveMpBack() }
+   */
+  function onPageBack(callback: () => void, options?: OnPageBackOptions): void
 
   /**
-   * 开启监听手势滑动事件
+   * Enable the back event listener for the current page.
+   *
+   * Use when `initialValue: false` was passed to `onPageBack()`,
+   * or to re-enable after calling `inactiveMpBack()`.
+   *
+   * Must be called inside `<script setup>`.
+   *
+   * @example
+   * import { activeMpBack } from 'mp-weixin-back-helper'
+   *
+   * // Enable on button click
+   * function handleEnable() {
+   *   activeMpBack()
+   * }
    */
-  function activeMpBack()
+  function activeMpBack(): void
 
   /**
-   * 禁用监听手势滑动事件
+   * Disable the back event listener for the current page.
+   *
+   * The page will resume its default back behavior until `activeMpBack()` is called again.
+   *
+   * Must be called inside `<script setup>`.
+   *
+   * @example
+   * import { inactiveMpBack } from 'mp-weixin-back-helper'
+   *
+   * // Disable when a modal is open
+   * function handleModalOpen() {
+   *   inactiveMpBack()
+   * }
    */
-  function inactiveMpBack()
+  function inactiveMpBack(): void
 
   export default onPageBack
-
   export { activeMpBack, inactiveMpBack }
 }

package/dist/index.cjs

@@ -423,9 +423,10 @@ async function resolveCompiler(root) {
         return await import('@vue/compiler-sfc');
       } catch (secondError) {
         throw new Error(
-          `\u65E0\u6CD5\u89E3\u6790 @vue/compiler-sfc\u3002
-\u6B64\u63D2\u4EF6\u9700\u8981\u9879\u76EE\u4E2D\u5B89\u88C5 @vue/compiler-sfc\u3002
-\u8BF7\u624B\u52A8\u5B89\u88C5\uFF1Apnpm add -D @vue/compiler-sfc
+          `[mp-weixin-back] Cannot resolve @vue/compiler-sfc.
+This plugin requires @vue/compiler-sfc to be installed in your project.
+Fix: pnpm add -D @vue/compiler-sfc
+Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E
 `
         );
       }
@@ -447,7 +448,10 @@ async function transformVueFile(code, id) {
     const walker = scriptSetup ? "compositionWalk" : "optionsWalk";
     return vueWalker[walker](this, code, sfc, id);
   } catch (error) {
-    this.log.error("\u89E3\u6790vue\u6587\u4EF6\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u662F\u5426\u6B63\u786E");
+    this.log.error(
+      `Failed to transform ${id}. Please check the file is a valid Vue SFC.
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#-\u5FEB\u901F\u5F00\u59CB`
+    );
     this.log.error(String(error));
     return code;
   }
@@ -511,7 +515,11 @@ class pageContext {
         }
       }
     } catch (error) {
-      this.log.error("\u8BFB\u53D6pages.json\u6587\u4EF6\u5931\u8D25");
+      this.log.error(
+        `Failed to read pages.json. Make sure src/pages.json exists and is valid JSON/JSON5.
+  Path checked: ${this.getPagesJsonPath()}
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E`
+      );
       this.log.debugLog(String(error));
     }
   }

package/dist/index.d.cts

@@ -1,34 +1,67 @@
 import { Plugin } from 'vite';
 
-type UserOptions = Partial<Config>;
-type Config = {
+/**
+ * Parameters passed to the onPageBack callback.
+ */
+type BackParams = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * The path of the current page that triggered the back event.
+     * @example 'pages/index/index'
      */
-    initialValue: boolean;
+    page: string;
+};
+/**
+ * Per-page options for `onPageBack()`.
+ */
+type OnPageBackOptions = {
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
+     * @example
+     * onPageBack(() => showDialog(), { preventDefault: true })
      */
     preventDefault: boolean;
     /**
-     * 阻止次数，默认是 `1`
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
+     * @example
+     * // Block 3 times, then allow back
+     * onPageBack(() => {}, { frequency: 3 })
      */
     frequency: number;
     /**
-     * 调试模式
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` to start disabled and enable manually via `activeMpBack()`.
+     * @default true
+     * @example
+     * // Start disabled, enable after user action
+     * onPageBack(() => {}, { initialValue: false })
+     * activeMpBack()
      */
-    debug: boolean;
+    initialValue: boolean;
+};
+/**
+ * Global plugin options passed to `mpBackPlugin()` in `vite.config.ts`.
+ */
+type Config = OnPageBackOptions & {
     /**
-     * 页面回退时触发
+     * Enable debug logging in development mode.
+     * @default false
      */
-    onPageBack?: (params: BackParams) => void;
-};
-type BackParams = {
+    debug: boolean;
     /**
-     * 当前页面路径
+     * Global callback fired every time a back event is detected on any page.
+     * Page-level callbacks registered via `onPageBack()` run in addition to this.
+     * @example
+     * mpBackPlugin({
+     *   onPageBack: ({ page }) => console.log('back on:', page)
+     * })
      */
-    page: string;
+    onPageBack?: (params: BackParams) => void;
 };
+type UserOptions = Partial<Config>;
 
 declare function MpBackPlugin(userOptions?: UserOptions): Plugin;
 

package/dist/index.d.mts

@@ -1,34 +1,67 @@
 import { Plugin } from 'vite';
 
-type UserOptions = Partial<Config>;
-type Config = {
+/**
+ * Parameters passed to the onPageBack callback.
+ */
+type BackParams = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * The path of the current page that triggered the back event.
+     * @example 'pages/index/index'
      */
-    initialValue: boolean;
+    page: string;
+};
+/**
+ * Per-page options for `onPageBack()`.
+ */
+type OnPageBackOptions = {
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
+     * @example
+     * onPageBack(() => showDialog(), { preventDefault: true })
      */
     preventDefault: boolean;
     /**
-     * 阻止次数，默认是 `1`
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
+     * @example
+     * // Block 3 times, then allow back
+     * onPageBack(() => {}, { frequency: 3 })
      */
     frequency: number;
     /**
-     * 调试模式
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` to start disabled and enable manually via `activeMpBack()`.
+     * @default true
+     * @example
+     * // Start disabled, enable after user action
+     * onPageBack(() => {}, { initialValue: false })
+     * activeMpBack()
      */
-    debug: boolean;
+    initialValue: boolean;
+};
+/**
+ * Global plugin options passed to `mpBackPlugin()` in `vite.config.ts`.
+ */
+type Config = OnPageBackOptions & {
     /**
-     * 页面回退时触发
+     * Enable debug logging in development mode.
+     * @default false
      */
-    onPageBack?: (params: BackParams) => void;
-};
-type BackParams = {
+    debug: boolean;
     /**
-     * 当前页面路径
+     * Global callback fired every time a back event is detected on any page.
+     * Page-level callbacks registered via `onPageBack()` run in addition to this.
+     * @example
+     * mpBackPlugin({
+     *   onPageBack: ({ page }) => console.log('back on:', page)
+     * })
      */
-    page: string;
+    onPageBack?: (params: BackParams) => void;
 };
+type UserOptions = Partial<Config>;
 
 declare function MpBackPlugin(userOptions?: UserOptions): Plugin;
 

package/dist/index.d.ts

@@ -1,34 +1,67 @@
 import { Plugin } from 'vite';
 
-type UserOptions = Partial<Config>;
-type Config = {
+/**
+ * Parameters passed to the onPageBack callback.
+ */
+type BackParams = {
     /**
-     * 初始化时是否监听手势返回，默认值为`true`
+     * The path of the current page that triggered the back event.
+     * @example 'pages/index/index'
      */
-    initialValue: boolean;
+    page: string;
+};
+/**
+ * Per-page options for `onPageBack()`.
+ */
+type OnPageBackOptions = {
     /**
-     * 是否阻止默认的回退事件，默认为 false
+     * Whether to block the default back navigation for this page.
+     * When `true`, the user stays on the current page and only the callback fires.
+     * @default false
+     * @example
+     * onPageBack(() => showDialog(), { preventDefault: true })
      */
     preventDefault: boolean;
     /**
-     * 阻止次数，默认是 `1`
+     * How many times to intercept the back event before allowing through.
+     * Set to a large number (e.g. `9999`) for persistent interception.
+     * @default 1
+     * @example
+     * // Block 3 times, then allow back
+     * onPageBack(() => {}, { frequency: 3 })
      */
     frequency: number;
     /**
-     * 调试模式
+     * Whether to start listening immediately when the page mounts.
+     * Set to `false` to start disabled and enable manually via `activeMpBack()`.
+     * @default true
+     * @example
+     * // Start disabled, enable after user action
+     * onPageBack(() => {}, { initialValue: false })
+     * activeMpBack()
      */
-    debug: boolean;
+    initialValue: boolean;
+};
+/**
+ * Global plugin options passed to `mpBackPlugin()` in `vite.config.ts`.
+ */
+type Config = OnPageBackOptions & {
     /**
-     * 页面回退时触发
+     * Enable debug logging in development mode.
+     * @default false
      */
-    onPageBack?: (params: BackParams) => void;
-};
-type BackParams = {
+    debug: boolean;
     /**
-     * 当前页面路径
+     * Global callback fired every time a back event is detected on any page.
+     * Page-level callbacks registered via `onPageBack()` run in addition to this.
+     * @example
+     * mpBackPlugin({
+     *   onPageBack: ({ page }) => console.log('back on:', page)
+     * })
      */
-    page: string;
+    onPageBack?: (params: BackParams) => void;
 };
+type UserOptions = Partial<Config>;
 
 declare function MpBackPlugin(userOptions?: UserOptions): Plugin;
 

package/dist/index.mjs

@@ -412,9 +412,10 @@ async function resolveCompiler(root) {
         return await import('@vue/compiler-sfc');
       } catch (secondError) {
         throw new Error(
-          `\u65E0\u6CD5\u89E3\u6790 @vue/compiler-sfc\u3002
-\u6B64\u63D2\u4EF6\u9700\u8981\u9879\u76EE\u4E2D\u5B89\u88C5 @vue/compiler-sfc\u3002
-\u8BF7\u624B\u52A8\u5B89\u88C5\uFF1Apnpm add -D @vue/compiler-sfc
+          `[mp-weixin-back] Cannot resolve @vue/compiler-sfc.
+This plugin requires @vue/compiler-sfc to be installed in your project.
+Fix: pnpm add -D @vue/compiler-sfc
+Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E
 `
         );
       }
@@ -436,7 +437,10 @@ async function transformVueFile(code, id) {
     const walker = scriptSetup ? "compositionWalk" : "optionsWalk";
     return vueWalker[walker](this, code, sfc, id);
   } catch (error) {
-    this.log.error("\u89E3\u6790vue\u6587\u4EF6\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u662F\u5426\u6B63\u786E");
+    this.log.error(
+      `Failed to transform ${id}. Please check the file is a valid Vue SFC.
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#-\u5FEB\u901F\u5F00\u59CB`
+    );
     this.log.error(String(error));
     return code;
   }
@@ -500,7 +504,11 @@ class pageContext {
         }
       }
     } catch (error) {
-      this.log.error("\u8BFB\u53D6pages.json\u6587\u4EF6\u5931\u8D25");
+      this.log.error(
+        `Failed to read pages.json. Make sure src/pages.json exists and is valid JSON/JSON5.
+  Path checked: ${this.getPagesJsonPath()}
+  Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-\u914D\u7F6E`
+      );
       this.log.debugLog(String(error));
     }
   }

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "mp-weixin-back",
   "type": "module",
-  "version": "0.0.15",
-  "description": "监听微信小程序的手势返回和页面默认导航栏的返回",
+  "version": "0.0.17",
+  "description": "Vite plugin to intercept back navigation (gesture back & navbar back) in WeChat miniprogram (mp-weixin) built with uni-app + Vue 3. 监听微信小程序的手势返回和页面默认导航栏的返回",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "scripts": {
-    "build": "unbuild",
-    "test": "vitest"
-  },
   "keywords": [
+    "miniprogram",
+    "wechat",
+    "mp-weixin",
+    "back-navigation",
+    "gesture-back",
+    "navigate-back",
+    "page-back",
+    "navigation-intercept",
+    "vite-plugin",
+    "uniapp",
+    "uni-app",
+    "vue3",
     "微信小程序",
     "手势返回",
-    "vite",
-    "uniapp"
+    "页面返回拦截"
   ],
   "exports": {
     ".": {
@@ -31,6 +38,11 @@
       "types": "./client.d.ts"
     }
   },
+  "files": [
+    "dist",
+    "client.d.ts",
+    "README.md"
+  ],
   "author": "DBAAZzz",
   "license": "ISC",
   "repository": {
@@ -54,6 +66,7 @@
     "*": "prettier --write"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.29.8",
     "@types/babel__generator": "^7.6.8",
     "@types/node": "^22.9.3",
     "@vitejs/plugin-vue": "^5.2.0",
@@ -63,5 +76,12 @@
     "unbuild": "^2.0.0",
     "vitest": "^2.1.5",
     "vue": "^3.5.13"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish"
   }
-}
+}

package/readme.md

@@ -1,5 +1,30 @@
 # mp-weixin-back
 
+Vite plugin to intercept back navigation (gesture back + navbar back button) in WeChat miniprogram (mp-weixin) built with uni-app + Vue 3.
+
+## TL;DR
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import mpBackPlugin from 'mp-weixin-back'
+
+export default defineConfig({
+  plugins: [mpBackPlugin()],
+})
+```
+
+```ts
+// Any page .vue file — inside <script setup>
+import onPageBack from 'mp-weixin-back-helper'
+
+onPageBack(() => {
+  // handle back: show dialog, log analytics, etc.
+})
+```
+
+---
+
 ## 功能概述
 
 `mp-weixin-back` 是一个专门用于监听微信小程序`手势返回`、`导航栏返回事件`、`navigateBack`的工具库，提供灵活的配置选项和简洁的 API。
@@ -9,7 +34,7 @@
 ```bash
 npm install mp-weixin-back
 # 或
-yarn add mp-weixin-back
+pnpm add mp-weixin-back
 ```
 
 ## ⚙️ Vite 配置
@@ -27,9 +52,9 @@ export default defineConfig({
       preventDefault: false, // 是否阻止默认返回行为，设置成 true 则不会返回上一层
       frequency: 1, // 阻止次数，需要一直拦截则设置一个很大的值即可，如：9999
       debug: false, // 调试模式，默认为 false
-      onPageBack: () => {
-        console.log('返回事件触发')
-      }, // 统一钩子，事件触发时执行
+      onPageBack: ({ page }) => {
+        console.log('返回事件触发，当前页面：', page)
+      }, // 全局钩子，任意页面触发时执行
     }),
   ],
 })
@@ -68,24 +93,45 @@ onPageBack(
 )
 ```
 
+### 显示确认弹窗（常见场景）
+
+```ts
+<script setup>
+import onPageBack from 'mp-weixin-back-helper'
+
+onPageBack(
+  () => {
+    uni.showModal({
+      title: '提示',
+      content: '确定要离开当前页面吗？',
+      success: (res) => {
+        if (res.confirm) uni.navigateBack()
+      },
+    })
+  },
+  { preventDefault: true }
+)
+</script>
+```
+
 ## 📚 API 文档
 
-### `onPageBack(callback, config?)`
+### `onPageBack(callback, options?)`
 
-监听页面返回事件
+监听页面返回事件，必须在 `<script setup>` 顶层调用。
 
-| 参数     | 类型         | 必填 | 说明                     |
-| -------- | ------------ | ---- | ------------------------ |
-| callback | `() => void` | 是   | 返回事件触发时的回调函数 |
-| options  | Object       | 否   | 监听器配置选项           |
+| 参数       | 类型                | 必填 | 说明                     |
+| ---------- | ------------------- | ---- | ------------------------ |
+| `callback` | `() => void`        | 是   | 返回事件触发时的回调函数 |
+| `options`  | `OnPageBackOptions` | 否   | 监听器配置选项           |
 
-#### 配置选项
+#### 配置选项 `OnPageBackOptions`
 
-| 参数           | 类型    | 默认值 | 说明                                            |
-| -------------- | ------- | ------ | ----------------------------------------------- |
-| preventDefault | boolean | false  | 是否阻止默认返回行为（true 时页面不会实际返回） |
-| frequency      | number  | 1      | 阻止次数                                        |
-| initialValue   | boolean | true   | 是否立即启用监听（设为 false 时需手动激活）     |
+| 参数             | 类型      | 默认值  | 说明                                                            |
+| ---------------- | --------- | ------- | --------------------------------------------------------------- |
+| `preventDefault` | `boolean` | `false` | 是否阻止默认返回行为（`true` 时页面不会实际返回）               |
+| `frequency`      | `number`  | `1`     | 阻止次数                                                        |
+| `initialValue`   | `boolean` | `true`  | 是否立即启用监听（设为 `false` 时需手动调用 `activeMpBack()`）  |
 
 ### 辅助方法
 
@@ -103,20 +149,27 @@ onPageBack(
 <template>
   <div>
     <!-- 页面代码 -->
-    <button @click="toggleListener(true)">开启</button>
-    <button @click="toggleListener(false)">禁用</button>
+    <button @click="activeMpBack()">开启</button>
+    <button @click="inactiveMpBack()">禁用</button>
   </div>
 </template>
 
 <script setup>
   import onPageBack, { activeMpBack, inactiveMpBack } from 'mp-weixin-back-helper'
 
-  const toggleListener = (enable) => {
-    enable ? activeMpBack() : inactiveMpBack()
-  }
+  onPageBack(() => { /* 处理返回 */ }, { initialValue: false })
 </script>
 ```
 
+### 插件全局配置 `mpBackPlugin(options)`
+
+| 参数             | 类型                                        | 默认值  | 说明                       |
+| ---------------- | ------------------------------------------- | ------- | -------------------------- |
+| `preventDefault` | `boolean`                                   | `false` | 全局阻止默认返回行为       |
+| `frequency`      | `number`                                    | `1`     | 全局阻止次数               |
+| `debug`          | `boolean`                                   | `false` | 开发模式下开启调试日志     |
+| `onPageBack`     | `(params: { page: string }) => void`        | —       | 全局回调，任意页面触发执行 |
+
 ## 🎯 选项式 API 支持（未完善）
 
 组件内直接声明
@@ -171,3 +224,10 @@ onPageBack(
 ### Q2: 全局配置与页面配置的优先级？
 
 页面级配置会覆盖全局配置，建议将通用配置放在全局，特殊需求在页面单独设置。
+
+### Q3: 不生效怎么排查？
+
+1. 确认 `src/pages.json` 存在且格式正确
+2. 确认是页面级 `.vue` 文件（非组件）
+3. 开启 `debug: true` 查看插件日志
+4. 确认 `@vue/compiler-sfc` 已安装：`pnpm add -D @vue/compiler-sfc`