mp-weixin-back 0.0.16 → 0.0.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mp-weixin-back",
   "type": "module",
-  "version": "0.0.16",
+  "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",
@@ -38,6 +38,11 @@
       "types": "./client.d.ts"
     }
   },
+  "files": [
+    "dist",
+    "client.d.ts",
+    "README.md"
+  ],
   "author": "DBAAZzz",
   "license": "ISC",
   "repository": {
@@ -45,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",
@@ -61,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`

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.editorconfig

@@ -1,25 +0,0 @@
-
-root = true
-
-[*]
-indent_style = space
-# 缩进大小=2
-indent_size = 2
-
-end_of_line = lf
-# 字符集=utf-8
-charset = utf-8
-# 删除行尾空格 = 是
-trim_trailing_whitespace = true
-# 插入最后一行=真
-insert_final_newline = true
-
-[*.md]
-# 删除行尾空格 = 否
-trim_trailing_whitespace = false
-
-[package.json]
-# 缩进样式=空格
-indent_style = space
-# 缩进大小=2
-indent_size = 2

package/.github/workflows/publish.yml

@@ -1,38 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    branches:
-      - main
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v4
-        with:
-          version: latest
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --no-frozen-lockfile
-
-      - name: Create Release Pull Request or Publish
-        uses: changesets/action@v1
-        with:
-          publish: pnpm release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierrc.cjs

@@ -1,8 +0,0 @@
-// .prettierrc.js 文件
-module.exports = {
-  printWidth: 100,
-  tabWidth: 2,
-  useTabs: false,
-  semi: false,
-  singleQuote: true,
-};

package/build.config.ts

@@ -1,12 +0,0 @@
-import { defineBuildConfig } from 'unbuild'
-
-export default defineBuildConfig({
-  entries: ['src/index'],
-  declaration: true,
-  clean: true,
-  rollup: {
-    emitCJS: true,
-  },
-  failOnWarn: false,
-  externals: ['vite', 'vue', '@babel/generator'],
-})

package/llms.txt

@@ -1,154 +0,0 @@
-# mp-weixin-back
-
-> Vite plugin for intercepting back navigation (gesture back + navbar back button) in WeChat miniprogram (mp-weixin) built with uni-app + Vue 3.
-
-## When to use
-
-Use this library when you need to:
-- Intercept or customize the swipe-back gesture in a WeChat miniprogram page
-- Intercept or customize the navbar back button behavior
-- Show a confirmation dialog before the user leaves a page
-- Prevent accidental back navigation (e.g., on a form page)
-
-## Install
-
-```bash
-npm install mp-weixin-back
-# or
-pnpm add mp-weixin-back
-```
-
-## Setup (vite.config.ts)
-
-Register the Vite plugin once, globally:
-
-```ts
-import { defineConfig } from 'vite'
-import mpBackPlugin from 'mp-weixin-back'
-
-export default defineConfig({
-  plugins: [
-    mpBackPlugin({
-      preventDefault: false, // true = block all back navigation by default
-      frequency: 1,          // how many times to intercept before allowing through
-      debug: false,          // enable debug logging in development
-      onPageBack: ({ page }) => {
-        console.log('back triggered on page:', page)
-      },
-    }),
-  ],
-})
-```
-
-## Usage in Vue SFC (Composition API)
-
-Import from the virtual module `mp-weixin-back-helper`:
-
-```ts
-// Basic usage — listen to back event
-import onPageBack from 'mp-weixin-back-helper'
-
-onPageBack(() => {
-  console.log('back navigation detected')
-})
-```
-
-```ts
-// Advanced — prevent back and show dialog
-import onPageBack from 'mp-weixin-back-helper'
-
-onPageBack(
-  () => {
-    showConfirmDialog() // your logic here
-  },
-  {
-    preventDefault: true, // block default back behavior
-    frequency: 2,         // intercept 2 times
-    initialValue: true,   // start listening immediately (default)
-  }
-)
-```
-
-```ts
-// Manually toggle the listener
-import onPageBack, { activeMpBack, inactiveMpBack } from 'mp-weixin-back-helper'
-
-onPageBack(() => { /* ... */ }, { initialValue: false }) // start disabled
-
-activeMpBack()   // enable listener (call inside <script setup>)
-inactiveMpBack() // disable listener (call inside <script setup>)
-```
-
-## TypeScript support
-
-Add to `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "types": ["mp-weixin-back/client"]
-  }
-}
-```
-
-Or in `env.d.ts`:
-
-```ts
-/// <reference types="mp-weixin-back/client" />
-```
-
-## API Reference
-
-### Plugin options (`mpBackPlugin(options)`)
-
-| Option          | Type                              | Default | Description                                              |
-| --------------- | --------------------------------- | ------- | -------------------------------------------------------- |
-| `preventDefault`| `boolean`                         | `false` | Block default back behavior globally                     |
-| `frequency`     | `number`                          | `1`     | Number of times to intercept before allowing through     |
-| `debug`         | `boolean`                         | `false` | Log debug info in development mode                       |
-| `onPageBack`    | `(params: { page: string }) => void` | —    | Global callback fired on every back event                |
-
-### `onPageBack(callback, options?)`
-
-Listen to back events on the current page. Must be called in `<script setup>`.
-
-| Param      | Type                  | Required | Description                     |
-| ---------- | --------------------- | -------- | ------------------------------- |
-| `callback` | `() => void`          | Yes      | Function called when back fires |
-| `options`  | `OnPageBackOptions`   | No       | Per-page overrides              |
-
-#### `OnPageBackOptions`
-
-| Option          | Type      | Default | Description                                                  |
-| --------------- | --------- | ------- | ------------------------------------------------------------ |
-| `preventDefault`| `boolean` | `false` | Block default back for this page                             |
-| `frequency`     | `number`  | `1`     | Intercept count for this page                                |
-| `initialValue`  | `boolean` | `true`  | Start listening immediately; set `false` to enable manually  |
-
-### `activeMpBack()`
-
-Enable the back listener. Call inside `<script setup>` when `initialValue: false`.
-
-### `inactiveMpBack()`
-
-Disable the back listener. Call inside `<script setup>`.
-
-## How it works
-
-This is a **Vite transform plugin**. At build time it:
-1. Reads `src/pages.json` to identify miniprogram pages
-2. For each `.vue` page file, injects a `<page-container>` component into the template (the WeChat API used to intercept back gestures)
-3. Wires up the `onPageBack` composable to control `show` state of `<page-container>`
-
-The virtual module `mp-weixin-back-helper` is resolved by the plugin and provides the runtime composable API.
-
-## Constraints
-
-- Requires **uni-app** project with `src/pages.json`
-- Requires **Vue 3** + `<script setup>` (Composition API)
-- Works with **Vite 3–6**
-- Only applies to page-level `.vue` files, not components
-
-## Repository
-
-https://github.com/DBAAZzz/mp-weixin-back

package/shims-vue.d.ts

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

package/src/context.ts

@@ -1,78 +0,0 @@
-import path from 'path'
-import fs from 'fs'
-import JSON5 from 'json5'
-import { red, white, green } from 'kolorist'
-import { ContextConfig, PagesJson } from '../types'
-import { transformVueFile } from '../utils'
-
-export class pageContext {
-  private logPreText = '[mp-weixin-back] : '
-  config: ContextConfig
-  pages: string[] = []
-  log = {
-    info: (text: string) => {
-      console.log(white(this.logPreText + text))
-    },
-    error: (text: string) => {
-      console.log(red(this.logPreText + text))
-    },
-    debugLog: (text: string) => {
-      if (this.config.mode === 'development' && this.config.debug) {
-        console.log(green(this.logPreText + text))
-      }
-    },
-  }
-
-  constructor(config: ContextConfig) {
-    this.config = config
-  }
-  getPagesJsonPath() {
-    const pagesJsonPath = path.join(this.config.root, 'src/pages.json')
-    return pagesJsonPath
-  }
-  // 获取页面配置详情
-  async getPagesJsonInfo() {
-    const hasPagesJson = fs.existsSync(this.getPagesJsonPath())
-    if (!hasPagesJson) return
-    try {
-      const content = await fs.promises.readFile(this.getPagesJsonPath(), 'utf-8')
-      const pagesContent = JSON5.parse(content) as PagesJson
-      const { pages, subpackages } = pagesContent
-      if (pages) {
-        const mainPages = pages.reduce((acc: string[], current) => {
-          acc.push(current.path)
-          return acc
-        }, [])
-        this.pages.push(...mainPages)
-      }
-      if (subpackages) {
-        for (let i = 0; i < subpackages.length; i++) {
-          const element = subpackages[i]
-          const root = element.root
-          const subPages = element.pages.reduce((acc: string[], current) => {
-            acc.push(`${root}/${current.path}`.replace('//', '/'))
-            return acc
-          }, [])
-          this.pages.push(...subPages)
-        }
-      }
-    } catch (error: unknown) {
-      this.log.error(
-        `Failed to read pages.json. Make sure src/pages.json exists and is valid JSON/JSON5.\n` +
-          `  Path checked: ${this.getPagesJsonPath()}\n` +
-          `  Docs: https://github.com/DBAAZzz/mp-weixin-back#%EF%B8%8F-vite-配置`
-      )
-      this.log.debugLog(String(error))
-    }
-  }
-  // 获取指定id的page
-  getPageById(id: string) {
-    const path = (id.split('src/')[1] || '').replace('.vue', '')
-    // 页面级别
-    return this.pages.find((i) => i === path) || null
-  }
-  async transform(code: string, id: string) {
-    const result = await transformVueFile.call(this, code, id)
-    return result
-  }
-}

package/src/index.ts

@@ -1,79 +0,0 @@
-import { pageContext } from './context'
-import { virtualFileId } from '../utils/constant'
-import type { Plugin } from 'vite'
-import type { Config, UserOptions } from '../types'
-
-function MpBackPlugin(userOptions: UserOptions = {}): Plugin {
-  let context: pageContext
-
-  const defaultOptions: Config = {
-    initialValue: true,
-    preventDefault: false,
-    frequency: 1,
-    debug: false,
-  }
-  const options = { ...defaultOptions, ...userOptions }
-
-  return {
-    name: 'vite-plugin-mp-weixin-back',
-    enforce: 'pre',
-    configResolved(config) {
-      context = new pageContext({ ...options, mode: config.mode, root: config.root })
-    },
-    buildStart() {
-      context.getPagesJsonInfo()
-    },
-    resolveId(id) {
-      if (id === virtualFileId) {
-        return virtualFileId
-      }
-    },
-    load(id) {
-      if (id.includes('node_modules')) {
-        return
-      }
-      // 导出一个对象
-      if (id === virtualFileId) {
-        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) {
-      if (id.includes('node_modules') || !id.includes('.vue')) {
-        return
-      }
-
-      return {
-        code: await context.transform(code, id),
-        map: null,
-      }
-    },
-  } as Plugin
-}
-
-export default MpBackPlugin

package/test/data/index-default.vue

@@ -1,17 +0,0 @@
-<template>
-  <div>我是默认的界面</div>
-</template>
-
-<script>
-export default {
-  data() {
-    return {}
-  },
-  onPageBack() {
-    console.log('触发了手势返回')
-    return true
-  },
-}
-</script>
-
-<style></style>

package/test/data/index-setup.vue

@@ -1,14 +0,0 @@
-<template>
-  <div>我是默认的界面</div>
-</template>
-
-<script setup>
-import onPageBack from 'mp-weixin-back-helper'
-
-onPageBack(() => {
-  console.log('触发了手势返回')
-  return true
-})
-</script>
-
-<style></style>

package/test/data/index-utils.vue

@@ -1,29 +0,0 @@
-<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>