更新记录

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 扫码组件

版本说明：2.0.0 是 lf-scan 的最终版本，功能已稳定，后续不再更新。 新功能与持续维护转向 uni-app x / UTS 版本 lf-scan-x（开发中，发布后可在插件市场搜索 lf-scan-x）。 现有项目可继续使用本版本；新项目如基于 uni-app x，请等待 lf-scan-x。

全平台条形码 / 二维码扫描组件，Vue2 / Vue3 通用，无第三方依赖。

• App：自带全屏扫码页（原生取景），vue 页面一行调用即可；nvue 页面可页面内嵌入；也可使用系统扫码页
• 小程序：微信 / 支付宝 / 百度 / 抖音 / QQ，系统扫码页
• H5：浏览器 BarcodeDetector，支持接入自定义解码器（jsQR / zxing 等），支持双指缩放
• 识别准确：默认只启用带校验位的常用一维码，一维码二次确认 + 长度校验，系统扫码页误识别自动重扫
• 反馈可控：震动、提示音（内置音效）开关真实生效，连续扫码相同内容不重复反馈
• 稳定：相机权限预检、切后台自动恢复、连续扫码、去重，修复 1.x 黑屏问题
• 结果解析：网址、WiFi、名片、电话、短信、邮件、地理位置、日程、商品条码、JSON

平台兼容

安装

1. 插件市场点击「使用 HBuilderX 导入插件」，或将 uni_modules/lf-scan 复制到项目 uni_modules 目录
2. 组件遵循 easycom 规范，无需 import 和注册，直接使用 <lf-scan>
3. App 端注册扫码页：在 pages.json 的 pages 中加入（vue 页面调用时会跳转到该页；未注册时自动回退为系统扫码页并在控制台提示）：

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

4. App 端在 manifest.json 勾选模块 Barcode（扫码），使用相册识别再勾选 Camera；iOS 配置相机与相册权限描述：

"app-plus": {
  "modules": { "Barcode": {}, "Camera": {} },
  "distribute": {
    "ios": {
      "privacyDescription": {
        "NSCameraUsageDescription": "用于扫描二维码 / 条形码",
        "NSPhotoLibraryUsageDescription": "用于从相册选择图片识别二维码"
      }
    },
    "android": {
      "permissions": [
        "<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\"/>"
      ]
    }
  }
}

修改模块或权限后需要重新打包自定义基座。

快速开始

1. 一行接入

<lf-scan @success="onSuccess" @fail="onFail" @cancel="onCancel" />

onSuccess(res) {
  console.log(res.result, res.scanType, res.parsed);
}

App 端打开插件扫码页，小程序打开系统扫码页，H5 使用浏览器摄像头。识别成功后触发 success，App 端扫码页自动关闭。

2. 通过 ref 调用、自定义按钮

<lf-scan ref="scan" :show-trigger="false" :vibrate="true" :sound="true" @success="onSuccess" />
<button @click="$refs.scan.start()">扫码</button>

3. 连续扫码

<lf-scan ref="scan" :continuous="true" :continuous-interval="1000" @success="onEach" />

每次识别触发一次 success 并震动 / 播放提示音，扫码页底部实时显示已识别数量与最新内容；识别后等待 continuousInterval 再继续，同一个码停留在框内会按该节奏重复回调，去重由业务层按需处理（或设置 dedupeTime）。点击左上角关闭或调用 stop() 结束，结束时触发 stop。

4. nvue 页面内嵌入

在 nvue 页面中组件直接使用原生取景，不跳转页面，适合完全自定义的扫码页：

<template>
  <view class="page">
    <lf-scan ref="scan" mode="custom" :auto-start="true" :show-trigger="false"
      @success="onSuccess" @cancel="goBack" @fail="onFail" />
  </view>
</template>

<script>
export default {
  onHide() { this.$refs.scan.pause(); },
  onShow() { this.$refs.scan.resume(); },
  onUnload() { this.$refs.scan.stop(); },
  methods: {
    onSuccess(res) { uni.$emit('scan-result', res); uni.navigateBack(); },
    goBack() { uni.navigateBack(); },
    onFail(err) { uni.showToast({ title: err.errMsg, icon: 'none' }); }
  }
};
</script>

页面需设置 navigationStyle: custom。

5. 系统扫码页

<lf-scan mode="api" @success="onSuccess" />

系统扫码页由系统提供，其震动与提示音不受 vibrate / sound 控制（组件会透传 sound 参数，部分基座版本生效）。

6. H5 接入自定义解码器

浏览器不支持 BarcodeDetector 时（如 iOS Safari）传入解码函数，以 jsQR 为例：

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

import jsQR from 'jsqr';
decode(imageData) {
  const code = jsQR(imageData.data, imageData.width, imageData.height);
  return code ? { result: code.data, scanType: 'QR_CODE' } : null;
}

签名：(imageData, { width, height, canvas }) => string | { result, scanType } | null，支持 Promise。

识别准确率说明

• barCode 默认只包含 EAN-13 / UPC-A / Code128。识别引擎每一帧先运行一维码读取器，读出结果就不再尝试二维码；ITF、Codabar、Code39、RSS 没有校验位，EAN-8、UPC-E 位数短、校验弱，对着二维码的条纹会频繁产生假读数，既造成结果错乱，也会把二维码识别拖慢到数秒��需要这些码型时显式传入 ean8、upce、code39、itf、codabar、rss14、rssexpanded 或 barCodeAll
• verifyBarcode（默认开启）：一维码需连续两次读到相同内容、且长度不少于 4 位才返回；二维码自带纠错不受影响
• 系统扫码页无法配置码型细节，组件会拦截可疑码型（ITF / Codabar / Code39 / RSS）并自动重扫，最多 2 次
• 遇到识别异常可开启 :debug="true"，控制台会输出原生识别事件的原始数据；正常使用请关闭，日志会影响流畅度

提升识别率的建议

自动放大与相机倍数完全由原生扫码引擎控制，barcode 组件没有开放 JS 接口，组件无法在不支持的基座 / iOS 上自行实现放大。

API

Props

scanType 取值

Events

success 回调 result

{
  result: 'https://uniapp.dcloud.net.cn',
  scanType: 'QR_CODE',      // QR_CODE EAN_13 CODE_128 DATA_MATRIX PDF_417 ...
  charSet: 'UTF-8',
  path: '',                 // 图片路径（相册识别 / saveImage）
  rawData: '',
  source: 'camera',         // camera | album | api | h5
  platform: 'app-nvue',
  timestamp: 1700000000000,
  parsed: { type: 'url', url: 'https://uniapp.dcloud.net.cn', raw: '...' }
}

parsed 解析类型

Methods（通过 ref 调用）

Slots

工具函数

import {
  parseScanResult, createScanHistory,
  checkCameraPermission, showPermissionGuide, openAppSettings,
  vibrate, playSound
} from '@/uni_modules/lf-scan/index.js';

缩放说明

• App：autoZoom 交给原生控件自动放大（Android，HBuilderX 3.5.4+ 基座生效；组件会同时以 autoZoom / autozoom 两种写法传给原生）；组件不遮挡取景区域，原生控件支持的双指缩放可直接使用。barcode 组件未提供 JS 控制相机倍数的接口，setZoom() 在 App 端无效
• H5：双指缩放，相机支持时使用相机缩放，否则使用数字缩放；autoZoom 开启时隔帧对画面中心 2 倍区域解码，提升小码 / 远距离识别率

FAQ

1. App vue 页面调用后打开的是系统扫码页 扫码页未在 pages.json 注册，按「安装」第 3 步注册后重新运行；控制台会有 [lf-scan] 扫码页面 ... 未注册 提示。

2. 震动 / 提示音开关不生效 系统扫码页（mode="api"）的反馈由系统控制。使用默认的 auto 模式（App 插件扫码页、nvue 页面内取景）或 H5 时，开关完全由组件控制。

3. 识别结果不对 见「识别准确率说明」，优先使用默认的 barCode 码型集合，只扫二维码时设置 ['qrCode']；开启 debug 查看原始数据。

4. iOS 启动扫码无画面或闪退 配置 NSCameraUsageDescription，勾选 Barcode 模块后重新打包自定义基座。

5. 1.x 黑屏的原因

6. H5 提示不支持 需要 HTTPS；iOS Safari 等不支持 BarcodeDetector 的浏览器请传入 h5Decoder。

更新日志

见 changelog.md。2.0.0 为最终版本，不再接受功能需求；后续请关注 lf-scan-x。

许可证

MIT