更新记录

1.0.15（2026-03-27）

• 修复 Android 端 beepOnScan / vibrateOnScan 仅有类型与文档、未实际生效的问题。
• 扫码成功与相册识别成功后，现可按配置播放提示音与触发短震动。

1.0.14（2026-03-27）

• showScanFrame=false 时进一步去除扫码遮罩层，不再保留中间透明方框，仅保留扫描线与提示文字。
• 同步更新参数与 UI 约定文档描述。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-scan-pro

lizhao-scan-pro 是跨端 UTS 扫码插件，仅提供 API 模式；调用后直接打开原生全屏扫码界面，底层使用 UTS + CameraX + ML Kit 实现。

支持平台

安装说明

import * as LizhaoScanPro from '@/uni_modules/lizhao-scan-pro'

本插件不提供 <lizhao-scan-pro /> 组件标签，统一通过 script 中的 API 调用。 本插件不再提供 common/core.js 等 JS 包装入口，统一通过 UTS API 入口调用。

API 列表

• startScan(options)
• stopScan(options)
• pauseScan(options)
• resumeScan(options)
• setTorchEnabled(options)
• setZoomRatio(options)
• pickImageAndScan(options)
• setScanFormats(options)
• postOverlayMessage(options)
• destroyScanner(options)

参数说明（ScanOptions）

回调说明（startScan）

说明：startScan 结果流默认通过 options.onResult/options.onError 回调返回。options.onOverlayEvent 属于高级通道，需同时配置 overlayConfig.enabled=true 才会触发。 说明：不使用遮罩事件时，建议不要传 options.onOverlayEvent，可减少页面销毁后回调释放日志。

连续扫描说明

continuous=true 时，扫码界面保持打开并持续返回 onResult，适用于批量入库、流水线录入等场景。

建议：

1. 业务侧对 onResult 做去重或节流（插件内部会对相同码值做约 900ms 短窗口去重，但建议业务侧保底）。
2. 在页面 onHide/onUnload 中调用 stopScan/destroyScanner 主动释放会话。

相册识别说明（Android）

在 startScan(options) 中设置 enableAlbum=true 后，原生扫码界面右上角会显示相册按钮。 点击该按钮后会拉起系统图片选择器，识别成功后复用 startScan 的 onResult 回调返回结果。

扫码页面顶部按钮文案：

1. 左上角：关闭
2. 右上角（启用相册时）：相册

pickImageAndScan(options) 会拉起系统图片选择器，用户选图后由插件原生链路解析条码/二维码。

说明：

1. Android 一般无需额外存储权限（使用系统 Picker 返回授权 URI）。
2. 识别成功时会触发 options.onResult，并回调 options.success/complete。
3. 用户取消选择时返回 9010008。
4. 图片中无可识别码时返回 9010006。

示例：

import * as LizhaoScanPro from '@/uni_modules/lizhao-scan-pro'

LizhaoScanPro.pickImageAndScan({
  scannerId: 'main',
  formats: ['qrCode', 'code128', 'ean13'],
  onResult(res) {
    console.log('album scan result', res)
  },
  onError(err) {
    console.error('album scan error', err)
  }
})

Overlay 事件类型

onOverlayEvent 回调事件结构：

{
  type: string,
  scannerId: string,
  payload: any
}

说明：上述事件仅在 overlayConfig.enabled=true 时派发。

Overlay 事件处理示例

import * as LizhaoScanPro from '@/uni_modules/lizhao-scan-pro'

LizhaoScanPro.startScan({
  scannerId: 'main',
  formats: ['qrCode', 'code128'],
  continuous: true,
  enableAlbum: true,
  showScanFrame: false,
  overlayConfig: {
    enabled: true
  },
  onResult(res) {
    console.log('scan result', res)
  },
  onError(err) {
    console.error('scan error', err)
  },
  onOverlayEvent(event) {
    switch (event.type) {
      case 'shown':
        console.log('scanner shown')
        break
      case 'cameraReady':
        console.log('camera ready')
        break
      case 'recognized':
        console.log('recognized payload:', event.payload)
        break
      case 'error':
        console.warn('overlay error:', event.payload)
        break
      case 'closed':
        console.log('scanner closed')
        break
      case 'nativeMessage':
        console.log('native message:', event.payload)
        break
      default:
        console.log('overlay event:', event)
        break
    }
  }
})

返回值说明（ScanFrameResult）

错误码说明

权限说明

• Android：CAMERA、FLASHLIGHT、VIBRATE（相册识别走系统 Picker，通常不需要额外存储权限）
• iOS：当前版本不支持扫描实现

自定义基座说明

新增以下配置时需要自定义基座：

• Android CameraX / ML Kit 依赖
• AndroidManifest 权限
• iOS Info.plist / PrivacyInfo.xcprivacy

本插件 Android 端严格使用自研链路（UTS + CameraX + ML Kit），不依赖 Barcode/uni-barcode-scanning 模块兜底。

如果直接使用普通调试基座运行，Android 侧可能出现 androidx.camera.* 或 com.google.android.gms.tasks.* 类缺失，表现为无法打开扫码界面。此时必须重新编译并安装自定义基座或原生安装包。

建议步骤：

1. 在 HBuilderX 执行「运行 -> 运行到手机或模拟器 -> 制作自定义基座」。
2. 卸载设备上旧基座后安装新基座（避免继续复用旧依赖）。
3. 清理项目编译缓存后重新运行。

示例（uni-app）

import * as LizhaoScanPro from '@/uni_modules/lizhao-scan-pro'

const info = uni.getSystemInfoSync()
if (String(info.platform || '').toLowerCase() !== 'android') {
  console.warn('lizhao-scan-pro 当前仅支持 Android')
  return
}

LizhaoScanPro.startScan({
  scannerId: 'main',
  formats: ['qrCode', 'code128'],
  continuous: true,
  enableAlbum: true,
  onResult(res) {
    console.log(res.results)
  },
  onError(err) {
    console.error(err)
  }
})

页面生命周期建议

onHide() {
  LizhaoScanPro.stopScan({ scannerId: 'main' })
}

onUnload() {
  LizhaoScanPro.destroyScanner({ scannerId: 'main' })
}

示例（uni-app x）

import * as LizhaoScanPro from '@/uni_modules/lizhao-scan-pro'

const info = uni.getSystemInfoSync()
if (String(info.platform || '').toLowerCase() !== 'android') {
  console.warn('lizhao-scan-pro 当前仅支持 Android')
  return
}

LizhaoScanPro.setTorchEnabled({ scannerId: 'main', enabled: true })
LizhaoScanPro.setZoomRatio({ scannerId: 'main', zoomRatio: 1.8 })

发布前自检清单

1. 确认插件仅通过 @/uni_modules/lizhao-scan-pro API 入口调用。
2. 确认未使用 <lizhao-scan-pro /> 模板标签或 common/*.js 旧入口。
3. 确认 Android 自定义基座已重建并重装（含 CameraX + ML Kit 依赖）。
4. 确认扫码页在 Android 真机可拉起全屏原生界面并返回结果。
5. 确认 iOS/Harmony/Web/小程序路径返回 9010001 且文档说明一致。