更新记录

1.0.0（2026-06-26）

新版本发布 android ios 扫码

平台兼容性

uni-app(4.0)

yzj-mlkit-barcode-scanner

基于 Google ML Kit Barcode Scanning 的 uni-app UTS 原生扫码插件，支持 Android 和 iOS 平台。提供二维码/条形码实时识别、相册选图识别、手电筒控制、多码点选、双指缩放预览以及原生扫码页 UI 自定义。

功能特性

• 单码扫码
• 多码识别后点选返回
• 相册选图识别
• 手电筒开关
• 双指缩放预览
• 原生扫码页 UI 自定义

兼容性

• 支持：uni-app Vue2、uni-app Vue3
• 支持页面：vue、nvue
• 支持平台：App-Android、App-iOS
• 不支持：H5、各类小程序、uni-app x
• 最低要求：uni-app 4.0+、HBuilderX 5.0+
• Android 最低系统版本：21（Android 5.0）
• iOS 最低系统版本：13.0

权限说明

• 相机权限：用于实时扫码
• 相册权限：用于从相册选择图片识别二维码/条形码
• 振动权限：用于扫码成功振动反馈（Android）

安装后目录

uni_modules/
└─ yzj-mlkit-barcode-scanner/

API

checkPermission()

检查当前是否已获得相机权限。

{
  granted: boolean
}

scanOnce(options?)

打开原生扫码页，识别成功后返回 Promise<ScanResult>。

type ScanOptions = {
  formats?: ScanFormat[]
  title?: string
  tipText?: string
  ui?: ScanUiOptions
}

type ScanResult = {
  value: string
  format: ScanFormat
  rawValue?: string | null
  debugInfo?: string | null
  timestamp: number
  cancelled?: boolean
}

常用参数：

• formats：限制识别的码制列表，不传表示识别全部支持码制
• title：扫码页标题
• tipText：扫码页底部提示文案
• ui：扫码页原生 UI 配置

常用 ui 配置：

• showBack：是否显示返回按钮
• showAlbum：是否显示相册按钮
• showTorch：是否显示手电筒按钮
• showTitle：是否显示标题
• showTipText：是否显示提示文案
• showScanLine：是否显示动态扫描线
• backIcon / albumIcon / torchIcon / torchActiveIcon：自定义图标路径
• scanLineImage：自定义扫描线图片
• scanLineColor：扫描线颜色
• scanLineStyle：扫描线样式，支持 wechat、simple
• scanLineSpeed：扫描线动画时长
• markerStyle：多码高亮样式，支持 rect、corner、badge
• multiSelectTipText：多码点选提示文案
• successTipText：扫码成功提示文案

基础用法

import { checkPermission, scanOnce } from '@/uni_modules/yzj-mlkit-barcode-scanner'

async function startScan() {
  const permission = checkPermission()
  if (!permission.granted) {
    console.log('当前还没有相机权限')
  }

  const result = await scanOnce()
  if (result.cancelled) {
    console.log('用户取消扫码')
    return
  }

  console.log('扫码结果:', result.value, result.format)
}

自定义扫码页 UI

import { scanOnce } from '@/uni_modules/yzj-mlkit-barcode-scanner'

const result = await scanOnce({
  title: 'Scan code',
  tipText: 'Align the QR code or barcode inside the camera',
  formats: ['qr_code', 'code_128', 'ean_13', 'ean_8'],
  ui: {
    showBack: true,
    showAlbum: true,
    showTorch: true,
    showScanLine: true,
    backIcon: 'static/scan/back.png',
    albumIcon: 'static/scan/album.png',
    torchIcon: 'static/scan/torch.png',
    torchActiveIcon: 'static/scan/torch-active.png',
    scanLineImage: 'static/scan/scan-line.png',
    scanLineColor: '#2EE36D',
    scanLineStyle: 'wechat',
    scanLineSpeed: 1400,
    markerStyle: 'badge',
    multiSelectTipText: '请选择一个二维码',
    successTipText: '扫码成功'
  }
})

console.log(result.value, result.format)

注意事项

• 插件仅支持 uni-app 的 App 原生运行，不支持 H5
• 首次进入扫码页前，建议先调用 checkPermission() 检查权限状态
• 自定义图片建议放在项目 static 目录，例如 static/scan/back.png
• Android 和 iOS 扫码页默认支持双指缩放，不需要额外参数
• iOS 端 codabar 码制仅在 iOS 15.4+ 生效，低版本会自动忽略该码制
• Android 本地运行三方依赖 UTS 插件时，需要正确配置 JDK、Android SDK 和 Gradle

错误码

• 1001：扫码页或相机初始化失败
• 1002：相机权限被拒绝
• 1003：用户取消扫码
• 1004：识别结果为空
• 1099：当前平台不支持或未知错误