更新记录

1.0.59（2026-06-25）

• 修复 iOS 云打包在较低 deploymentTarget 下 Swift 编译失败的问题：connectedScenes / UIWindowScene 仅 iOS 13.0 可用，现在已加入 #available(iOS 13.0, *) 分支，低版本构建目标下回退到 keyWindow/windows 解析根控制器。
• Android / iOS 运行诊断标识随发布升级为 lizhao-scan-pro/android@1.0.59、lizhao-scan-pro/ios@1.0.59，uni-app x 示例 TRACE 标识同步到 2026-06-25-uniappx-scan-1.0.59。
• 已通过 uni-app x app-ios appResource 导出验证，确认本轮 Swift 编译错误不再阻塞 iOS 打包。
• 本次不修改扫码公共 API、参数结构或识别算法；iOS 原生桥接文件有变更，发布或真机验证前仍需重新制作并安装 iOS 自定义基座或正式包。

1.0.58（2026-06-25）

• 修复 Android 构建标识未随发布元信息同步的问题：buildInfo 更新为 lizhao-scan-pro/android@1.0.58，便于确认新自定义基座已包含 CameraX + ML Kit 依赖。
• 同步 iOS 构建标识为 lizhao-scan-pro/ios@1.0.58，保持发布包、README 与运行诊断信息一致。
• 修复 uni-app x 示例页右上角支持状态一直显示“检测中”的问题：页面 onReady 会根据当前平台刷新为“可测试”或“不支持”。
• 补充 Android uni-app x USB 真机验证记录：重新制作并安装自定义基座后，原生全屏扫码页可打开，logcat 显示 cameraReady，未再出现 android native dependency missing、camera init failed、ClassCastException 或 FATAL EXCEPTION。
• 补充相册识别验证记录：带静区二维码图片可识别为 qrCode，结果值为 SCAN_PRO_USB_TEST_20260625。
• 本次不修改公共 API、接口类型或扫码算法；Android/iOS 仅同步诊断构建标识，发布或真机验证仍需重新制作并安装对应自定义基座或正式包。

1.0.57（2026-06-15）

• 优化 README 接入说明结构：按“能力说明 -> 适合场景 -> 接入方式选择 -> 5 分钟跑通 -> 从基础到进阶 -> 特色功能一览 -> 详细 API”的顺序组织，方便客户由浅入深接入。
• 新增业务场景引导：补充普通扫码、库存盘点、一屏多个码、相册识别、近距扫码、品牌化扫码页和页面状态联动等场景说明，让客户先理解插件特色能力再查参数。
• 补充最小可运行示例和进阶示例：覆盖基础扫码、指定码制、连续扫码、同帧多码、近距小码识别和扫码页品牌化配置。
• 补充 HBuilderX 版本注意事项：建议使用 HBuilderX 5.07 及以上版本测试、运行和打包，低版本可能出现 UTS 语法校验、编译或原生联编问题。
• 修正插件内示例 README 的平台说明：不再写成“仅 Android 可用”，改为明确当前支持 Android / iOS / Harmony App 端，Web 和小程序返回不支持错误。
• 发布元信息升级：package.json.version 更新为 1.0.57，engines.HBuilderX 对齐为 >=5.07，描述补充近距聚焦与扫码页样式定制能力。
• 本次为文档与发布元信息整理，不修改 Android/iOS/Harmony 原生扫码实现；运行态 buildInfo 仍以实际自定义基座内已编译版本为准。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-scan-pro

lizhao-scan-pro 是一个面向 uni-app / uni-app x 的原生扫码 UTS API 插件。客户只需要在页面脚本中调用 API，就可以拉起原生全屏扫码界面，支持二维码、条形码、多码识别、连续扫码、相册识别、手电筒、缩放、近距聚焦和扫码页样式定制。

插件底层按平台走原生能力：Android 使用 CameraX + ML Kit，iOS 使用 AVFoundation + Vision，Harmony 使用系统扫码能力。Web 和小程序当前不伪造成功结果，会返回明确的不支持错误。

适合哪些场景

接入方式选择

5 分钟跑通

1. 使用推荐版本

建议使用 HBuilderX 5.07 及以上版本进行测试、运行和打包。低版本 HBuilderX 的 UTS 编译器可能不支持当前插件使用的部分 UTS 语法或生成规则，容易出现 UTS 语法校验、编译或原生联编问题。

2. 引入插件

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

本插件不提供 <lizhao-scan-pro /> 组件标签，统一通过 script 中的 API 调用。页面只需要 import 到插件根目录，不要直接 import utssdk 内部文件。

3. 打开扫码页

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

LizhaoScanPro.startScan({
  // 建议页面内固定一个扫描器 ID，后续停止、暂停、恢复都使用同一个 ID
  scannerId: 'main',
  // 显示相册入口，方便用户从图片中识别二维码或条形码
  enableAlbum: true,
  // 识别成功回调，单次扫码默认识别成功后返回结果
  onResult(res) {
    console.log('扫码结果：', res.value, res.format)
  },
  // 识别失败、权限异常或平台不支持时会进入这里
  onError(err) {
    console.error('扫码失败：', err)
  }
})

4. 页面离开时释放资源

onHide() {
  // 页面不可见时停止扫码，避免后台占用相机
  LizhaoScanPro.stopScan({ scannerId: 'main' })
}

onUnload() {
  // 页面销毁时彻底释放扫描器
  LizhaoScanPro.destroyScanner({ scannerId: 'main' })
}

从基础到进阶

只识别指定码制

LizhaoScanPro.startScan({
  scannerId: 'main',
  // 只识别二维码和 Code128，减少无关码制干扰
  formats: ['qrCode', 'code128'],
  onResult(res) {
    console.log('命中指定码制：', res.value)
  }
})

连续扫码和批量识别

LizhaoScanPro.startScan({
  scannerId: 'main',
  // 开启连续扫码，适合仓储、盘点、核销等连续作业
  continuous: true,
  // 两次回调至少间隔 500ms，业务侧也建议继续做去重
  continuousIntervalMs: 500,
  // 同一帧出现多个码时返回全部识别结果
  returnAllResults: true,
  onResult(res) {
    res.results.forEach((item) => {
      console.log('批量结果：', item.value, item.format)
    })
  }
})

近距小码识别

LizhaoScanPro.startScan({
  scannerId: 'main',
  // 开启近距锁焦模式，适合设备铭牌、细小标签、约 5cm 近距扫码
  nearFocusLock: true,
  // 预设缩放倍率，帮助小码在画面中更清晰
  zoomRatio: 1.8,
  // 固定码长业务可过滤明显错误的短结果
  minBarcodeLength: 8,
  onResult(res) {
    console.log('近距识别结果：', res.value)
  }
})

品牌化扫码页

LizhaoScanPro.startScan({
  scannerId: 'main',
  scanFrameStyle: {
    // 调整扫码框宽高和位置，适配业务视觉
    widthRatio: 0.72,
    heightRatio: 0.5,
    topRatio: 0.2,
    cornerRadius: 22,
    borderColor: '#88FFFFFF',
    cornerColor: '#FFFF6B6B'
  },
  uiTextConfig: {
    // 自定义提示文案和按钮文案
    tipText: '请对准二维码或条形码',
    closeText: '关闭',
    albumText: '相册',
    torchOffText: '打开手电筒',
    torchOnText: '关闭手电筒'
  },
  onResult(res) {
    console.log('扫码结果：', res.value)
  }
})

特色功能一览

支持平台

API 列表

Harmony 能力边界

Harmony 端已补齐与 Android / iOS 同名 API 与回调结构，但受系统扫码页能力限制，存在以下边界：

1. setTorchEnabled / setZoomRatio：保持状态兼容并返回成功回调，当前不直接驱动系统扫码页的手电筒和缩放。
2. startScan / pickImageAndScan：基于系统 uni.scanCode 能力，UI 形态以系统页面为准，不保证与 Android/iOS 自定义扫码页完全一致。
3. continuous=true：通过循环拉起系统扫码能力实现连续扫描，支持 continuousIntervalMs 回调间隔控制；建议业务侧继续做去重与节流。
4. showContinuousToggle：参数可接收但受系统扫码页能力限制，Harmony 当前不展示页内“单次/连续”切换按钮。
5. returnAllResults：参数可接收但受系统扫码能力限制，Harmony 当前仍按单条结果回调。
6. formats：Harmony 仅能按系统扫码大类限制（如 barCode / qrCode / datamatrix / pdf417），code39/code128/ean13 等一维细分格式会映射到 barCode。
7. minBarcodeLength：Harmony 端按识别结果长度做回调前过滤，可过滤短于阈值的一维码结果，但不能提升系统扫码页本身的识别精度。
8. beepOnScan / vibrateOnScan：Android / iOS 按插件原生链路处理；Harmony 当前暂不承诺震动/提示音生效，以系统扫码页行为为准。

参数说明（ScanOptions）

扫码框样式配置（scanFrameStyle）

scanFrameStyle 仅作用于 Android / iOS 全屏原生扫码页：

1. 不传时保持历史默认扫码框样式（零破坏兼容）。
2. 比例参数使用 0~1 坐标系：widthRatio / heightRatio / topRatio。
3. cornerRadius 单位：Android 按 dp、iOS 按 pt。
4. showScanFrame=false 时，scanFrameStyle 整体忽略。
5. showCorners=false 时隐藏四个顶角，仅保留边框与扫描线。
6. 字段缺失或非法值自动回退默认值，不抛错、不影响扫码链路。

参数结构：

默认行为示例（不传 scanFrameStyle）：

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

LizhaoScanPro.startScan({
  // 扫描会话 ID；后续 stop/pause/resume/destroy 需传同一个值
  scannerId: 'main',
  // 是否显示默认扫码框与遮罩层
  showScanFrame: true,
  // 识别成功回调（单次/连续结果都从这里返回）
  onResult(res) {
    console.log(res)
  }
})

自定义样式示例：

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

LizhaoScanPro.startScan({
  // 扫描会话 ID
  scannerId: 'main',
  // 启用扫码框渲染（scanFrameStyle 仅在此为 true 时生效）
  showScanFrame: true,
  scanFrameStyle: {
    // 扫码框宽度占屏宽比例（0~1）
    widthRatio: 0.72,
    // 扫码框高度占屏高比例（0~1）
    heightRatio: 0.5,
    // 扫码框顶部距屏幕顶部比例（0~1）
    topRatio: 0.2,
    // 圆角：Android=dp，iOS=pt
    cornerRadius: 22,
    // 是否显示四个顶角
    showCorners: true,
    // 边框颜色（支持 #RRGGBB / #AARRGGBB）
    borderColor: '#88FFFFFF',
    // 顶角颜色（仅影响顶角，不影响边框）
    cornerColor: '#FFFF6B6B'
  },
  // 识别成功回调
  onResult(res) {
    console.log(res)
  }
})

黑色遮罩独立开关示例（仅隐藏黑色遮罩，保留扫码框/扫描线）：

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

LizhaoScanPro.startScan({
  scannerId: 'main',
  // 继续显示扫码框与扫描线
  showScanFrame: true,
  // 仅隐藏黑色遮罩层
  showMaskOverlay: false,
  onResult(res) {
    console.log(res)
  }
})

扫码页文案/图标配置（uiTextConfig）

uiTextConfig 仅作用于 Android / iOS 全屏原生扫码页，支持以下三种配置方式：

1. 仅图标：{ closeIcon: "✕" }
2. 仅文案：{ closeText: "返回" }
3. 图标 + 文案：{ closeIcon: "✕", closeText: "关闭" }

提示：

1. tipText（旧字段）继续可用，若同时传 uiTextConfig.tipText，优先使用 uiTextConfig.tipText。
2. torchIcon 会同时作用于手电按钮的开/关/不支持文案。
3. 未配置的字段自动回退到默认文案，不影响历史行为。

扫码页图片图标配置（uiImageConfig）

uiImageConfig 仅作用于 Android / iOS 全屏原生扫码页，推荐配合 uiTextConfig 使用：

1. 仅图标：只传图片图标，文本字段留空（例如 close 只传 src）。
2. 仅文案：不传 uiImageConfig，只传 uiTextConfig 文案字段。
3. 图标 + 文案：同时传 uiImageConfig 与 uiTextConfig 对应字段。

图标来源支持：

1. 本地文件路径（如 /storage/...、应用沙盒路径）
2. file:// / content:// URI
3. data:image/*;base64,...
4. 应用静态资源路径（如 static/xxx.png、_www/static/xxx.png）

静态资源路径建议：

1. 优先传 static/xxx.png 或 /static/xxx.png（推荐）。
2. _www/static/xxx.png 也兼容，但通常不需要业务层手动加 _www 前缀。
3. 若业务需要固定为绝对路径，可在页面侧用 plus.io.convertLocalFileSystemURL('_www/static/xxx.png') 转换后再传入。

本地 static 图片示例（Android / iOS）：

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

function resolveUiImagePath(path: string): string {
  // 统一路径分隔符并去除首尾空白
  const normalized = String(path || '').replace(/\\/g, '/').trim()
  if (!normalized) {
    return normalized
  }
  // #ifdef APP-PLUS
  try {
    // 兼容传入 static/xxx.png 或 /static/xxx.png 的写法
    const plusLocalPath = normalized.startsWith('_www/')
      ? normalized
      : `_www/${normalized.replace(/^\/+/, '')}`
    return plus.io.convertLocalFileSystemURL(plusLocalPath) || normalized
  } catch (_) {
    // plus 不可用时回退原始路径（例如非 App 环境文档预览）
    return normalized
  }
  // #endif
  return normalized
}

LizhaoScanPro.startScan({
  // 扫描会话 ID
  scannerId: 'main',
  // 关闭按钮/相册/手电等按钮胶囊背景（适合 icon-only 风格）
  showActionCapsuleBackground: false,
  uiTextConfig: {
    // icon-only 场景：文本置空
    closeText: '',
    albumText: '',
    torchOnText: '',
    torchOffText: '',
    // 底部提示文案
    tipText: '请对准二维码'
  },
  uiImageConfig: {
    // 左上角关闭图标（src 支持 static/file/content/data URI）
    close: { src: resolveUiImagePath('/static/logo.png'), width: 18, height: 18 },
    // 右上角相册图标（需同时 enableAlbum=true 才会显示按钮）
    album: { src: resolveUiImagePath('/static/logo.png'), width: 18, height: 18 },
    // 手电开启态图标
    torchOn: { src: resolveUiImagePath('/static/logo.png'), width: 16, height: 16 },
    // 手电关闭态图标
    torchOff: { src: resolveUiImagePath('/static/logo.png'), width: 16, height: 16 },
    // 底部提示区图标
    tip: { src: resolveUiImagePath('/static/logo.png'), width: 18, height: 18 }
  }
})

tintColor 使用建议：

1. 彩色图标建议不传 tintColor，保持原图颜色（iOS 默认 alwaysOriginal 渲染）。
2. 单色图标需要统一着色时再传 tintColor（如 #FFFFFF）。

参数结构：

ScanUiImageItem 字段说明：

扫码页偏移配置（uiLayoutConfig）

uiLayoutConfig 仅作用于 Android / iOS 全屏原生扫码页，用于解决“隐藏胶囊后图标离边太远”场景：

1. 坐标语义统一：x > 0 向右，y > 0 向下；支持负值。
2. 单位：Android 按 dp、iOS 按 pt。
3. 未传字段按 0 处理，不影响旧布局。

参数结构：

ScanUiElementLayout 字段说明：

顶栏 icon-only 贴边示例：

LizhaoScanPro.startScan({
  // 建议固定 scannerId，便于在生命周期中释放资源
  scannerId: 'main',
  // 关闭按钮胶囊背景，配合 icon-only 更简洁
  showActionCapsuleBackground: false,
  // 文本置空，仅展示图标
  uiTextConfig: {
    closeText: '',
    albumText: ''
  },
  // 细调顶部按钮位置（Android=dp，iOS=pt）
  uiLayoutConfig: {
    close: {
      // 整个关闭按钮容器向左偏移
      containerOffset: { x: -12, y: 0 },
      // 图标相对容器再微调
      iconOffset: { x: -2, y: 0 }
    },
    album: {
      // 整个相册按钮容器向右偏移
      containerOffset: { x: 12, y: 0 },
      // 图标相对容器再微调
      iconOffset: { x: 2, y: 0 }
    }
  }
})

胶囊背景控制：

1. 默认 showActionCapsuleBackground=true，保持历史胶囊样式。
2. 传 showActionCapsuleBackground=false 时，顶部/底部操作按钮不渲染胶囊底和描边。
3. 该开关对“关闭/相册/单次连续/手电”统一生效，适合纯图标视觉风格。

底层实现说明：

1. Android：原生页按钮使用“容器 + 独立 icon/text 子视图”渲染，支持 containerOffset / iconOffset / textOffset 三层偏移。
2. iOS：原生页按钮使用 UIButton + UIImage 渲染图标（支持尺寸缩放与 tintColor，默认保持原图色彩，不受系统蓝色模板渲染影响）。
3. 传参方式：统一通过 startScan({ uiImageConfig: {...} }) 传入，不需要额外调用其他 API。

回调说明（startScan）

说明：startScan 结果流默认通过 options.onResult/options.onError 回调返回。options.onOverlayEvent 属于高级通道，需同时配置 overlayConfig.enabled=true 才会触发。 说明：不使用遮罩事件时，建议不要传 options.onOverlayEvent，可减少页面销毁后回调释放日志。 说明：returnAllResults=true 时，onResult(res) 的 res.results 会携带同帧多码结果；默认 false 保持单码回调行为。 说明：Android 相机扫码 / 相册识别、iOS 相机扫码支持 minBarcodeLength 一维条码最小长度过滤；Harmony 端按识别结果长度做回调前过滤。固定长度业务可直接过滤近距失焦、倾斜或轻微拖影时出现的短码片段；过滤后会优先返回码值更长的一维码，长度一致时再按识别框面积选择；Android 相机扫码还会在前 8 帧或约 1.2s 内合并一维码候选择长，避免 minBarcodeLength 小于实际码长时首帧短码立即回调；二维码等二维格式不受该字段影响。 说明：iOS 实时扫码默认先走 AVCaptureMetadataOutput 快速识别；当竖向、反光或轻微虚焦的一维条码没有 metadata 回调时，会低频抽取视频帧交给 Vision 兜底识别，成功后仍沿用原有 onResult、去重与 minBarcodeLength 过滤逻辑。 说明：连续扫码中同一数字 Code39/Code128 已返回较长结果后，后续短码子序列会被过滤，减少同一标签结果从 2000000031 回退到 20000031。 建议：业务已知码制时，优先通过 formats 只保留需要的格式；若码值固定长度，务必同时传 minBarcodeLength，例如本场景应传 formats: ['code39'], minBarcodeLength: 10，可过滤 20000031 这类短码片段且不会额外等待冷启动窗口。 建议：15 位纯数字 ITF / Interleaved 2 of 5 设备码场景应传 formats: ['itf'], minBarcodeLength: 15；iOS 会同时启用 itf14 与 interleaved2of5，避免只支持 ITF-14 导致普通 ITF 无法识别。

Data Matrix / 反色 DM 码说明

识别 DM 码时建议显式传 formats: ['dataMatrix']，减少 Android ML Kit 与 iOS Vision 的无关码制候选。

Android 端自 lizhao-scan-pro/android@1.0.54 起针对 Data Matrix 增强；lizhao-scan-pro/android@1.0.55 继续保留该增强并升级 Android 原生依赖以兼容 16 KB page size；lizhao-scan-pro/android@1.0.56 将 ML Kit 帧回调切到 cameraExecutor 并对 DM Bitmap 兜底节流，避免进入预览后出现预览卡顿，同时修复扫码成功后退出全屏界面时晚到回调触发 RejectedExecutionException 的闪退问题：

1. 常规整帧识别无结果时，会按可视扫码框做中心裁剪后再次识别，让 DM 码更接近 ML Kit 输入图中心。
2. 中心裁剪仍无结果时，会对裁剪图做反色重试，用于黑底白点这类反色 DM 码。
3. 该增强仅在请求包含 dataMatrix 或未限制码制时启用；未限制码制时已做低频兜底节流，不影响普通二维码/条形码主链路的实时预览。
4. 反色 DM 码仍受清晰度、反光、焦距、打标质量影响；建议客户提供实物样张做 Android 真机确认。

示例：

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

LizhaoScanPro.startScan({
  scannerId: 'dm-main',
  // DM / Data Matrix 码制固定这样传，大小写需保持 dataMatrix
  formats: ['dataMatrix'],
  // 近距离小码建议开启近距锁焦
  nearFocusLock: true,
  // 现场较暗时可打开手电
  enableTorch: true,
  onResult(res) {
    console.log('DM扫码结果', res.results[0].value)
  },
  onError(err) {
    console.error('DM扫码失败', err)
  },
  onOverlayEvent(event) {
    console.log('扫码诊断事件', event)
  },
  overlayConfig: {
    enabled: true
  }
})

连续扫描说明

continuous=true 时，扫码界面保持打开并持续返回 onResult，适用于批量入库、流水线录入等场景。
可选传 continuousIntervalMs 控制连续回调最小间隔（默认 0，即不额外延迟）。 当 continuousIntervalMs 传入负数或无效值时，按 0 处理。

建议：

1. 业务侧对 onResult 做去重或节流（插件内部会对相同码值做约 900ms 短窗口去重，但建议业务侧保底）。
2. 在页面 onHide/onUnload 中调用 stopScan/destroyScanner 主动释放会话。
3. 若业务需要同帧多码，请传 returnAllResults=true 并按 res.results 批量处理。

相册识别说明（Android / iOS / Harmony）

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

Android / iOS 扫码页面按钮文案（Harmony 以系统页面为准）：

1. 左上角：关闭
2. 右上角（启用相册时）：相册
3. 底部操作区（showContinuousToggle=true 时）：单次扫码 / 连续扫码 与 打开手电筒 / 关闭手电 同一行左右并排、整体居中
4. 底部中间（showContinuousToggle=false 且设备支持闪光灯时）：打开手电筒 / 关闭手电
5. Android / iOS 支持点击扫码画面触发重新聚焦（启动时也会自动执行一次近景优先聚焦）
6. Android / iOS 点击对焦时会显示短暂聚焦提示框，便于确认“已触发对焦”
7. Android / iOS 传 nearFocusLock=true 时，会保持近距辅助缩放策略，提升近距离（约 5cm）对焦稳定性
8. Android / iOS 传 showActionCapsuleBackground=false 时，可关闭“关闭/相册/单次连续/手电”按钮胶囊背景

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

说明：

1. Android 一般无需额外存储权限（使用系统 Picker 返回授权 URI）；iOS 走系统相册选择器并受 NSPhotoLibraryUsageDescription 约束；Harmony 走系统扫码页相册入口，权限与系统实现保持一致。
2. 识别成功时会触发 options.onResult，并回调 options.success/complete。
3. 用户取消选择时返回 9010008。
4. 图片中无可识别码时返回 9010006。
5. 如需识别成功提示音/短震动，请在 startScan 或 pickImageAndScan 中传 beepOnScan/vibrateOnScan=true（默认 false）；Harmony 当前暂不承诺震动/提示音生效，以系统扫码页行为为准。
6. returnAllResults=true 在 Android 相册识别生效；iOS/Harmony 相册识别当前仍返回单条结果。

示例：

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

LizhaoScanPro.pickImageAndScan({
  // 扫描会话 ID（用于区分不同业务会话）
  scannerId: 'main',
  // 指定相册识别格式，减少无关格式扫描开销
  formats: ['qrCode', 'code128', 'ean13'],
  // 识别成功时播放提示音
  beepOnScan: true,
  // 识别成功时触发短震动
  vibrateOnScan: true,
  // 识别成功回调
  onResult(res) {
    console.log('album scan result', res)
  },
  // 识别失败回调（如 9010006 / 9010008）
  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({
  // 扫描会话 ID
  scannerId: 'main',
  // 限定识别格式，提升识别稳定性和效率
  formats: ['qrCode', 'code128'],
  // 连续扫码模式（扫码页不会自动关闭）
  continuous: true,
  // 启用右上角相册入口
  enableAlbum: true,
  // 近距锁焦（Android/iOS）
  nearFocusLock: true,
  // 隐藏默认扫码框，仅保留扫描线
  showScanFrame: false,
  // 开启 overlay 事件通道（onOverlayEvent 才会触发）
  overlayConfig: {
    enabled: true
  },
  // 识别成功回调
  onResult(res) {
    console.log('scan result', res)
  },
  // 识别失败回调
  onError(err) {
    console.error('scan error', err)
  },
  // 原生层事件回调（shown/cameraReady/recognized/...）
  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 'continuousChanged':
        console.log('mode changed:', 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：NSCameraUsageDescription、NSPhotoLibraryUsageDescription（扫码与相册识别）
• Harmony：依赖系统扫码能力与系统权限弹窗策略

自定义基座说明

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

• Android CameraX / ML Kit 依赖
• AndroidManifest 权限
• Android utssdk/app-android/ScanCaptureNative.kt 原生链路变更
• iOS Info.plist / PrivacyInfo.xcprivacy
• iOS utssdk/app-ios/index.uts 或 ScanIosBridge.swift 原生链路变更

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

如果直接使用普通调试基座运行，Android 侧可能出现 androidx.camera.* 或 com.google.android.gms.tasks.* 类缺失，表现为无法打开扫码界面。此时必须重新编译并安装自定义基座或原生安装包。 当前发布包的运行诊断标识为 lizhao-scan-pro/android@1.0.59、lizhao-scan-pro/ios@1.0.59。Android 16 KB page size、预览卡顿、扫码成功后退出闪退修复、iOS 13 API 可用性保护以及本次 buildInfo 同步均涉及自定义基座内的原生/平台代码，发布或真机验证前需要重新制作并安装 Android/iOS 自定义基座或正式包；可通过 onOverlayEvent 的 buildInfo 确认真机运行版本。

Android 16 KB page size 说明：

1. 旧版 androidx.camera:camera-core:1.3.3 会带入 libimage_processing_util_jni.so，旧版 com.google.mlkit:barcode-scanning:17.2.0 会带入 libbarhopper_v3.so；这两个库在旧调试包中均可能表现为 4 KB ELF 对齐，从而触发 Google Play 的 16 KB page size 检查。
2. 当前版本已将 CameraX 升级到 1.4.2，将 ML Kit Barcode Scanning 升级到 17.3.0；重新打包后应以最终 AAB/APK 中的 .so 为准再次验证。
3. 只替换 uni_modules 文件但不重新制作 Android 自定义基座，设备和上架包仍可能使用旧 .so，无法解决 Google Play 拦截。

建议步骤：

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

完整组合示例（uni-app）

如果已经跑通前面的最小示例，可以参考下面的组合写法一次性启用多码识别、连续扫码、相册入口、自定义文案和图片图标。完整页面示例可查看 uni_modules/lizhao-scan-pro/example/index.vue 或项目页面 pages/scan/scan.vue。

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

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

LizhaoScanPro.startScan({
  // 扫描会话 ID；建议页面内固定值
  scannerId: 'main',
  // 仅识别二维码和 code128
  formats: ['qrCode', 'code128'],
  // 同帧多码回传（默认 false）
  returnAllResults: true,
  // 连续扫码模式
  continuous: true,
  // 连续回调最小间隔（ms）
  continuousIntervalMs: 500,
  // 显示“单次/连续”切换按钮
  showContinuousToggle: true,
  // 隐藏操作胶囊背景（保留按钮能力）
  showActionCapsuleBackground: false,
  // 显示相册入口
  enableAlbum: true,
  uiTextConfig: {
    // 底部提示图标（emoji 或文本图标）
    tipIcon: '📷',
    // 底部提示文案
    tipText: '请对准二维码',
    // 左上角关闭按钮图标/文案
    closeIcon: '✕',
    closeText: '关闭',
    // 右上角相册按钮图标/文案
    albumIcon: '🖼',
    albumText: '相册',
    // 底部手电按钮图标/开关文案
    torchIcon: '🔦',
    torchOnText: '关闭手电',
    torchOffText: '打开手电筒'
  },
  uiImageConfig: {
    // 可传本地路径、file://、content://、data URI、static 资源路径
    // 彩色图标建议不传 tintColor；需要统一单色时再传 tintColor（如 #FFFFFF）。
    close: { src: 'static/scan-icons/close.png', width: 18, height: 18 },
    album: { src: 'static/scan-icons/album.png', width: 18, height: 18 },
    torchOn: { src: 'static/scan-icons/torch-on.png', width: 16, height: 16 },
    torchOff: { src: 'static/scan-icons/torch-off.png', width: 16, height: 16 },
    tip: { src: 'static/scan-icons/tip.png', width: 18, height: 18 }
  },
  // 识别成功回调（returnAllResults=true 时 res.results 可能有多条）
  onResult(res) {
    res.results.forEach((item) => {
      console.log(item.value, item.format)
    })
  },
  // 识别失败回调
  onError(err) {
    console.error(err)
  }
})

页面生命周期建议

onHide() {
  // 页面不可见时先停扫码（避免后台占用相机）
  LizhaoScanPro.stopScan({ scannerId: 'main' })
}

onUnload() {
  // 页面销毁时彻底释放扫描器资源
  LizhaoScanPro.destroyScanner({ scannerId: 'main' })
}

完整组合示例（uni-app x）

uni-app x 同样通过插件根目录导入 API。下面示例展示扫码启动后再动态控制手电和缩放，适合需要在页面按钮中调整扫码状态的场景。

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

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

LizhaoScanPro.startScan({
  // 扫描会话 ID（需与后续 setTorch/setZoom 一致）
  scannerId: 'main',
  // 开启连续扫码，便于演示动态调参
  continuous: true,
  // 显示手电按钮（部分业务可选）
  enableTorch: true,
  onResult(res) {
    console.log('uni-app x scan result', res)
  },
  onError(err) {
    console.error('uni-app x scan error', err)
  }
})

// 动态打开手电（仅设备支持时生效）
LizhaoScanPro.setTorchEnabled({
  scannerId: 'main',
  enabled: true
})

// 动态设置缩放倍率（>0）
LizhaoScanPro.setZoomRatio({
  scannerId: 'main',
  zoomRatio: 1.8
})

// 页面离开时释放资源（示例）
// onHide() {
//   LizhaoScanPro.stopScan({ scannerId: 'main' })
// }
// onUnload() {
//   LizhaoScanPro.destroyScanner({ scannerId: 'main' })
// }

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

发布前自检清单

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 且文档说明一致。

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。