fix
This commit is contained in:
iqudoo
336
dist/index.md
vendored
Normal file
336
dist/index.md
vendored
Normal file
@@ -0,0 +1,336 @@
|
||||
# scan-code-jssdk
|
||||
|
||||
统一扫码 JSSDK，支持桥接扫码、微信小程序、微信 JSSDK 扫码、Web 摄像头扫码、选择图片识别和扫码枪输入。
|
||||
|
||||
## 功能
|
||||
|
||||
- App 桥接环境：优先调用原生桥接 `startScan` / `stopScan`。
|
||||
- 微信浏览器：初始化微信 JSSDK 后调用 `wx.scanQRCode`。
|
||||
- Web 浏览器：使用 `BarcodeDetector` 识别二维码和条形码。
|
||||
- 图片识别：选择本地图片后识别二维码/条形码。
|
||||
- 扫码枪：监听键盘快速输入并统一走扫码监听回调。
|
||||
- 监听规则：支持按 `match` 正则和 `level` 优先级分发扫码结果。
|
||||
|
||||
## 引入
|
||||
|
||||
构建后使用 `dist/index.js`：
|
||||
|
||||
```html
|
||||
<script src="./dist/index.js"></script>
|
||||
<script>
|
||||
IScan.config().then(function () {
|
||||
console.log("IScan ready");
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
如果脚本是后加载的，可以监听 `IScanReady`：
|
||||
|
||||
```js
|
||||
function init() {
|
||||
IScan.config().then(function () {
|
||||
// ready
|
||||
});
|
||||
}
|
||||
|
||||
if (window.IScan) {
|
||||
init();
|
||||
} else {
|
||||
window.addEventListener("IScanReady", init, { once: true });
|
||||
}
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
```js
|
||||
IScan.config({
|
||||
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)` 配置。
|
||||
|
||||
```ts
|
||||
interface ScanConfigOptions {
|
||||
scanRestartDelay?: number,
|
||||
bridgeEnabled?: boolean;
|
||||
bridgeName?: string;
|
||||
webScanEnabled?: boolean,
|
||||
webScanCanvasEnabled?: boolean;
|
||||
webScanCanvasStyle?: string;
|
||||
webScanCloseButtonStyle?: 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[];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
| 配置 | 说明 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `scanRestartDelay` | 扫码重启延迟，单位：毫秒 | `500ms` |
|
||||
| `bridgeEnabled` | 是否启用桥接扫码 | `true` |
|
||||
| `bridgeName` | 挂载在 `window` 上的桥接对象名称 | `__bridge_client__` |
|
||||
| `webScanEnabled` | 是否支持 WebScan 扫码 | `true` |
|
||||
| `webScanCanvasEnabled` | 是否显示 WebScan 扫码 canvas；关闭后仍会用隐藏 canvas 识别 | `true` |
|
||||
| `webScanCanvasStyle` | WebScan 扫码 canvas 样式 | `position: fixed; width: 300px; height: 300px; top: 0; left: 0; z-index: 9999;` |
|
||||
| `webScanCloseButtonStyle` | WebScan 扫码 canvas 关闭按钮样式 | 显示在 canvas 右上角 |
|
||||
| `webScanType` | WebScan 扫码类型 | `["qrCode", "barCode"]` |
|
||||
| `webScanVideoMirror` | WebScan 视频是否水平镜像；不配置时自动判断：前置/PC 镜像，后置不镜像 | 自动 |
|
||||
| `webScanVideoMirrorVertical` | WebScan 视频是否垂直镜像 | `false` |
|
||||
| `webScanBeepAudio` | WebScan 扫码成功提示音地址 | 内置提示音 |
|
||||
| `webScanBeepEnabled` | WebScan 扫码成功是否播放提示音 | `true` |
|
||||
| `initWechatJssdk` | 微信 JSSDK 初始化配置，仅微信环境生效 | 无 |
|
||||
|
||||
`initWechatJssdk` 子配置：
|
||||
|
||||
| 配置 | 说明 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `apiUrl` | 微信 JSSDK 签名配置接口地址；未传 `sdkConfig` 时会请求该接口，并自动携带当前页面 URL 参数 | 无 |
|
||||
| `sdkConfig` | 直接传入微信 JSSDK 签名配置；配置后不再请求 `apiUrl` | 无 |
|
||||
| `sdkConfig.debug` | 是否开启微信 JSSDK 调试模式 | `false` |
|
||||
| `sdkConfig.appId` | 微信公众平台应用 ID | 必填 |
|
||||
| `sdkConfig.timestamp` | 签名时间戳 | 必填 |
|
||||
| `sdkConfig.nonceStr` | 签名随机字符串 | 必填 |
|
||||
| `sdkConfig.signature` | 微信 JSSDK 签名 | 必填 |
|
||||
| `sdkUrl` | 微信 JSSDK 脚本地址 | `https://res.wx.qq.com/open/js/jweixin-1.6.0.js` |
|
||||
| `jsApiList` | 微信 JSSDK JS-API 列表，SDK 会自动追加 `scanQRCode` | `["scanQRCode"]` |
|
||||
|
||||
## 桥接接入
|
||||
|
||||
桥接对象需要挂载到 `window[bridgeName]`，并实现 `call(method, data)`。
|
||||
|
||||
SDK 会调用：
|
||||
|
||||
- `startScan`
|
||||
- `stopScan`
|
||||
|
||||
异步回调方法名为 `${bridgeName}_handle_callback`。
|
||||
|
||||
```js
|
||||
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 接入
|
||||
|
||||
配置接口方式：
|
||||
|
||||
```js
|
||||
IScan.config({
|
||||
initWechatJssdk: {
|
||||
apiUrl: "https://your-domain.com/wechat/jssdk-config"
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
接口会收到当前页面 URL 参数：`url=location.href.split("#")[0]`。
|
||||
|
||||
也可以直接传入微信签名配置：
|
||||
|
||||
```js
|
||||
IScan.config({
|
||||
initWechatJssdk: {
|
||||
apiUrl: "",
|
||||
sdkConfig: {
|
||||
appId: "wx_app_id",
|
||||
timestamp: 123456,
|
||||
nonceStr: "nonce",
|
||||
signature: "signature"
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
`jsApiList` 会默认追加 `scanQRCode`。
|
||||
|
||||
## API
|
||||
|
||||
### `config(options?): Promise<any>`
|
||||
|
||||
配置并初始化 SDK。
|
||||
|
||||
```js
|
||||
IScan.config({
|
||||
webScanCanvasEnabled: true
|
||||
});
|
||||
```
|
||||
|
||||
### `setStatusListener(callback): void`
|
||||
|
||||
监听扫码状态，状态为：
|
||||
|
||||
- `scanning`
|
||||
- `closed`
|
||||
|
||||
```js
|
||||
IScan.setStatusListener(function (status) {
|
||||
console.log(status);
|
||||
});
|
||||
```
|
||||
|
||||
### `onScanListener(callback, key, match?, level?): ScanListenerInfo`
|
||||
|
||||
添加扫码结果监听。
|
||||
|
||||
```js
|
||||
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。
|
||||
|
||||
```js
|
||||
IScan.offScanListener("order");
|
||||
listener.cancel();
|
||||
```
|
||||
|
||||
### `getStatus(): "scanning" | "ready"`
|
||||
|
||||
获取当前扫码状态。
|
||||
|
||||
```js
|
||||
console.log(IScan.getStatus());
|
||||
```
|
||||
|
||||
### `startScan(): void`
|
||||
|
||||
开启扫码。SDK 会按以下顺序选择可用能力：
|
||||
|
||||
1. 桥接扫码
|
||||
2. 微信扫码
|
||||
3. Web 摄像头扫码
|
||||
4. 图片识别
|
||||
|
||||
扫码结果通过 `onScanListener` 回调。
|
||||
|
||||
```js
|
||||
IScan.startScan();
|
||||
```
|
||||
|
||||
### `scanVideo(): void`
|
||||
|
||||
直接开启 Web 摄像头扫码。扫码结果通过 `onScanListener` 回调。
|
||||
|
||||
```js
|
||||
IScan.scanVideo();
|
||||
```
|
||||
|
||||
### `scanImage(): void`
|
||||
|
||||
直接选择图片进行识别。识别结果通过 `onScanListener` 回调。
|
||||
|
||||
```js
|
||||
IScan.scanImage();
|
||||
```
|
||||
|
||||
### `stopScan(): void`
|
||||
|
||||
停止当前扫码。
|
||||
|
||||
```js
|
||||
IScan.stopScan();
|
||||
```
|
||||
|
||||
### `clear(): void`
|
||||
|
||||
清空全部扫码监听。
|
||||
|
||||
```js
|
||||
IScan.clear();
|
||||
```
|
||||
|
||||
## 类型
|
||||
|
||||
```ts
|
||||
interface ScanResult {
|
||||
result: string;
|
||||
key: string;
|
||||
}
|
||||
|
||||
type ScanStatus = "scanning" | "ready";
|
||||
|
||||
type ScanResultCallback = (result: ScanResult) => any;
|
||||
type ScanStatusCallback = (status: ScanStatus) => any;
|
||||
```
|
||||
|
||||
## 开发
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
构建产物输出到 `dist` 目录。
|
||||
Reference in New Issue
Block a user