更新记录

3.0.0（2026-10-22） 下载此版本

新增

• Android CameraX + ML Kit、iOS AVFoundation + ML Kit 实时原生扫码引擎
• App 镜头同帧多码、定格选择、动态多码和按实际位置显示的结果标记
• App/H5 图片多码识别，默认按引擎实际结果返回，不限制数量
• App 原生增强相机连续自动对焦、双指缩放、手动变焦与点按对焦
• App 标准相机和 H5 自动变焦
• getScanCapabilities() 码制及功能能力查询，不支持码制通过 fail 明确返回
• 标题、提示、主题色、工具栏项目/顺序/文案及扫码页区域插槽自定义
• URL 打开、系统分享、拨号、WiFi 连接、地图导航、邮件、短信和复制等结果动作
• H5 实时多码、摄像头枚举与切换、闪光灯、截图、自定义解码器

优化

• 插件统一迁移到 uni_modules/lf-scan，组件、扫码页、原生引擎、静态资源和文档一次导入
• 多码使用无暗角遮罩的全屏界面，识别后可定格画面，也可保持实时跟踪
• Android 多码坐标按分析帧旋转、裁剪区域和全屏预览规则映射
• 动态多码增加短时结果稳定窗口，降低正常手持抖动造成的标记闪烁
• 默认一维码仅启用 EAN-13、UPC-A、Code 128；其他一维码按需显式开启
• 扫码页面、示例页面、操作文案和返回键行为统一整理

修复

• 修复 App 非系统扫码页按系统返回键无法退出
• 修复 Android 多码页面点击结果时崩溃
• 修复多码标记停留在已移出画面的码位置
• 修复图片或预览缩放造成的多码标记坐标偏移
• 修复设备倾斜或旋转后分析帧方向变化造成的多码标记错位
• 修复 CameraX 分析裁剪区域原点未换算造成的多码箭头偏移
• 修复 RSS_14、RSS_EXPANDED 等当前引擎不支持且设置页无法取消时阻止启动
• 修复非 App 环境直接访问 plus 导致的运行错误
• 补充系统扫码、标准相机、原生增强相机和 H5 的功能边界说明

2.0.0（2026-09-23） 下载此版本

2.0.0（2026-09-23）最终版本

2.0.0 是 lf-scan 的最终版本，后续不再更新。持续维护与新功能转向 uni-app x / UTS 版本 lf-scan-x（开发中）。

修复

• 修复自定义界面识别二维码需要数秒：barCode 默认集合去掉 EAN-8 / UPC-E，避免其假读数每帧抢占识别并反复停止扫描；需要短条码时显式传入 ean8 / upce
• 修复连续扫码去重窗口被重复读数不断刷新、到期后不重置的问题；去重改为默认关闭（dedupeTime 为 0），每次读到都视为新结果
• 修复原生以字符串形式返回数值码型（如 "1"）时码型被识别为未知的问题
• 修复连续扫码只有第一次播放提示音：App 端 innerAudioContext 停止后再播放无声，改为每次新建上下文、播完即销毁
• 修复识别结果错乱、连续扫码"震动多次但结果全错 / 只剩一个字符"：barCode 不再包含 Code39 / ITF / Codabar / RSS 等无校验位码型，新增一维码二次确认与最小长度校验，原生识别事件按最长字符串字段取内容，系统扫码页对可疑码型自动重扫
• 修复震动 / 提示音开关无效：原生控件的震动 / 提示音关闭，改由组件统一控制，去重时不重复反馈
• 修复 App nvue 自定义界面多种场景黑屏：相机重复初始化、barcode 无显式尺寸、无相机权限、切后台回前台未恢复、闪光灯误拉起系统相机、停止时先销毁后 cancel
• 修复快速连续点击导致重复调用 uni.scanCode
• 修复 filters 与码型名称映射和 plus.barcode 常量不一致
• 修复 nvue 下闪光灯状态被两次取反无法关闭

新增

• 插件自带全屏扫码页 uni_modules/lf-scan/pages/scan/scan.nvue，App vue 页面一行调用即可使用自定义界面（pages.json 注册一次，未注册自动回退系统扫码页）
• 迁移为 uni_modules 规范，easycom 自动引入，HBuilderX 一键发布
• mode：auto / api / custom
• 识别成功提示音（内置音效，sound / soundSrc）
• 自动放大 autoZoom（App 原生 / 系统扫码页 / H5 中心区域放大识别），H5 双指缩放与 setZoom()
• 一维码二次确认 verifyBarcode，barCodeAll 码型
• 连续扫码 continuous / continuousInterval / dedupeTime，底部实时显示已识别数量与最新内容（showResult）
• H5 支持：getUserMedia + BarcodeDetector，支持 h5Decoder 接入 jsQR / zxing，支持闪光灯
• 相机权限预检与设置页引导，fail 事件增加 type
• 结果解析 result.parsed：网址 / WiFi / vCard / MECARD / 日程 / 电话 / 短信 / 邮件 / 地理位置 / 商品条码 / JSON
• 方法：pause()、resume()、cancel()、setFlash()、toggleFlash()、setZoom()、scanImage(path)、isScanning()
• 事件：start、stop、flash-change
• 属性：color、showHeader、showFlash、showTrigger、triggerText、showResult、autoStart、vibrate、sound、soundSrc、verifyBarcode、parse、permissionTip、safeAreaTop、pagePath、zIndex、debug、autoCharset、barCodeInput、h5*
• 内置纯 view 绘制的图标，无字体 / 图片依赖
• 工具函数入口 index.js：parseScanResult、createScanHistory、checkCameraPermission、playSound 等

变更

• 组件目录由 components/lf-scan 迁移至 uni_modules/lf-scan
• auto 模式在 App vue 页面默认跳转插件扫码页（1.x 为系统扫码页），需要系统扫码页请设置 mode="api"
• autoStart 语义变更为「组件挂载后自动开始扫码」，默认 false
• autoCharset 默认 false（与 uni.scanCode 一致）
• success 回调新增 source、platform、timestamp、parsed，scanType 统一为大写下划线命名
• startScan() / stopScan() 保留为别名

1.0.0

• 首个版本：App / 小程序扫码，nvue 自定义界面，闪光灯、相册识别、保存图片

1.0.0（2025-12-22） 下载此版本

平台兼容性

uni-app(5.26)

lf-scan 全平台扫码与多码识别

lf-scan 是面向经典 uni-app（Vue2 / Vue3）的二维码、条形码扫描组件。插件内置 easycom 组件、全屏扫码页、Android/iOS 原生识别引擎与结果处理工具，一次导入即可覆盖 App、H5、微信 / 支付宝 / 百度 / 抖音 / QQ 小程序，无需再安装任何第三方扫码依赖。

📌 新项目建议使用 lf-scan-x

uni-app x（UTS / uvue）是 DCloud 官方未来的主推方向。新建项目、新功能建议直接选用 lf-scan-x（本插件的 uni-app x 版，插件市场搜索即可）；已有的经典 uni-app（Vue2 / Vue3）项目可继续使用本插件。

核心特性

安装配置

1. 导入插件

在插件市场选择「使用 HBuilderX 导入插件」，插件目录应为 uni_modules/lf-scan/。组件符合 easycom 规范，无需手动 import 或注册。

2. 注册 App 扫码页

导入时确认合并插件的 pages_init.json。若未自动合并，在项目 pages.json 的 pages 中加入：

// #ifdef APP-PLUS
,
{
  "path": "uni_modules/lf-scan/pages/scan/scan",
  "style": {
    "navigationStyle": "custom",
    "backgroundColor": "#000000",
    "app-plus": {
      "bounce": "none",
      "titleNView": false
    }
  }
}
// #endif

pages 数组第一项后使用上述片段时保留开头逗号；扫码页是第一项则删除逗号。未注册页面时，App Vue 页面会回退到系统扫码页。

3. 配置 App 模块与权限

在 manifest.json 中勾选 Barcode（扫码） 与 Camera（相机） 模块，并配置相机、相册权限描述。Android 至少声明：

<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.FLASHLIGHT"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-feature android:name="android.hardware.camera"/>
<uses-feature android:name="android.hardware.camera.autofocus"/>

iOS 至少配置：

{
  "NSCameraUsageDescription": "用于识别二维码和条形码",
  "NSPhotoLibraryUsageDescription": "用于从相册选择图片识别二维码",
  "NSPhotoLibraryAddUsageDescription": "用于保存扫码截图到相册"
}

连接 WiFi 还需要 Android 的 WiFi、网络状态、定位及 Android 13 NEARBY_WIFI_DEVICES 权限；iOS 需要 com.apple.developer.networking.HotspotConfiguration entitlement。示例工程的 manifest.json 已包含完整配置。

4. 制作自定义基座

插件包含 UTS 原生依赖。首次导入、更新原生代码或修改权限后，需要使用 HBuilderX 4.71+ 重新制作自定义调试基座。Android 最低 API 21（Android 5.0）；iOS 原生依赖要求 deployment target 15.5。

快速开始

<template>
  <lf-scan ref="scan" :show-trigger="false" @success="onSuccess" @fail="onFail" />
</template>

<script>
export default {
  methods: {
    openScan() {
      this.$refs.scan.start();
    },
    onSuccess(result) {
      console.log(result.result, result.scanType, result.parsed);
    },
    onFail(error) {
      console.log(error.type, error.errMsg);
    }
  }
};
</script>

不同宿主的行为：

• App Vue 页面：进入插件自带的全屏扫码页。
• App nvue 页面：在当前页面内显示扫描视图。
• H5：使用浏览器摄像头（需 HTTPS 或 localhost）。
• 小程序：调用各平台 uni.scanCode 系统扫码页。

平台能力

系统扫码页由运行平台实现，界面、手动变焦、点按对焦、多码选择和完全自定义工具栏不受组件控制。需要这些能力时，App 使用默认自定义页并开启 nativeCamera，H5 使用默认浏览器扫码界面。

模式与引擎

mode 如何选择引擎

mode="custom" 只表示使用插件自定义扫码界面。经典 uni-app 的 Vue 页面仍会打开插件的 nvue 扫码页；只有宿主本身是 nvue 页面时才在当前页内显示。

相机能力对照

自动对焦与自动变焦是两个独立能力。系统扫码、标准相机和原生增强相机都会使用各自相机栈的自动对焦；autoZoom 只负责改变画面倍率。原生增强相机保留完整视野，不执行自动变焦，实时多码也不会为某一个码自动放大。用户可双指缩放、点击对焦，或调用 setZoom()、focusAt()。

非相机功能

图片识别通过 scanImage() 独立执行，不受 mode 影响。saveImage 依赖当前引擎能否返回识别画面路径；原生实时相机不保证能够保存预览帧，业务需要截图时应以返回的 path 是否为空为准。

Props

Events

Methods

Slots

数据类型

LfScanResult 识别结果

单个结果的主要字段：

多码批次额外包含：

LfScanParsed 内容解析

parse=true（默认）时，组件按内容自动识别类型，填充 result.parsed。字段随 parsed.type 变化：

所有解析结果均包含 type 与 raw（原始内容）两个公共字段。

LfScanFail 错误对象

常见错误类型：permission（权限）、unsupported（能力不支持）、scan（扫描失败）、album（相册失败）、flash（闪光灯）、busy（占用）、action（动作失败）、cancel（取消）。

LfScanCapabilities 能力查询

getScanCapabilities() 返回对象包含 platform、engine、precise、known、requestedFormats、supportedFormats、unsupportedFormats、available 与 features（realtimeMultiple / zoom / focus / customToolbar / resultActions）。可在开始扫描前据此做能力适配。

码制

可用值：qrCode、barCode、barCodeAll、datamatrix、pdf417、aztec、maxicode、ean13、ean8、upca、upce、codabar、code39、code93、code128、itf、rss14、rssexpanded。

barCode 仅包含 EAN-13、UPC-A、Code 128，减少二维码纹理被短条码或无校验条码误识别的概率。需要其他一维码时显式指定具体码制或 barCodeAll。不同引擎的支持范围不完全一致，开始扫描前组件会检查能力；不支持时触发 fail，其中包含 supportedFormats 和 unsupportedFormats。

结果动作

const actions = this.$refs.scan.getResultActions(result);
this.$refs.scan.executeResultAction(actions[0], result, {
  confirm: true,
  confirmTitle: '确认操作'
});

动作名称：copy、share、open、call、wifi、navigate、email、sms。

涉及打开外部应用、拨号、连接 WiFi 和导航的动作默认二次确认，可传 confirm: false 关闭。小程序受平台安全策略限制，外部 URL 和系统分享等动作可能返回 unsupported。

场景示例

单码扫描

<lf-scan ref="scan" :show-trigger="false" @success="onSuccess" />

连续逐个扫描

<lf-scan
  ref="scan"
  :show-trigger="false"
  :continuous="true"
  :continuous-interval="800"
  :dedupe-time="1500"
  @success="onEachResult"
/>

每次识别都会触发 success。continuousInterval 控制两次解码之间的等待时间；dedupeTime=0 表示不去重。

实时多码（定格 / 动态）

<lf-scan
  ref="scan"
  :show-trigger="false"
  :multiple="true"
  :dynamic-multiple="false"
  @select=""
  @success="onSuccess"
/>

dynamicMultiple=false 时，检测到多个码后定格当前画面，用户点击对应标记返回结果。dynamicMultiple=true 时保持实时预览，码移出画面后标记自动消失。多码结果默认不限制数量；设置 maxResults 可限制返回数量。

原生实时多码会把分析帧中的位置转换到当前预览层，设备倾斜或旋转后仍按屏幕上的实际位置显示标记。bounds 使用当前预览区域的 0 到 1 归一化坐标；不要直接把原始相机像素坐标当作页面坐标使用。

图片多码

this.$refs.scan.scanImage(localPath);
// 或打开相册选择
this.$refs.scan.chooseImage();

组件设置 multiple=true 时，success 返回批次对象，完整列表位于 results。App 和 H5 支持该能力，小程序不支持组件直接识别本地图片。

原生相机增强

<lf-scan ref="scan" :native-camera="true" />

App 单码默认使用 DCloud barcode 控件；开启 nativeCamera 后改用原生 CameraX/AVFoundation 引擎，支持连续自动对焦、双指缩放、setZoom() 和 focusAt()。实时多码始终使用原生引擎。原生增强模式不执行 autoZoom；系统扫码页的相机控制由系统决定。

自定义工具栏

<lf-scan
  :toolbar-items="[
    { key: 'flash', text: '照明' },
    { key: 'album', text: '图片' },
    { key: 'zoom-in', text: '放大', icon: '+' },
    { key: 'help', text: '帮助', icon: '?' }
  ]"
  @toolbar-action="onToolbarAction"
/>

内置动作包括 flash、album、camera、close、pause、resume、zoom-in 和 zoom-out。未知 key 不执行内置操作，只触发 toolbar-action，由业务自行处理。工具栏项目支持 text、icon、textColor、backgroundColor、size 和 show。

所有自定义扫码界面都支持通过 toolbarItems 配置按钮顺序、文案、图标、颜色、尺寸和显示状态，并通过 toolbar-action 接收点击事件。App Vue 使用独立扫码页，插槽无法跨页面传递，但 toolbarItems 和 toolbar-action 会传递到该扫码页；App nvue 与 H5 还可通过 header、tip、result、toolbar 插槽完全替换对应区域。系统扫码页不支持自定义操作栏。

H5 自定义解码器

不支持 BarcodeDetector 的浏览器可传入业务解码器：

<lf-scan :h5-decoder="decode" />

函数签名：

decode(imageData, { width, height, canvas })

可同步或异步返回字符串、单个 { result, scanType, bounds }、结果数组或 { results }。多码位置 bounds 使用 0 到 1 的归一化坐标。

相机控制

const scan = this.$refs.scan;

scan.toggleFlash();                 // 切换闪光灯
scan.setFlash(true);                // 打开闪光灯
scan.setZoom(2.5).then(v => {})     // 设置缩放倍数，返回实际值
scan.focusAt(0.5, 0.5);             // 点按画面中心对焦
scan.toggleCamera();                // H5 切换前后镜头
scan.captureImage('png', 0.9);      // H5 获取当前预览截图

工具函数

import {
  parseScanResult,
  createScanHistory,
  checkCameraPermission,
  getScanResultActions,
  executeScanResultAction,
  getStaticFormatCapability
} from '@/uni_modules/lf-scan/index.js';

常见问题

扫码黑屏 / 无画面？ 确认已勾选 Camera 模块、权限已授权，且 App 端已重新制作包含插件 UTS 原生依赖的自定义基座。

App 点扫码没反应？ 检查 pages.json 是否已注册 uni_modules/lf-scan/pages/scan/scan；未注册时 App Vue 页面会静默回退到系统扫码页。

H5 无法调用摄像头？ 浏览器要求 HTTPS 或 localhost；Safari 无原生 BarcodeDetector，需传入 h5Decoder。最终能力以 getScanCapabilities() 返回为准。

多码标记位置不准？ 标记基于预览区域的归一化坐标；请勿把原始相机像素坐标当页面坐标。若做了自定义缩放或裁剪，请核对坐标映射。

请求的码制不生效？ 组件会在启动前校验码制能力，不支持的码制通过 fail 返回 supportedFormats / unsupportedFormats，请据此调整 scanType。

实时多码画面卡顿？ 实时多码固定走原生引擎，请确认已使用自定义基座；H5 端性能取决于浏览器 BarcodeDetector 与设备算力。

隐私说明

插件仅在设备本地处理相机画面、用户主动选择的图片和扫码结果，不采集、不存储、不上传用户数据。相机用于实时扫码；相册用于图片识别或保存截图；震动用于成功反馈；WiFi、网络状态和定位权限只在业务主动执行 WiFi 连接动作时使用。宿主应用仍需根据实际业务完善隐私政策和系统权限用途说明。

注意事项

• 原生依赖或权限变化后必须重新制作自定义基座，旧基座不会自动包含新能力。
• 动态多码适合持续跟踪；定格多码的位置最稳定，默认建议使用定格模式。
• H5 相机必须运行在 HTTPS 或 localhost；浏览器最终支持能力以 getScanCapabilities() 返回为准。
• iOS、H5 和各小程序应在发布前使用目标设备复核权限文案、相机能力及平台审核要求。
• debug 只用于排查原始识别事件，正式发布时应保持关闭。

许可证

MIT License，详见 license.md。