mp-weixin-back 0.0.17 → 0.0.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mp-weixin-back",
   "type": "module",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "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",
@@ -50,7 +50,6 @@
     "url": "git+https://github.com/DBAAZzz/mp-weixin-back.git"
   },
   "dependencies": {
-    "@babel/generator": "^7.26.2",
     "@babel/parser": "^7.26.2",
     "@babel/traverse": "^7.25.9",
     "ast-kit": "^1.3.1",
@@ -66,22 +65,29 @@
     "*": "prettier --write"
   },
   "devDependencies": {
+    "@babel/types": "^7.26.0",
     "@changesets/cli": "^2.29.8",
-    "@types/babel__generator": "^7.6.8",
+    "@types/babel__traverse": "^7.20.6",
     "@types/node": "^22.9.3",
     "@vitejs/plugin-vue": "^5.2.0",
+    "@vue/compiler-sfc": "^3.5.13",
     "@vue/test-utils": "^2.4.6",
     "happy-dom": "^15.11.6",
     "typescript": "^5.7.2",
     "unbuild": "^2.0.0",
+    "vite": "^5.4.11",
     "vitest": "^2.1.5",
     "vue": "^3.5.13"
   },
   "scripts": {
     "build": "unbuild",
     "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check-publish": "node scripts/check-publish.mjs && pnpm publish --dry-run --no-git-checks",
     "changeset": "changeset",
     "version": "changeset version",
-    "release": "pnpm build && changeset publish"
+    "release": "pnpm run version && pnpm typecheck && pnpm test:run && pnpm build && pnpm check-publish && pnpm publish --access public --no-git-checks",
+    "release:dry": "pnpm build && pnpm check-publish"
   }
 }

package/readme.md

@@ -54,12 +54,19 @@ export default defineConfig({
       debug: false, // 调试模式，默认为 false
       onPageBack: ({ page }) => {
         console.log('返回事件触发，当前页面：', page)
-      }, // 全局钩子，任意页面触发时执行
+      }, // 全局钩子，任意页面触发时执行。⚠️ 该函数会被序列化注入页面，必须自包含（不能引用 vite.config.ts 中的变量或 import 的模块）
+      pageContainer: {
+        zIndex: 1, // 注入的 page-container 的 z-index，默认 1
+        overlay: false, // 是否显示遮罩，默认 false
+        duration: false, // 动画时长（ms），默认 false 关闭
+      },
     }),
   ],
 })
 ```
 
+> 插件会自动探测 `src/pages.json`（CLI 项目）或根目录 `pages.json`（HBuilderX 项目）；多端构建时仅在 `UNI_PLATFORM=mp-weixin` 下生效，其他平台自动降级为 no-op。
+
 ## 🚀 快速开始
 
 ### 基本使用
@@ -133,6 +140,8 @@ onPageBack(
 | `frequency`      | `number`  | `1`     | 阻止次数                                                        |
 | `initialValue`   | `boolean` | `true`  | 是否立即启用监听（设为 `false` 时需手动调用 `activeMpBack()`）  |
 
+> ⚠️ 这些配置在**构建期静态读取**，必须直接写布尔/数字字面量（如 `{ frequency: 3 }`），不能传变量或表达式。需要运行时动态控制时请使用 `activeMpBack()` / `inactiveMpBack()`。
+
 ### 辅助方法
 
 #### `activeMpBack()`
@@ -167,33 +176,55 @@ onPageBack(
 | ---------------- | ------------------------------------------- | ------- | -------------------------- |
 | `preventDefault` | `boolean`                                   | `false` | 全局阻止默认返回行为       |
 | `frequency`      | `number`                                    | `1`     | 全局阻止次数               |
+| `initialValue`   | `boolean`                                   | `true`  | 全局是否立即启用监听       |
 | `debug`          | `boolean`                                   | `false` | 开发模式下开启调试日志     |
-| `onPageBack`     | `(params: { page: string }) => void`        | —       | 全局回调，任意页面触发执行 |
-
-## 🎯 选项式 API 支持（未完善）
+| `onPageBack`     | `(params: { page: string \| null }) => void` | —       | 全局回调，任意页面触发执行。必须自包含（会被序列化注入页面，闭包变量运行时不可用，检测到时构建期会警告） |
+| `pageContainer`  | `{ zIndex?, overlay?, duration? }`          | 见上文  | 注入的 page-container 组件属性 |
 
-组件内直接声明
+## 🎯 选项式 API 支持
 
-在 Vue 组件的选项对象中直接定义 onPageBack 方法：
+在 Vue 组件的选项对象中直接定义 `onPageBack`，支持三种写法：
 
 ```html
-<template>
-  <div class="container">
-    <div>当前页面内容</div>
-  </div>
-</template>
-
 <script>
   export default {
-    // 读取 vite 中的配置
+    // 写法一：方法简写（使用 vite 中的全局配置）
     onPageBack() {
       console.log('检测到返回操作')
-      // 业务逻辑处理
     },
   }
 </script>
 ```
 
+```html
+<script>
+  export default {
+    // 写法二：函数属性
+    onPageBack: function () {
+      console.log('检测到返回操作')
+    },
+  }
+</script>
+```
+
+```html
+<script>
+  export default {
+    // 写法三：对象写法，支持页面级配置（与 composition API 对齐）
+    onPageBack: {
+      preventDefault: true,
+      frequency: 3,
+      initialValue: true,
+      handler() {
+        console.log('检测到返回操作')
+      },
+    },
+  }
+</script>
+```
+
+回调中的 `this` 指向组件实例，可直接访问 `data` / `methods`。
+
 ## 🛠 类型支持
 
 ### 类型声明配置
@@ -227,7 +258,8 @@ onPageBack(
 
 ### Q3: 不生效怎么排查？
 
-1. 确认 `src/pages.json` 存在且格式正确
-2. 确认是页面级 `.vue` 文件（非组件）
-3. 开启 `debug: true` 查看插件日志
-4. 确认 `@vue/compiler-sfc` 已安装：`pnpm add -D @vue/compiler-sfc`
+1. 确认 `src/pages.json` 或根目录 `pages.json` 存在且格式正确
+2. 确认是 `pages.json` 中注册的页面级 `.vue` 文件（组件中使用不会注入，dev 下运行时会有 console 警告）
+3. 多端项目确认构建平台为 `mp-weixin`（其他平台插件自动禁用）
+4. 开启 `debug: true` 查看插件日志
+5. 确认 `@vue/compiler-sfc` 已安装：`pnpm add -D @vue/compiler-sfc`