scan-code-jssdk/README.md

scan-code-jssdk

统一扫码 JSSDK，支持桥接扫码、微信 JSSDK 扫码、Web 摄像头扫码、选择图片识别和扫码枪输入。

功能

• App 桥接环境：优先调用原生桥接 startScan / stopScan。
• 微信浏览器：初始化微信 JSSDK 后调用 wx.scanQRCode。
• Web 浏览器：使用 BarcodeDetector 识别二维码和条形码。
• 图片识别：选择本地图片后识别二维码/条形码。
• 扫码枪：监听键盘快速输入并统一走扫码监听回调。
• 监听规则：支持按 match 正则和 level 优先级分发扫码结果。

引入

构建后使用 dist/index.js：

<script src="./dist/index.js"></script>
<script>
  IScan.config().then(function () {
    console.log("IScan ready");
  });
</script>

如果脚本是后加载的，可以监听 IScanReady：

function init() {
  IScan.config().then(function () {
    // ready
  });
}

if (window.IScan) {
  init();
} else {
  window.addEventListener("IScanReady", init, { once: true });
}

快速开始

IScan.config({
  webCanvasEnabled: true,
  webScanBeepEnabled: true,
  initWechatJssdk: {
    apiUrl: "https://your-domain.com/wechat/jssdk-config"
  }
}).then(function () {
  IScan.setStatusListener(function (status) {
    console.log("status:", status);
  });

  IScan.onScanListener(function (res) {
    console.log("scan result:", res.result, res.key);
  }, "scan", null, 100);
});

// 自动选择可用扫码方式：桥接 -> 微信 -> Web 摄像头 -> 图片识别
IScan.startScan();

// 仅打开 Web 视频扫码
IScan.scanVideo();

// 仅选择图片识别
IScan.scanImage();

// 停止当前扫码
IScan.stopScan();

配置项

通过 IScan.config(options) 配置。

interface ScanConfigOptions {
  bridgeEnabled?: boolean;
  bridgeName?: string;
  webCanvasEnabled?: boolean;
  webScanCanvasStyle?: string;
  webScanType?: ("qrCode" | "barCode")[];
  webScanVideoMirror?: boolean;
  webScanVideoMirrorVertical?: boolean;
  webScanBeepAudio?: string;
  webScanBeepEnabled?: boolean;
  initWechatJssdk?: {
    apiUrl: string;
    sdkConfig?: {
      debug?: boolean;
      appId: string;
      timestamp: number;
      nonceStr: string;
      signature: string;
    };
    sdkUrl?: string;
    jsApiList?: string[];
  };
}

配置	说明	默认值
bridgeEnabled	是否启用桥接扫码	true
bridgeName	挂载在 window 上的桥接对象名称	__bridge_client__
webCanvasEnabled	是否显示 Web 扫码 canvas；关闭后仍会用隐藏 canvas 识别	true
webScanCanvasStyle	Web 扫码 canvas 样式	position: fixed; width: 300px; height: 300px; top: 0; left: 0; z-index: 9999;
webScanType	Web 扫码类型	["qrCode", "barCode"]
webScanVideoMirror	Web 视频是否水平镜像；不配置时自动判断：前置/PC 镜像，后置不镜像	自动
webScanVideoMirrorVertical	Web 视频是否垂直镜像	false
webScanBeepAudio	Web 扫码成功提示音地址	内置提示音
webScanBeepEnabled	Web 扫码成功是否播放提示音	true
initWechatJssdk	微信 JSSDK 初始化配置，仅微信环境生效	无

桥接接入

桥接对象需要挂载到 window[bridgeName]，并实现 call(method, data)。

SDK 会调用：

• startScan
• stopScan

异步回调方法名为 ${bridgeName}_handle_callback。

window.__bridge_client__ = {
  call: function (method, data) {
    var requestId = data.request_id;

    if (method === "startScan") {
      // 调用原生扫码后回调
      window.__bridge_client___handle_callback({
        code: 0,
        method: method,
        request_id: requestId,
        payload: {
          result: "https://example.com"
        }
      });
    }

    if (method === "stopScan") {
      window.__bridge_client___handle_callback({
        code: 0,
        method: method,
        request_id: requestId,
        payload: {}
      });
    }
  }
};

微信 JSSDK 接入

配置接口方式：

IScan.config({
  initWechatJssdk: {
    apiUrl: "https://your-domain.com/wechat/jssdk-config"
  }
});

接口会收到当前页面 URL 参数：url=location.href.split("#")[0]。

也可以直接传入微信签名配置：

IScan.config({
  initWechatJssdk: {
    apiUrl: "",
    sdkConfig: {
      appId: "wx_app_id",
      timestamp: 123456,
      nonceStr: "nonce",
      signature: "signature"
    }
  }
});

jsApiList 会默认追加 scanQRCode。

API

config(options?): Promise<any>

配置并初始化 SDK。

IScan.config({
  webCanvasEnabled: true
});

setStatusListener(callback): void

监听扫码状态，状态为：

• scanning
• closed

IScan.setStatusListener(function (status) {
  console.log(status);
});

onScanListener(callback, key, match?, level?): ScanListenerInfo

添加扫码结果监听。

var listener = IScan.onScanListener(function (res) {
  console.log(res.result, res.key);
}, "order", "^https://", 100);

参数说明：

• callback：扫码结果回调。
• key：监听 key，同 key 会覆盖旧监听。
• match：可选正则字符串；扫码结果匹配后才回调。
• level：优先级，数值越大越先匹配。

offScanListener(callbackOrKey): void

移除监听，可传 callback 或 key。

IScan.offScanListener("order");
listener.cancel();

getStatus(): "scanning" | "closed"

获取当前扫码状态。

console.log(IScan.getStatus());

startScan(): void

开启扫码。SDK 会按以下顺序选择可用能力：

1. 桥接扫码
2. 微信扫码
3. Web 摄像头扫码
4. 图片识别

扫码结果通过 onScanListener 回调。

IScan.startScan();

scanVideo(): void

直接开启 Web 摄像头扫码。扫码结果通过 onScanListener 回调。

IScan.scanVideo();

scanImage(): void

直接选择图片进行识别。识别结果通过 onScanListener 回调。

IScan.scanImage();

stopScan(): void

停止当前扫码。

IScan.stopScan();

clear(): void

清空全部扫码监听。

IScan.clear();

类型

interface ScanResult {
  result: string;
  key: string;
}

type ScanStatus = "scanning" | "closed";

type ScanResultCallback = (result: ScanResult) => any;
type ScanStatusCallback = (status: ScanStatus) => any;

开发

npm install
npm run build

构建产物输出到 dist 目录。