QRPress 二维码长按兼容工具

GB.QRPress 用于改善微信 iOS 环境中，二维码图片经过 transform 等布局处理后无法正常长按识别的问题。长按目标时，它会临时复制二维码图片到独立遮罩层，为微信原生长按菜单提供可识别的图片节点。

安装与引入

浏览器直接引入

<script src="https://cloud.m775.net/js/qrpress.js"></script>

npm 项目

npm i @gentbo/qrpress

import '@gentbo/qrpress';

快速开始

默认监听带有 data-qrcode 属性的元素。目标可以是图片本身，也可以是内部包含图片的容器。

<div class="qr-card" data-qrcode>
  <img src="qrcode.png" alt="扫码访问">
</div>

<script>
GB.QRPress()
  .class('qr-overlay')
  .delay(350)
  .slide(10)
  .start();
</script>

配置遮罩样式

工具只负责创建遮罩、复制图片并设置图片尺寸，遮罩的位置、层级和视觉效果需要由页面 CSS 控制。

.qr-overlay {
  position: fixed;
  z-index: 9999;
  inset: 50% auto auto 50%;
  transform: translate(-50%, -50%);
  background: #fff;
}

.qr-overlay img {
  display: block;
}

遮罩宽高会自动使用原二维码图片的实际显示尺寸。遮罩图片会设置为不可拖拽，并在触摸结束约 300ms 后移除。

API 速查

GB.QRPress(selector?)创建监听器；默认选择器为 [data-qrcode]。

.class(name)设置临时遮罩层类名，默认 qr-overlay。

.delay(ms)设置触发长按的等待时间，默认 350ms，只接受正数。

.slide(px = 10)设置取消长按的移动阈值，默认 10px，只接受正数。

.start()在 document 上注册触摸监听并开始工作。

.run()start() 的兼容入口。

使用自定义选择器

GB.QRPress('.wechat-qrcode')
  .class('wechat-qr-overlay')
  .delay(500)
  .slide(16)
  .start();

事件采用委托方式注册在 document 上，因此启动后动态加入页面、且匹配选择器的二维码也可以工作。

使用边界

触摸环境监听 touchstart、touchmove、touchend 和 touchcancel，桌面鼠标长按不会触发。

目标结构匹配元素不是 img 时，会查找其内部的第一个 img；没有图片则不执行。

重复启动start() 没有重复调用保护；同一实例或多个实例重复启动会增加 document 监听器。

生命周期当前 API 没有停止或销毁方法，建议每个页面只初始化一次。