更新记录

1.0.48（2026-05-06）

• 新增独立开关 showMaskOverlay（默认 true）：用于控制扫码页黑色遮罩层显隐。
• Android / iOS 双端对齐：当 showMaskOverlay=false 时仅隐藏黑色遮罩，扫码框、扫描线、提示文案与操作按钮保持原有行为。
• 兼容性声明：未传 showMaskOverlay 时保持历史视觉（黑色遮罩默认显示），不影响现有 showScanFrame 语义与回调链路。

1.0.47（2026-04-30）

• 新增扫码框顶角总开关：scanFrameStyle.showCorners（默认 true），支持在圆角场景下隐藏四个顶角，仅保留边框与扫描线。
• Android / iOS 双端对齐：borderColor 与 cornerColor 独立生效，边框色与顶角色可单独配置。
• iOS 扫码框顶角渲染升级：移除内层整框描边模拟，改为四个独立短线顶角绘制，视觉与 Android 行为一致。
• 兼容性声明：不传 showCorners 时保持历史视觉；showScanFrame=false 时继续整体忽略 scanFrameStyle。
• 新增扫码框样式配置：ScanOptions.scanFrameStyle，支持 widthRatio / heightRatio / topRatio / cornerRadius / borderColor / cornerColor。
• Android 扫码遮罩支持按配置渲染扫码框区域、圆角与颜色；未配置时保持历史默认样式不变。
• iOS 扫码框接入样式配置：支持按比例定制框体位置与尺寸、圆角与边框色；cornerColor 当前以内层描边方式同步表现。
• 兼容性声明：showScanFrame=false 时忽略 scanFrameStyle；字段缺失或非法值自动回退默认值，不影响现有回调与扫码链路。

1.0.46（2026-04-30）

• 修复 iOS 云打包 Swift 编译错误：消除 UIEdgeInsets 计算中 NSNumber 参与一元负号导致的失败（unary operator '-' cannot be applied to an operand of type 'NSNumber'）。
• iOS 偏移量计算兼容性增强：将负向 inset 计算统一改为 0 - value 形式，规避 NSNumber 一元运算符不支持与 Decimal 推断冲突。
• iOS 构建标识升级：buildInfo 更新为 lizhao-scan-pro/ios@1.0.46，便于确认发布版本。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-scan-pro

lizhao-scan-pro 是跨端 UTS 扫码插件，仅提供 API 模式；调用后直接打开原生全屏扫码界面，底层使用 UTS + 原生相机能力实现（Android：CameraX + ML Kit，iOS：AVFoundation + Vision，Harmony：系统扫码能力）。

支持平台

安装说明

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)

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 当前仍按单条结果回调。

参数说明（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 保持单码回调行为。

连续扫描说明

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）。
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 权限
• 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()
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）

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