更新记录

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

• 新增 Android CameraX + ML Kit、iOS AVFoundation + ML Kit 实时原生引擎
• 新增 Android/iOS 实时多码，支持定格选择与动态跟踪
• 新增 App 图片多码和 Web 自定义解码器多码结果
• 新增 App 原生增强相机连续自动对焦、双指缩放、手动变焦和点按对焦
• 新增 App 标准相机和 Web 自动变焦
• 新增码制能力查询，不支持码制通过 fail 明确返回
• 新增工具栏按钮顺序、文案、图标、颜色、尺寸和自定义事件
• 新增顶部栏、提示区、结果区和工具栏插槽
• 新增 Web 摄像头枚举、能力查询、镜头切换和预览截图
• 新增复制、分享、网址、拨号、WiFi、导航、邮件和短信结果动作

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 全平台扫码与多码识别

lf-scan-x 是面向 uni-app x（UTS / uvue）的二维码、条形码扫描组件。插件内置 easycom 组件、全屏扫码页、Android/iOS UTS 原生识别引擎与结果处理工具，一次导入即可覆盖 App、Web 与微信小程序，无需再安装任何第三方扫码依赖。经典 uni-app（Vue2 / Vue3）项目请使用独立的 lf-scan，两个插件互不依赖。

核心特性

安装配置

1. 导入插件

在插件市场选择「使用 HBuilderX 导入插件」。组件符合 easycom 规范，无需手动注册：

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

2. 注册扫码页

插件的 pages_init.json 会在导入时合并扫码页。请确认项目 pages.json 包含：

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

3. App 模块、权限和基座

在 manifest.json 中勾选 uni-barcode-scanning。Android 至少需要相机和震动权限；iOS 至少填写：

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

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

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

快速开始

<template>
  <lf-scan-x ref="scan" :show-trigger="false" @success="onSuccess" @fail="onFail"></lf-scan-x>
  <button @click="start">开始扫码</button>
</template>

<script setup lang="uts">
import { LfScanResult, LfScanFail } from '@/uni_modules/lf-scan-x/utils/index.uts'

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

function start() : void {
  scan.value?.start()
}

function onSuccess(result : LfScanResult) : void {
  console.log(result.result, result.scanType)
}

function onFail(error : LfScanFail) : void {
  console.log(error.type, error.errMsg)
}
</script>

平台能力

系统扫码页由运行平台实现，界面、相机控制和多码选择不受组件控制。App 需要完整相机能力时使用默认 auto 模式，或使用 custom 模式在当前页面显示扫码界面。

模式与引擎

mode 如何选择引擎

相机能力对照

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

非相机功能

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

Props

Events

Methods

Slots

App 默认 auto 模式使用独立全屏扫码页，插槽不能跨页面传递；需要使用插槽时将 mode 设为 custom。系统扫码页由平台实现，不能应用自定义插槽和工具栏。

数据类型

类型定义统一从 @/uni_modules/lf-scan-x/utils/index.uts 导入。

LfScanResult 识别结果

多码批次额外包含：

LfScanParsed 内容解析

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

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

LfScanFail 错误对象

错误类型包括 permission、unsupported、scan、album、flash、busy、action 和 cancel。

LfScanCapabilities 能力查询

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

码制

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

barCodeAll 会按当前引擎能力展开，只请求该引擎实际支持的一维码。显式请求不支持的码制时，组件不会进入扫码页，而是通过 fail 返回明确列表。

结果与动作

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

const actions = getScanResultActions(result)
executeScanResultAction('open', result, null)

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

外部应用、拨号、WiFi 和导航默认二次确认，可传 { confirm: false } 关闭。

场景示例

实时多码

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

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

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

连续扫描

<lf-scan-x
  :continuous="true"
  :continuous-interval="1000"
  :dedupe-time="1500"
  @success="onEachResult"
/>

图片多码

scan.value?.scanImage(tempFilePath)
// 或直接打开相册
scan.value?.chooseImage()

组件设置 multiple=true 时，完整结果列表位于 result.results，并返回 detectedCount、acceptedCount 和 displayedCount。

原生相机增强

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

App 开启 nativeCamera 后使用原生 CameraX/AVFoundation 引擎，支持连续自动对焦、双指缩放、点按对焦、setZoom() 和 focusAt()。实时多码始终使用原生引擎。原生增强模式不执行 autoZoom。

自定义工具栏

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

const toolbarItems : LfToolbarItem[] = [
  { key: 'flash', text: '补光' } as LfToolbarItem,
  { key: 'album', text: '图片' } as LfToolbarItem,
  { key: 'help', text: '说明', icon: '?', backgroundColor: '#24372F' } as LfToolbarItem
]

<lf-scan-x :toolbar-items="toolbarItems" @toolbar-action="onToolbarAction" />

内置键包括 flash、album、camera、input、close、pause、resume、zoom-in 和 zoom-out。未知键不执行内置操作，只触发 toolbar-action。所有按钮点击后都会触发该事件，参数包含 key、text 和完整的 item 配置。

Web 自定义解码器

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

解码器签名为 (imageData, { width, height, canvas }) => result，可同步或异步返回字符串、单个 { result, scanType, bounds }、结果数组或 { results }。多码位置 bounds 使用 0 到 1 的归一化坐标。

相机控制

scan.value?.toggleFlash()
scan.value?.setZoom(2.5, (v : number) => {})
scan.value?.focusAt(0.5, 0.5, () => {})
scan.value?.toggleCamera()          // Web 切换前后镜头
scan.value?.captureImage('png', 0.9) // Web 获取当前预览截图

常见问题

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

App 点扫码没反应？ 检查 pages.json 是否已注册 uni_modules/lf-scan-x/pages/scan/scan；未注册时会改用系统扫码页。

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

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

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

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

隐私说明

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

注意事项

• 原生依赖或权限变化后必须重新制作自定义基座，旧基座不会自动包含新能力。
• 动态多码适合持续跟踪；定格多码位置更稳定，默认建议使用定格模式。
• H5 相机必须运行在 HTTPS 或 localhost，最终能力以 getScanCapabilities() 返回为准。
• Android 10 及以上连接 WiFi 时会显示系统授权面板；Android 9 及以下直接写入系统 WiFi 配置。
• 发布前应在目标设备复核相机、权限和外部结果动作；跨平台编译通过不等于真机行为验证。

许可证

MIT License，详见 license.md。