更新记录

1.0.0（2026-09-28） 下载此版本

lf-scan 的 uni-app x / UTS 版本，界面重新设计。

• 组件（easycom）：App 端 auto 模式跳转插件自带全屏扫码页，custom 模式在当前页面内使用 camera 组件取景，api 模式使用系统扫码页
• UTS 原生能力：Android / iOS 基于 ML Kit 的相册图片识别、短震动、相机权限申请
• 连续扫码、相同内容去重、一维码二次确认与最小长度校验，系统扫码页可疑码型自动重扫
• 自动放大：App 端未识别时在 1x / 2.5x 之间切换，双击取景区域手动放大
• 识别成功震动 / 提示音、闪光灯、相册识别、识别后保存截图
• 相机权限预检与设置页引导，切后台释放相机、回前台自动恢复
• 扫码结果解析：网址 / WiFi / vCard / MECARD / 日程 / 电话 / 短信 / 邮件 / 位置 / 商品条码 / JSON
• Web：getUserMedia + BarcodeDetector，支持 h5Decoder 接入 jsQR / zxing

平台兼容性

uni-app x(4.71)

lf-scan-x 扫码组件（uni-app x / UTS）

lf-scan 的 uni-app x 版本。组件、页面、工具函数全部使用 .uvue / .uts 编写，App 端识别、震动、权限、相册识别由 UTS 原生插件实现，无第三方依赖。

• App（Android / iOS）：自带全屏扫码页（camera 组件原生取景，Google ML Kit 识别），一行调用；也可在当前页面内嵌入取景；也可使用系统扫码页
• 鸿蒙 / 微信小程序：系统扫码页 uni.scanCode
• Web：浏览器 BarcodeDetector，支持接入自定义解码器（jsQR / zxing 等），支持双指缩放
• 识别准确：默认只启用带校验位的常用一维码，一维码二次确认 + 长度校验，系统扫码页误识别自动重扫
• 反馈可控：震动、提示音（内置音效）开关真实生效
• 稳定：相机权限预检、切后台自动恢复、连续扫码、去重
• 结果解析：网址、WiFi、名片、电话、短信、邮件、地理位置、日程、商品条码、JSON

环境要求

平台兼容

安装

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

// #ifdef APP-ANDROID || APP-IOS
{
  "path": "uni_modules/lf-scan-x/pages/scan/scan",
  "style": {
    "navigationStyle": "custom",
    "backgroundColorContent": "#000000",
    "backgroundColor": "#000000",
    "bounces": false
  }
}
// #endif

4. manifest.json：App 端勾选模块 uni-barcode-scanning（相机组件扫码），这是 camera 组件 scanCode 模式的依赖；iOS 在「隐私信息访问的许可描述」中填写相机与相册用途；Android 权限由插件的 AndroidManifest.xml 自动合并（CAMERA、VIBRATE），示例项目也在 manifest 中显式声明了一遍：

"app-android": {
  "distribute": {
    "modules": { "uni-barcode-scanning": {} },
    "permissions": [
      "<uses-permission android:name=\"android.permission.CAMERA\"/>",
      "<uses-permission android:name=\"android.permission.VIBRATE\"/>",
      "<uses-permission android:name=\"android.permission.FLASHLIGHT\"/>"
    ]
  }
},
"app-ios": {
  "distribute": {
    "modules": { "uni-barcode-scanning": {} },
    "privacyDescription": {
      "NSCameraUsageDescription": "用于扫描二维码 / 条形码",
      "NSPhotoLibraryUsageDescription": "用于从相册选择图片识别二维码",
      "NSPhotoLibraryAddUsageDescription": "用于保存扫码截图到相册"
    }
  }
}

5. 制作自定义基座后真机运行（标准基座不包含 UTS 插件与扫码模块）

快速开始

1. 一行接入

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

import { LfScanResult, LfScanFail } from '@/uni_modules/lf-scan-x/utils/index.uts'

function onSuccess(res : LfScanResult) {
  console.log(res.result, res.scanType, res.parsed?.type)
}
function onFail(err : LfScanFail) {
  console.log(err.type, err.errMsg)
}

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

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

<lf-scan-x ref="scan" :show-trigger="false" @success="onSuccess" />
<button @click="scan?.start()">扫码</button>

const scan = ref<LfScanXComponentPublicInstance | null>(null)

3. 连续扫码

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

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

4. 页面内嵌入（App）

uni-app x 的任意页面都可以放置 camera 组件，因此 custom 模式不再区分 vue / nvue：

<template>
  <view style="flex: 1; background-color: #000000">
    <lf-scan-x ref="scan" mode="custom" :auto-start="true" :show-trigger="false" safe-area-top="true"
      @success="onSuccess" @cancel="goBack" @fail="onFail" />
  </view>
</template>

<script setup lang="uts">
  import { LfScanResult, LfScanFail } from '@/uni_modules/lf-scan-x/utils/index.uts'
  const scan = ref<LfScanXComponentPublicInstance | null>(null)
  function onSuccess(res : LfScanResult) { uni.$emit('scan-result', JSON.stringify(res)); uni.navigateBack() }
  function goBack() { uni.navigateBack() }
  function onFail(err : LfScanFail) { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  onUnload(() => { scan.value?.stop() })
</script>

页面建议设置 navigationStyle: custom。组件会自动监听页面的 onPageHide / onPageShow，切后台释放相机、回前台恢复，无需手动调用 pause() / resume()。

5. 系统扫码页

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

系统扫码页由 uni-app x 内置扫码页提供，其震动与提示音不受 vibrate / sound 控制。App 端关闭系统扫码页不会回调 fail，组件在回到页面后仍无结果时按 cancel 处理。

6. Web 接入自定义解码器

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

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

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

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

识别准确率说明

• barCode 默认只包含 EAN-13 / EAN-8 / UPC-A / UPC-E / Code128，全部带校验位。ITF、Codabar、Code39、RSS 没有校验位，识别引擎对着二维码、文字、条纹都可能"读出"一串甚至一个字符；需要这些码型时显式传入 code39、itf、codabar、rss14、rssexpanded 或 barCodeAll
• camera 组件返回所有码型，组件按 scanType 在结果端过滤，不在范围内的结果直接丢弃
• verifyBarcode（默认开启）：一维码需连续两次读到相同内容、且长度不少于 4 位才返回；二维码自带纠错不受影响
• 系统扫码页无法配置码型细节，组件会拦截可疑码型（ITF / Codabar / Code39 / RSS）并自动重扫，最多 2 次
• 遇到识别异常可开启 :debug="true"，控制台会输出 camera 识别事件的原始数据；正常使用请关闭

提升识别率的建议

API

Props

scanType 取值

Events

LfScanResult

{
  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 | web
  platform: 'app-android',  // app-android | app-ios | app-harmony | web | mp-weixin
  timestamp: 1700000000000,
  parsed: { type: 'url', url: 'https://uniapp.dcloud.net.cn', raw: '...' },  // parse 为 false 时为 null
  imageSaved: null,
  imageSaveError: null
}

parsed 解析类型（LfScanParsed）

UTS 为强类型，LfScanParsed 包含以上全部字段，未使用的字段为 null。

Methods（通过 ref 调用）

Slots

工具函数

import {
  parseScanResult, createScanHistory,
  checkCameraPermission, showPermissionGuide, openAppSettings,
  vibrate, playSound,
  LfScanResult, LfScanFail, LfScanParsed
} from '@/uni_modules/lf-scan-x/utils/index.uts'

@/uni_modules/lf-scan-x 根路径指向 UTS 原生插件，导出 lfDecodeImage、lfVibrate、lfRequestCameraPermission、lfCheckCameraPermission，可在自己的页面中直接使用。

FAQ

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

2. 自定义界面黑屏 / 没有画面 确认 manifest.json 勾选了 uni-barcode-scanning 模块并重新打包自定义基座；确认系统设置中已允许相机；开启 :debug="true" 查看控制台的 camera error 事件。

3. 相册识别提示「未识别到二维码 / 条形码」 图片中的码需清晰且不过小；只在 scanType 范围内查找，多个码时返回第一个符合的结果。

4. 震动无效 Android 需要 VIBRATE 权限（插件已声明，需重新打包基座）；iOS 使用触感反馈，静音模式或关闭系统触感时不会震动。

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

更新日志

见 changelog.md。

许可证

MIT