598 lines
17 KiB
TypeScript
598 lines
17 KiB
TypeScript
/**
|
||
* 扫码初始化选项
|
||
*/
|
||
interface ScanConfigOptions {
|
||
/**
|
||
* 扫码重启延迟，单位：毫秒，默认500ms
|
||
*/
|
||
scanRestartDelay?: number,
|
||
/**
|
||
* iframe 场景下是否将 API 调用转发到父页面同名 SDK（postMessage）。
|
||
* - `'auto'`（默认）：处于子 frame 时 `startScan` 等由父页执行；`onScanListener` 仅注册在 iframe 内，识别结果由父页 `postMessage` 回传
|
||
* - `true` / `'on'` / `'parent'`：存在父 window 时强制转发
|
||
* - `false` / `'off'` / `'local'`：始终在本页执行（子页自己要跑扫码时用）
|
||
*/
|
||
embedProxyMode?: 'auto' | boolean | 'on' | 'off' | 'local' | 'parent',
|
||
/**
|
||
* 请求微信 JS-SDK 签名时使用的页面 URL（不含 hash）。
|
||
* 跨域 iframe 无法读取父页地址时需手动设为当前微信内打开的页面链接。
|
||
*/
|
||
wxJssdkSignatureUrl?: string,
|
||
/**
|
||
* 页面 URL 变化后是否自动重新初始化微信 JSSDK（默认 true，避免扫一扫失效）
|
||
*/
|
||
wxJssdkAutoReinitOnUrlChange?: boolean,
|
||
/**
|
||
* URL 轮询检测间隔（毫秒），用于捕获未走 history API 的 SPA 路由；默认 1000，设为 0 关闭
|
||
*/
|
||
wxJssdkUrlPollInterval?: number,
|
||
/**
|
||
* 桥接是否启用，默认启用
|
||
*/
|
||
bridgeEnabled?: boolean,
|
||
/**
|
||
* 桥接名称，默认：__bridge_client__
|
||
* 桥接需实现call方法，并暴露在window上，并通过${bridgeName}_handle_callback方法处理回调
|
||
* 示例：
|
||
* window.${bridgeName} = {
|
||
* call: function (method, { data, request_id }): any {
|
||
* // 处理请求
|
||
* // 异步返回结果
|
||
* ${bridgeName}_handle_callback({
|
||
* code: 0, // 0成功，其他失败
|
||
* method, // 方法名
|
||
* payload: result, // 返回结果
|
||
* request_id // 请求id
|
||
* });
|
||
* // 同步返回结果
|
||
* return result;
|
||
* }
|
||
* }
|
||
* 需要实现以下方法：
|
||
* 1. 发起扫码的方法名称为：startScan
|
||
* 2. 结束扫码的方法名称为：stopScan
|
||
*/
|
||
bridgeName?: string,
|
||
/**
|
||
* 桥接扫码超时（毫秒），超时后回退 Web/图片识别，默认 5000
|
||
*/
|
||
bridgeScanTimeout?: number,
|
||
/**
|
||
* 是否允许 H5 摄像头扫码：true 强制开启（仍需有媒体 API），false 强制关闭
|
||
*/
|
||
webScanCameraEnabled?: boolean,
|
||
/**
|
||
* startScan 走 Web 摄像头前是否展示权限说明弹窗，默认 true
|
||
*/
|
||
webScanCameraPermissionDialogEnabled?: boolean,
|
||
/**
|
||
* 摄像头权限说明弹窗标题
|
||
*/
|
||
webScanCameraPermissionTitle?: string,
|
||
/**
|
||
* 摄像头权限说明弹窗正文
|
||
*/
|
||
webScanCameraPermissionMessage?: string,
|
||
/**
|
||
* 摄像头权限说明弹窗确认按钮文案
|
||
*/
|
||
webScanCameraPermissionConfirmText?: string,
|
||
/**
|
||
* 摄像头权限说明弹窗取消按钮文案
|
||
*/
|
||
webScanCameraPermissionCancelText?: string,
|
||
/**
|
||
* 选图后延迟读取 file 对象（毫秒），微信/安卓 WebView 默认 100
|
||
*/
|
||
webScanFileReadDelay?: number,
|
||
/**
|
||
* 强制使用 WASM ponyfill 识别（微信/部分 WebView 建议开启，默认微信内自动开启）
|
||
*/
|
||
webScanPreferPonyfill?: boolean,
|
||
/**
|
||
* WASM 文件完整 URL；未配置时相对 SDK 脚本地址解析 lib/reader.wasm
|
||
*/
|
||
webScanWasmUrl?: string,
|
||
/**
|
||
* WASM 基准路径（SDK 脚本 URL 或目录）；用于 async/defer 加载时修正 reader.wasm 路径
|
||
*/
|
||
webScanWasmBaseUrl?: string,
|
||
/**
|
||
* webScan是否启用，默认启用
|
||
*/
|
||
webScanEnabled?: boolean,
|
||
/**
|
||
* 网页扫码canvas是否启用，默认启用
|
||
*/
|
||
webScanCanvasEnabled?: boolean,
|
||
/**
|
||
* 网页扫码canvas样式，默认：PC 为左上角固定 300×300；移动端为 min(视口宽, 视口高) 的正方形，固定在左上角；z-index: 9999
|
||
*/
|
||
webScanCanvasStyle?: string,
|
||
/**
|
||
* 网页扫码canvas关闭按钮样式，默认显示在canvas右上角
|
||
*/
|
||
webScanCloseButtonStyle?: string,
|
||
/**
|
||
* 网页扫码 canvas 根元素的 class，便于配合外部样式表定制布局与外观
|
||
*/
|
||
webScanCanvasClass?: string,
|
||
/**
|
||
* 网页扫码关闭按钮的 class
|
||
*/
|
||
webScanCloseButtonClass?: string,
|
||
/**
|
||
* Canvas 开启且支持图片识别时，关闭按钮下方的「选图」按钮样式（fixed 定位基准由 SDK 计算，可与关闭按钮一致覆盖）
|
||
*/
|
||
webScanPickImageButtonStyle?: string,
|
||
/**
|
||
* 网页扫码选图按钮的 class
|
||
*/
|
||
webScanPickImageButtonClass?: string,
|
||
/**
|
||
* 网页扫码类型，默认支持二维码和条码
|
||
*/
|
||
webScanType?: ('qrCode' | 'barCode')[],
|
||
/**
|
||
* 网页扫码视频是否镜像，默认自动判断：前置/PC镜像，后置不镜像
|
||
*/
|
||
webScanVideoMirror?: boolean,
|
||
/**
|
||
* 网页扫码视频是否垂直镜像，默认不镜像
|
||
*/
|
||
webScanVideoMirrorVertical?: boolean,
|
||
/**
|
||
* 摄像头不可用（如部分安卓内置浏览器禁用 getUserMedia）时是否自动回退为拍照/选图识别，默认启用
|
||
*/
|
||
webScanImageFallbackOnVideoError?: boolean,
|
||
/**
|
||
* 打开摄像头超时时间（毫秒），超时后触发图片回退，默认 10000
|
||
*/
|
||
webScanVideoAccessTimeout?: number,
|
||
/**
|
||
* 摄像头已打开但长时间无画面时触发图片回退（毫秒），默认 8000
|
||
*/
|
||
webScanVideoReadyTimeout?: number,
|
||
/**
|
||
* 图片/回退识别时 detect 超时（毫秒），默认 15000
|
||
*/
|
||
webScanDetectTimeout?: number,
|
||
/**
|
||
* 图片识别是否优先使用 ZXing ponyfill（原生 detect 在部分 WebView 可能卡住），默认 true
|
||
*/
|
||
webScanImagePreferPonyfill?: boolean,
|
||
/**
|
||
* 移动端图片回退是否使用 capture 拍照（false 为相册选图，兼容性更好），默认 false
|
||
*/
|
||
webScanImagePreferCapture?: boolean,
|
||
/**
|
||
* 图片识别是否优先 canvas 解码（安卓 WebView 建议开启），默认在安卓/微信内自动开启
|
||
*/
|
||
webScanImageDetectPreferCanvas?: boolean,
|
||
/**
|
||
* ZXing WASM 加载超时（毫秒），默认 20000
|
||
*/
|
||
webScanPrepareTimeout?: number,
|
||
/**
|
||
* 选图等待超时（毫秒），默认 120000
|
||
*/
|
||
webScanChooseImageTimeout?: number,
|
||
/**
|
||
* 选图方式：button=显示「选择图片」按钮（安卓/微信默认，需用户点击）；auto=自动弹出系统选图
|
||
*/
|
||
webScanImagePickerMode?: 'auto' | 'button',
|
||
webScanImagePickerTitle?: string,
|
||
webScanImagePickerButtonText?: string,
|
||
webScanImagePickerCancelText?: string,
|
||
/**
|
||
* 单次扫码会话超时（毫秒），超时后状态恢复 ready，默认 90000
|
||
*/
|
||
scanSessionTimeout?: number,
|
||
/**
|
||
* 扫码成功提示音地址，默认使用内置提示音；任意识别模式匹配成功时播放
|
||
*/
|
||
scanBeepAudio?: string,
|
||
/**
|
||
* 扫码成功是否播放提示音，默认启用；任意识别模式匹配成功时生效
|
||
*/
|
||
scanBeepEnabled?: boolean,
|
||
/**
|
||
* PC 微信 Native 扫码支付是否展示内置二维码弹层，默认 true
|
||
*/
|
||
paymentNativeQrEnabled?: boolean,
|
||
/**
|
||
* Native 支付二维码弹层标题
|
||
*/
|
||
paymentNativeQrTitle?: string,
|
||
/**
|
||
* Native 支付二维码弹层说明文案
|
||
*/
|
||
paymentNativeQrMessage?: string,
|
||
/**
|
||
* Native 支付二维码底部提示
|
||
*/
|
||
paymentNativeQrHint?: string,
|
||
/**
|
||
* Native 支付二维码边长（像素），默认 220
|
||
*/
|
||
paymentNativeQrSize?: number,
|
||
/**
|
||
* Native 支付二维码弹层遮罩样式
|
||
*/
|
||
paymentNativeQrOverlayStyle?: string,
|
||
/**
|
||
* Native 支付二维码弹层面板样式
|
||
*/
|
||
paymentNativeQrPanelStyle?: string,
|
||
/**
|
||
* Native 支付二维码关闭按钮样式
|
||
*/
|
||
paymentNativeQrCloseButtonStyle?: string,
|
||
/**
|
||
* Native 支付二维码弹层遮罩 class
|
||
*/
|
||
paymentNativeQrOverlayClass?: string,
|
||
/**
|
||
* Native 支付二维码弹层面板 class
|
||
*/
|
||
paymentNativeQrPanelClass?: string,
|
||
/**
|
||
* PC 支付宝表单是否使用弹层 + iframe，默认 true；false 时整页跳转
|
||
*/
|
||
paymentAlipayFormEnabled?: boolean,
|
||
/**
|
||
* 支付宝表单弹层标题
|
||
*/
|
||
paymentAlipayFormTitle?: string,
|
||
/**
|
||
* 支付宝表单弹层说明文案
|
||
*/
|
||
paymentAlipayFormMessage?: string,
|
||
/**
|
||
* 支付宝表单 iframe 高度（像素），默认 520
|
||
*/
|
||
paymentAlipayFormIframeHeight?: number,
|
||
/**
|
||
* 支付宝表单弹层遮罩样式（未配置时回退 paymentNativeQrOverlayStyle）
|
||
*/
|
||
paymentAlipayFormOverlayStyle?: string,
|
||
/**
|
||
* 支付宝表单弹层面板样式（未配置时回退 paymentNativeQrPanelStyle）
|
||
*/
|
||
paymentAlipayFormPanelStyle?: string,
|
||
/**
|
||
* 支付宝表单弹层关闭按钮样式（未配置时回退 paymentNativeQrCloseButtonStyle）
|
||
*/
|
||
paymentAlipayFormCloseButtonStyle?: string,
|
||
/**
|
||
* 支付宝表单弹层遮罩 class（未配置时回退 paymentNativeQrOverlayClass）
|
||
*/
|
||
paymentAlipayFormOverlayClass?: string,
|
||
/**
|
||
* 支付宝表单弹层面板 class（未配置时回退 paymentNativeQrPanelClass）
|
||
*/
|
||
paymentAlipayFormPanelClass?: string,
|
||
/**
|
||
* 微信支付 OAuth 配置（paymentType 为 wechat 且微信内 JSAPI 时由 requestPayment 自动处理）
|
||
*/
|
||
initWechatPayment?: {
|
||
/**
|
||
* 用 code 换 openid，对应 api.biz.wechat.oauth；
|
||
* 未配置时默认 /api?action=api.biz.wechat.oauth（若已配置 initWechatJssdk.apiUrl 则沿用其域名与路径）
|
||
*/
|
||
oauthApiUrl?: string,
|
||
/**
|
||
* 获取 OAuth 授权信息（含 appId、authorizeUrl），对应 api.biz.wechat.oauthAuthorizeUrl；
|
||
* 未配置时默认 /api?action=api.biz.wechat.oauthAuthorizeUrl（若已配置 initWechatJssdk.apiUrl 则沿用其域名与路径）
|
||
*/
|
||
oauthAuthorizeUrlApiUrl?: string,
|
||
/**
|
||
* openid 缓存 key，默认 iscan_wechat_openid_${appId}（appId 来自授权接口响应）
|
||
*/
|
||
storageKey?: string,
|
||
/**
|
||
* OAuth 授权回跳完整 URL（redirectUri），须与当前页域名一致且已在公众号登记；
|
||
* 未配置时默认使用当前页 location.href（不含 hash）
|
||
*/
|
||
redirectUri?: string,
|
||
},
|
||
/**
|
||
* 微信JSSDK配置，微信环境才会生效，配置后会自动初始化微信JSSDK
|
||
*/
|
||
initWechatJssdk: {
|
||
/**
|
||
* 微信JSSDK配置API地址，调用接口会带上当前页面url作为参数
|
||
*/
|
||
apiUrl?: string,
|
||
/**
|
||
* 微信JSSDK配置参数，不配置则自动获取
|
||
*/
|
||
sdkConfig?: {
|
||
/**
|
||
* 是否开启调试模式
|
||
*/
|
||
debug?: boolean,
|
||
/**
|
||
* 微信公众平台应用ID
|
||
*/
|
||
appId: string,
|
||
/**
|
||
* 时间戳
|
||
*/
|
||
timestamp: number,
|
||
/**
|
||
* 随机字符串
|
||
*/
|
||
nonceStr: string,
|
||
/**
|
||
* 签名
|
||
*/
|
||
signature: string,
|
||
},
|
||
/**
|
||
* 微信JSSDK配置SDK地址，默认为https://res.wx.qq.com/open/js/jweixin-1.6.0.js
|
||
*/
|
||
sdkUrl?: string,
|
||
/**
|
||
* 微信JSSDK配置JS-API列表，默认追加["scanQRCode"]
|
||
*/
|
||
jsApiList?: string[]
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 扫码选项
|
||
*/
|
||
interface ScanResult {
|
||
result: string,
|
||
key: string
|
||
}
|
||
|
||
/**
|
||
* 扫码错误
|
||
*/
|
||
interface ScanErrorInfo {
|
||
error: string,
|
||
key: string,
|
||
source?: string,
|
||
cancel?: number
|
||
}
|
||
|
||
/**
|
||
* 监听key
|
||
*/
|
||
interface ScanListenerInfo {
|
||
/**
|
||
* 监听key
|
||
*/
|
||
key?: string;
|
||
/**
|
||
* 监听匹配
|
||
*/
|
||
match?: string;
|
||
/**
|
||
* 监听级别
|
||
*/
|
||
level?: number;
|
||
/**
|
||
* 为 true 时仅接收同 key 主动扫码（startScan/scanImage 等）的结果，忽略扫码枪
|
||
*/
|
||
selfKeyOnly?: boolean;
|
||
/**
|
||
* 监听回调
|
||
*/
|
||
listener: ScanResultCallback;
|
||
/**
|
||
* 取消监听
|
||
*/
|
||
cancel: () => void;
|
||
}
|
||
|
||
/**
|
||
* 监听状态
|
||
*/
|
||
type ScanStatus = "scanning" | "ready";
|
||
|
||
/**
|
||
* 监听结果回调
|
||
*/
|
||
type ScanResultCallback = (result: ScanResult) => any;
|
||
|
||
/**
|
||
* 监听扫码错误回调
|
||
*/
|
||
type ScanErrorCallback = (error: ScanErrorInfo) => any;
|
||
|
||
/**
|
||
* 扫码错误监听信息
|
||
*/
|
||
interface ScanErrorListenerInfo {
|
||
key?: string;
|
||
match?: string;
|
||
level?: number;
|
||
listener: ScanErrorCallback;
|
||
cancel: () => void;
|
||
}
|
||
|
||
/**
|
||
* 监听状态回调
|
||
*/
|
||
type ScanStatusCallback = (status: ScanStatus) => any;
|
||
|
||
/**
|
||
* 支付渠道
|
||
*/
|
||
type PaymentType = 'wechat' | 'alipay';
|
||
|
||
/**
|
||
* JSAPI 收银台交互结果（仅表示用户在收银台的操作，非支付到账结果）
|
||
*/
|
||
type PaymentCashierResult = 'ok' | 'cancel' | 'fail';
|
||
|
||
/**
|
||
* 微信支付场景
|
||
*/
|
||
type PayScene = 'jsapi' | 'h5' | 'native';
|
||
|
||
/**
|
||
* SDK 传给业务支付函数的参数（OAuth、环境判断由 SDK 自动完成）
|
||
*/
|
||
interface PaymentPrepareParams {
|
||
/** 微信 JSAPI 场景下的 openid，其他场景为空字符串 */
|
||
openid: string;
|
||
/** 当前环境对应的微信支付场景 */
|
||
payScene: PayScene;
|
||
/** navigator.userAgent */
|
||
userAgent: string;
|
||
/** 用户 IP，默认空字符串 */
|
||
clientIp: string;
|
||
/** 支付完成回跳地址 */
|
||
returnUrl: string;
|
||
/** 支付渠道 */
|
||
paymentType: PaymentType;
|
||
/** 支付金额（元），由 requestPayment 传入 */
|
||
amount?: number | string;
|
||
}
|
||
|
||
/**
|
||
* 业务支付函数：调用自己的支付接口，返回 paymentFormData
|
||
*/
|
||
type PaymentFormDataProvider = (
|
||
params: PaymentPrepareParams
|
||
) => string | Record<string, any> | Promise<string | Record<string, any>>;
|
||
|
||
/**
|
||
* SDK 发起支付后的返回（不代表支付成功，业务须自行查单）
|
||
*/
|
||
interface PaymentInvokeResult {
|
||
payType?: 'jsapi' | 'h5' | 'native' | 'alipay';
|
||
/** SDK 是否已发起支付流程 */
|
||
invoked: boolean;
|
||
/** 微信 OAuth 授权跳转中（页面将刷新，业务函数尚未执行） */
|
||
oauthRedirecting?: boolean;
|
||
/** 支付未发起（含微信 OAuth 失败） */
|
||
failed?: boolean;
|
||
/** 微信 OAuth / openid 获取失败 */
|
||
oauthFailed?: boolean;
|
||
/** OAuth 或调起失败时的错误信息 */
|
||
error?: string;
|
||
/** H5 / 移动端支付宝是否已跳转整页 */
|
||
redirected?: boolean;
|
||
/** Native 场景是否展示了二维码弹层 */
|
||
qrShown?: boolean;
|
||
/** PC 支付宝是否展示了表单弹层 */
|
||
dialogShown?: boolean;
|
||
/** 微信 JSAPI 收银台交互结果（非支付到账结果） */
|
||
cashierResult?: PaymentCashierResult;
|
||
}
|
||
|
||
/**
|
||
* 支付请求选项
|
||
*/
|
||
interface RequestPaymentOptions {
|
||
/** 支付金额（元），展示在支付弹窗；也可由业务返回 amount / totalAmount / payAmount */
|
||
amount?: number | string;
|
||
/** 货币符号，默认 CNY（¥） */
|
||
currency?: string;
|
||
/** 支付完成回跳地址，未传时使用当前页 URL */
|
||
returnUrl?: string;
|
||
/** OAuth 授权回跳完整 URL（redirectUri），覆盖 initWechatPayment.redirectUri */
|
||
redirectUri?: string;
|
||
}
|
||
|
||
/** IScan */
|
||
interface IScan {
|
||
/**
|
||
* 配置SDK
|
||
* @param options 配置选项
|
||
*/
|
||
config(options?: ScanConfigOptions): Promise<any>;
|
||
/**
|
||
* 监听扫码状态
|
||
* @param callback 监听回调
|
||
*/
|
||
setStatusListener(callback: ScanStatusCallback): void;
|
||
/**
|
||
* 添加监听扫码结果
|
||
* @param callback 监听回调
|
||
* @param key 监听key
|
||
* @param match 监听匹配
|
||
* @param level 监听级别
|
||
* @param selfKeyOnly 为 true 时仅接收同 key 主动扫码结果，忽略扫码枪
|
||
*/
|
||
onScanListener(callback: ScanResultCallback, key: string, match?: string, level?: number, selfKeyOnly?: boolean): ScanListenerInfo;
|
||
/**
|
||
* 取消监听扫码结果
|
||
* @param callback 监听回调，或监听key
|
||
*/
|
||
offScanListener(callback: ScanResultCallback | string): void;
|
||
/**
|
||
* 添加监听扫码错误（如图片识别失败）
|
||
* @param callback 错误回调
|
||
* @param key 监听 key
|
||
* @param match 可选正则，匹配 error 文本后回调
|
||
* @param level 优先级
|
||
*/
|
||
onScanErrorListener(callback: ScanErrorCallback, key: string, match?: string, level?: number): ScanErrorListenerInfo;
|
||
/**
|
||
* 取消监听扫码错误
|
||
* @param callback 监听回调，或监听 key
|
||
*/
|
||
offScanErrorListener(callback: ScanErrorCallback | string): void;
|
||
/**
|
||
* 获取扫码状态
|
||
* @returns ScanStatus
|
||
*/
|
||
getStatus(): ScanStatus;
|
||
/**
|
||
* 关闭扫码
|
||
*/
|
||
stopScan(): void;
|
||
/**
|
||
* 开启扫码（摄像头 / 桥接 / 微信等）
|
||
* @param key 可选，指定后结果仅分发给同 key 的 onScanListener
|
||
*/
|
||
startScan(key?: string): void;
|
||
/**
|
||
* 选择图片进行识别
|
||
* @param key 可选，指定后结果仅分发给同 key 的 onScanListener
|
||
*/
|
||
scanImage(key?: string): void;
|
||
/**
|
||
* 由业务/原生传入已选图片 File 识别（WebView input.files 异常时使用）
|
||
* @param file 已选图片 File
|
||
* @param key 可选，指定后结果仅分发给同 key 的 onScanListener
|
||
*/
|
||
scanImageFromFile(file: File | Blob, key?: string): void;
|
||
/**
|
||
* 清除全部监听
|
||
*/
|
||
clear(): void;
|
||
/**
|
||
* 发起支付：按 paymentType 决定是否走微信 OAuth，再将参数传给业务函数获取 paymentFormData 并调起支付。
|
||
* 不代表支付成功，业务须自行查单。
|
||
*/
|
||
requestPayment(
|
||
paymentType: PaymentType,
|
||
fetchPaymentFormData: PaymentFormDataProvider,
|
||
options?: RequestPaymentOptions
|
||
): Promise<PaymentInvokeResult>;
|
||
/**
|
||
* 关闭 SDK 管理的支付相关 UI（如 PC Native 二维码弹层、支付宝表单弹层）
|
||
*/
|
||
closePaymentDialog(): void;
|
||
|
||
}
|
||
|
||
/**
|
||
* IScan 实例
|
||
*/
|
||
declare var IScan: IScan;
|
||
|
||
/**
|
||
* 将 IScan 实例挂载到 Window 对象上
|
||
* 方便在全局使用
|
||
*/
|
||
declare interface Window {
|
||
IScan: IScan;
|
||
} |