【重磅】无侵入式一键实现监听微信小程序手势左滑事件！！

百慕大三角
1,480 阅读4分钟

序言

在开发微信小程序时，很多人都会遇到这样的需求：例如，监听用户左滑返回操作，并弹窗确认是否真的要退出页面。

当我们就会吭哧吭哧的去百度寻找相关的资料，但得到的答案都是不能。

image.png

image.png

然而是真的不能监听手势返回吗？答案是否定的，利用 page-container 组件是可以实现监听手势返回， 对应的文档在这：page-container。

下面是该组件描述：

小程序如果在页面内进行复杂的界面设计（如在页面内弹出半屏的弹窗、在页面内加载一个全屏的子页面等），用户进行返回操作会直接离开当前页面，不符合用户预期，预期应为关闭当前弹出的组件。 为此提供“假页”容器组件，效果类似于 popup 弹出层，页面内存在该容器时，当用户进行返回操作，关闭该容器不关闭页面。返回操作包括三种情形，右滑手势、安卓物理返回键和调用 navigateBack 接口。

原理就是通过页面引入 page-container 组件和实现其 beforeleave 方法。

如果我们需要在多个页面中监听手势返回事件，只能在各个页面一遍遍引入组件和声明 beforeleave 方法。如何方便快捷的实现监听手势返回？于是 mp-weixin-back 诞生了，提供了一种简单、高效的解决方案。

mp-weixin-back

功能概述

mp-weixin-back 是一个专门用于监听微信小程序手势返回、导航栏返回事件、navigateBack的工具库，提供灵活的配置选项和简洁的 API。

📦 安装

npm install mp-weixin-back
# 或
yarn add mp-weixin-back

⚙️ Vite 配置

在 vite.config.ts 中添加插件：

import { defineConfig } from 'vite'
import mpBackPlugin from 'mp-weixin-back'

export default defineConfig({
  plugins: [
    mpBackPlugin({
      // 可选配置项
      preventDefault: false, // 是否阻止默认返回行为，设置成 true 则不会返回上一层
      frequency: 1, // 阻止次数，需要一直拦截则设置一个很大的值即可，如：9999
      debug: false, // 调试模式，默认为 false
      onPageBack: () => {
        console.log('返回事件触发')
      }, // 统一钩子，事件触发时执行
    }),
  ],
})

🚀 快速开始

基本使用

<script setup>
import onPageBack from 'mp-weixin-back-helper'

// 简单监听返回事件
onPageBack(() => {
  console.log('检测到返回操作（手势或导航栏返回）')
  // 在这里添加你的处理逻辑
})
</script>

高级配置

// 带配置的监听
onPageBack(
  () => {
    console.log('返回事件被触发')
    // 自定义处理逻辑
  },
  {
    initialValue: false, // 立即生效，默认值为`true`
    preventDefault: true, // 阻止默认返回行为
    frequency: 2, // 阻止次数为2次
  }
)

📚 API 文档

onPageBack(callback, config?)

监听页面返回事件

参数类型必填说明
callback() => void是返回事件触发时的回调函数
optionsObject否监听器配置选项
配置选项
参数类型默认值说明
preventDefaultbooleanfalse是否阻止默认返回行为（true 时页面不会实际返回）
frequencynumber1阻止次数
initialValuebooleantrue是否立即启用监听（设为 false 时需手动激活）

辅助方法

activeMpBack()

启用返回事件监听（需在<script setup>中执行）

inactiveMpBack()

禁用返回事件监听（需在<script setup>中执行）

举例：

<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>

🎯 选项式 API 支持（未完善）

组件内直接声明

在 Vue 组件的选项对象中直接定义 onPageBack 方法：

<template>
  <div class="container">
    <div>当前页面内容</div>
  </div>
</template>

<script>
  export default {
    // 读取 vite 中的配置
    onPageBack() {
      console.log('检测到返回操作')
      // 业务逻辑处理
    },
  }
</script>

🛠 类型支持

类型声明配置

在 tsconfig.json 中添加：

{
  "compilerOptions": {
    "types": ["mp-weixin-back/client"]
  }
}

或通过声明文件引用：

// env.d.ts
/// <reference types="mp-weixin-back/client" />

❓ 常见问题

Q1: 如何实现多页面独立配置？

每个页面单独调用 onPageBack 时传入不同的配置参数即可实现页面级定制。

Q2: 全局配置与页面配置的优先级？

页面级配置会覆盖全局配置，建议将通用配置放在全局，特殊需求在页面单独设置。

开源地址

如果 mp-weixin-back 对你有帮助，欢迎在 GitHub 上给项目点个 Star ⭐️！

Star 是对开源项目最直接、最有价值的支持方式：

  • 增加项目的可见度
  • 鼓励开发者继续维护和改进
  • 帮助其他开发者发现这个有用的工具

你的每一个 Star 都是对开源社区的贡献！

点击链接查看更详细文档：地址

avatar
文章
阅读
粉丝