原生扫码秒级响应（近距聚焦增强）安卓+iOS+鸿蒙 - 更新日志
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，便于确认发布版本。
1.0.45（2026-04-30）
- 修复 Android 全屏预览顶部状态栏区域未覆盖问题：补齐弹层窗口 edge-to-edge 参数，允许内容绘制到状态栏与刘海区域，避免顶部出现白色留边。
- Android 沉浸式窗口兼容性优化：移除在部分 UTS 编译链路下不稳定的
WindowCompat.setDecorFitsSystemWindows调用，改用decorView.fitsSystemWindows=false与系统 UI 标记组合实现等效效果。 - iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.45，便于确认发布版本。
1.0.44（2026-04-30）
- iOS 扫码预览改为满屏裁切优先：
AVCaptureVideoPreviewLayer显式设置resizeAspectFill，解决顶部/底部黑边问题。 - iOS 新增预览层统一刷新：在
viewDidAppear / viewDidLayoutSubviews / 前后台恢复场景统一按view.bounds刷新预览层，避免会话恢复后出现留边回退。 - Android 扫码弹层窗口启用 edge-to-edge：内容延伸到状态栏与导航栏下方，并将系统栏背景改为透明，去除安全区导致的上下黑条。
- 保持交互兼容：系统栏图标仍保留显示，Android 现有扫码框遮罩与操作按钮布局语义不变。
- 新增扫码页偏移配置：
ScanOptions.uiLayoutConfig，支持close / album / continuous / torch / tip五类元素按containerOffset / iconOffset / textOffset三层独立偏移。 - 偏移方向统一：
x > 0向右、y > 0向下；支持正负值；Android 按dp、iOS 按pt。 - iOS 接入偏移能力：在
setupChrome与applyButtonImage中统一应用容器/图标/文字偏移，不改变回调语义与生命周期。 - Android 接入偏移能力：
index.uts通过layoutConfigJson下发原生层，Kotlin 侧新增解析与应用逻辑。 - Android 按钮渲染升级：由单一
TextView + compound drawable升级为“容器 + 独立 icon/text 子视图”，支持图标与文字独立位移。 - 兼容性保持：不传
uiLayoutConfig时偏移默认0，界面行为与旧版本保持一致。
1.0.42（2026-04-28）
- 修复 iOS 近距离扫码模糊问题：重构后置镜头选择策略，默认优先主摄（
builtInWideAngleCamera），避免部分机型近距场景误落到无自动对焦超广角导致发糊。 - 新增 iOS 机型能力判定：仅当虚拟多摄（
builtInTripleCamera/builtInDualWideCamera）中的 ultra-wide 分量具备自动对焦能力时，preferNear才启用 near 优先策略。 - 兼容性增强：补充
dual / dualWide / triple / ultraWide / default的分层兜底顺序，确保旧机型与单摄机型保持可用且行为可预测。 - iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.42，用于确认自定义基座是否安装到本次修复版本。
1.0.40（2026-04-27）
- 新增扫码页图片图标配置：
ScanOptions.uiImageConfig，支持提示区与“关闭/相册/手电”按钮分别传入图片图标。 - 图标渲染支持“仅图标 / 仅文案 / 图标+文案”：当对应位置传入图片图标且未传文案时，按钮按仅图标展示；未传图片时保持原有文案回退逻辑。
- Android 新增图标来源解析：支持本地文件路径、
file://、content://、data:image/*;base64,...与应用资源路径（含_www/static）。 - 新增操作按钮胶囊背景开关：
ScanOptions.showActionCapsuleBackground，默认true（保持历史样式）。 - 当
showActionCapsuleBackground=false时，Android / iOS 扫码页顶部与底部操作按钮（关闭/相册/单次连续/手电）不再渲染胶囊底与描边。 - 修复 Android 本地图标路径解析：补充
assets/apps/<appId>/www/资源目录扫描，static/logo.png这类路径可直接用于uiImageConfig。 - 增强 Android 本地图标兜底：当常规候选路径未命中时，自动按后缀在
assets目录树内查找匹配文件。 - 增强 Android 路径写法兼容：
static/...、/static/...、_www/static/...与apps/<appId>/www/...写法统一归一处理，降低路径前缀差异导致的图标不显示问题。 - 增强 Android 运行时目录兼容：新增应用私有目录（含
.../apps/<appId>/www）文件系统候选路径与后缀匹配兜底，适配资源不落在assets的运行环境。 - iOS 新增
UIImage图标桥接：支持本地路径与data URI解析、尺寸缩放与tintColor染色，统一用于提示区与按钮图标。 - 修复 iOS 图片图标显示异常：
UIButton(.system)场景下图标改为alwaysOriginal渲染，避免被系统tint模板化为蓝色方块。 - 兼容性保持：未配置
uiImageConfig与showActionCapsuleBackground时，历史uiTextConfig、默认文案与胶囊样式行为不变。 - 示例页新增胶囊背景开关与本地图片路径示例，便于验证纯图标场景视觉。
1.0.39（2026-04-27）
- 新增可控多结果回调开关：
ScanOptions.returnAllResults（默认false），默认行为保持不变（每帧只回传一个优先结果）。 - Android 相机扫码支持同帧多码回传：
returnAllResults=true时，onResult(res).results可返回同帧全部有效码值；关闭时仍保持历史单码策略与节流逻辑。 - Android 相册识别支持同图多码回传：开启
returnAllResults后，pickImageAndScan同步返回图片中的多条识别结果。 - iOS 相机扫码支持同帧多码回传：开启
returnAllResults后，metadataOutput将聚合同帧可读码并统一回调。 - 新增扫码页 UI 文案/图标配置：
ScanOptions.uiTextConfig，支持提示文案与“关闭/相册/手电”按钮按需自定义。 - 新增图标文案组合策略：支持“仅图标 / 仅文案 / 图标+文案”，未配置字段自动回退默认文案，不影响旧调用。
- 保持历史兼容：
tipText旧字段继续有效；当同时传uiTextConfig.tipText时优先使用新字段。 - Android / iOS 双端对齐：全屏原生扫码页顶部按钮、底部手电按钮与提示文案均支持配置化展示。
- iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.39，便于验证自定义基座版本。
1.0.37（2026-04-26）
- 修复 iOS 初始
enableTorch=true场景的闪光灯异常：扫码页首次打开时，手电筒改为在预览链路稳定后再开启，避免“灯光一闪即灭”。 - 修复 iOS 前后台切换后的手电筒状态丢失：应用切到后台时同步更新为关闭状态；切回前台后等待预览恢复，再按切后台前状态自动恢复手电筒。
- 优化 iOS 扫码页手电筒按钮文案同步：按钮文本始终与当前真实灯光状态保持一致（
打开手电筒 / 关闭手电）。 - iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.37，用于确认自定义基座已安装到本次修复版本。
1.0.36（2026-04-24）
- 新增连续扫码回调节奏控制：
ScanOptions.continuousIntervalMs支持设置连续扫码最小回调间隔（默认0），并保持 Android / iOS 现有“同码约900ms去重”逻辑不变。 - 新增全屏页内模式切换能力：
ScanOptions.showContinuousToggle=true时，Android / iOS 扫码页底部显示“单次扫码 / 连续扫码”切换按钮，切换后立即生效。 - 新增 overlay 事件
continuousChanged：当用户在原生页切换模式时回传固定 payload：{ continuous: boolean, source: "nativeToggle" }。 - 提升 Android / iOS 顶部“关闭 / 相册”可读性：增大字号与点击热区，并升级为胶囊底样式，适配亮背景与老年用户场景。
- Harmony 对齐
continuousIntervalMs：连续扫码循环调度支持最小间隔配置；showContinuousToggle参数可接收但受系统扫码页能力限制不展示页内开关。 - 优化 Android / iOS 全屏扫码页底部操作区布局：当
showContinuousToggle=true时，“单次扫码 / 连续扫码”与“打开手电筒 / 关闭手电”改为同一行左右并排、整体居中显示，减少视线跳转成本。 - iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.36，便于确认当前基座是否已安装本次布局优化版本。
1.0.34（2026-04-22）
- 新增 Harmony 扫码实现：补齐
start/stop/pause/resume/pickImageAndScan/setScanFormats/postOverlayMessage/destroyScanner，并保持与 Android/iOS 一致的回调结构（onResult/onError/success/fail/complete）与错误码体系。 - 新增 Harmony 连续扫码状态机：支持
continuous、scannerId多实例状态隔离、overlayConfig.enabled事件通道（overlayReady/shown/cameraReady/recognized/albumRecognized/paused/resumed/closed/nativeMessage）。 - 新增 Harmony 相册识别链路：
pickImageAndScan与startScan(enableAlbum=true)复用系统扫码页，识别成功统一返回ScanFrameResult。 - Harmony 能力边界说明：系统扫码页不提供可编程手电筒与缩放控制，
setTorchEnabled/setZoomRatio以“状态兼容 + 成功回调”方式对齐调用语义。 - 同步更新平台声明：
package.json与readme.md已将 Harmony 标记为可用能力。
1.0.33（2026-04-20）
- Android 扫描线视觉升级：全屏扫码页改为细长半透明红色光束，首帧透明淡入并匀速下移，新增中心高亮、边缘柔和渐隐、轻微霓虹辉光与玻璃高光层次，整体观感向 iOS 对齐。
- Android 主题色联动优化：扫码角框、框体描边、提示气泡描边改为基于
scanLineColor动态派生，避免界面残留固定红色；同时优化提示文案气泡与边框层次，提升整体观感。
1.0.32（2026-04-20）
- Android 识别性能优化：实时扫码与相册识别链路改为“按配置格式构建 ML Kit Scanner”，避免全码制扫描导致的额外开销。
- Android 误识别优化：当同帧存在多个候选码时，优先选择可读内容且面积更大的码，降低小目标误触发概率。
- Android 稳定性优化：
ImageAnalysis分析分辨率固定为1280x720，并在相机绑定后执行中心点自动追焦，改善条形码场景启动初期的失焦与抖动感。
1.0.31（2026-04-18）
- 修复 iOS 扫码线颜色异常问题：新增
resolveScanLineBaseColor取色逻辑，优先读取有效背景色/阴影色并提供兜底默认值，避免渐变装饰后再次取色失真。 - 优化 iOS 扫码会话启动后的对焦稳定性：新增
applyRunningFocusDefaults与focusRestoreTimer生命周期管理，在会话运行后补一次对焦恢复，降低短时失焦概率。 - 优化 iOS 扫码线动画重启行为：每次重启动画前先恢复业务色，确保
scanLineColor与视觉表现一致。 - iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.31，用于确认自定义基座已安装到当前发布版本。
1.0.30（2026-04-17）
- 修复 iOS 相册识别失败时全屏扫码页未关闭的问题：当相册识别结果为空或识别过程异常时，统一执行关闭全屏扫码页。
- 优化 iOS 相册识别失败链路：失败分支新增明确关闭阶段标记（
album.decode.empty.close/album.decode.catch.close），便于日志回溯。 - iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.30，用于确认自定义基座已安装到当前发布版本。 - 优化iOS启动时短暂的黑屏之后再出现扫码预览。
1.0.27（2026-04-16）
- Android 新增点击聚焦能力：扫码预览区支持点按触发
FocusMeteringAction，并补一次延时追焦，提升近距场景对焦稳定性。 - Android 新增聚焦可视化反馈：点击聚焦时显示短暂聚焦提示框（与 iOS 交互体验对齐）。
- Android 支持
nearFocusLock：开启后保持近距辅助缩放策略；关闭时仍保留“点按后短时辅助缩放并自动恢复”的行为。 - 接口与文档同步：
nearFocusLock从“仅 iOS”更新为“Android / iOS”。 - iOS 构建标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.27，用于确认当前插件版本。
1.0.26（2026-04-16）
- 发版元信息升级：
package.json.version更新为1.0.26，并同步优化插件displayName/description，突出 iOS 近距聚焦增强能力。 - iOS 调试标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.26，用于确认自定义基座是否安装到当前版本。
1.0.24（2026-04-16）
- iOS 闪退排查增强：
setupChrome新增分段 trace，精确定位到具体 UI 构建步骤。 - iOS 稳定性修复：
resolveShowScanFrame改为直接读取强类型字段，移除UTSJSONObject强转，降低运行时桥接崩溃风险。 - iOS 调试标识升级：
buildInfo更新为lizhao-scan-pro/ios@1.0.24，用于确认自定义基座是否安装到最新构建。
1.0.20（2026-04-16）
- 修复 iOS 云打包编译错误：
app-ios端聚焦调用改为位置参数，避免生成 Swift 后出现extraneous argument labels 'x:y:fromTap:'与extraneous argument labels 'x:y:'报错。 - 同步统一版本号：
package.json.version更新为1.0.20，与更新日志保持一致。
1.0.18（2026-04-16）
- 新增 iOS 全屏扫码页手电筒按钮：底部中间可直接切换“打开手电筒 / 关闭手电”，并与
enableTorch/setTorchEnabled状态联动。 - 补齐 iOS
scanLineColor解析：支持#RRGGBB与#AARRGGBB，与文档参数说明保持一致。 - 同步更新文档与示例：补充扫码页按钮文案说明，并明确相册识别也可通过
beepOnScan/vibrateOnScan启用提示音与震动。
1.0.17（2026-04-15）
- 修复 iOS 云打包编译失败问题：规避
NSNumber -> Double类型不兼容导致的index.swift编译报错。 - 优化 iOS 扫码页展示：扫码界面改为原生全屏展示，避免出现非全屏弹层样式。
- 调整扫码页交互：示例页不再进入页面自动拉起扫码，改为点击按钮后再触发授权与扫码流程。
- 修复扫码页状态同步：点击原生扫码页“关闭”后，页面按钮状态可正确恢复为“打开原生扫码”。
- 优化 iOS 扫码动效：扫描线改为单向下扫循环（到底淡出后从上方继续），不再来回往返。
- 优化扫码框视觉样式：恢复扫码框并增加圆角、轻描边与柔和层次效果，整体观感更接近微信扫码体验。
1.0.16（2026-04-01）
- 新增 iOS 原生扫码实现：基于
AVFoundation + Vision，支持实时扫码与相册识别。 - iOS 端补齐与 Android 一致的核心 API：
start/stop/pause/resume、setTorchEnabled、setZoomRatio、setScanFormats、postOverlayMessage、destroyScanner。 - iOS 端支持 Overlay 事件与回调链路，统一错误码与回调语义（
onResult/onError/success/fail/complete）。 - 同步更新文档与平台声明：
package.json中 iOS 支持标记为可用，README 增加 iOS 能力与权限说明。
1.0.15（2026-03-27）
- 修复 Android 端
beepOnScan/vibrateOnScan仅有类型与文档、未实际生效的问题。 - 扫码成功与相册识别成功后，现可按配置播放提示音与触发短震动。
1.0.14（2026-03-27）
showScanFrame=false时进一步去除扫码遮罩层，不再保留中间透明方框，仅保留扫描线与提示文字。- 同步更新参数与 UI 约定文档描述。