更新记录

1.0.0（2026-06-05）

• 首次发布全端扫码插件。
• 支持 Android、iOS、HarmonyOS、H5 和主流小程序扫码。
• 支持相册识别、能力检测、Promise 调用和全端二维码生成。
• 示例工程已完成 Android/iOS 真机验证，并优化二维码生成结果展示。

平台兼容性

uni-app(4.71)

uni-app x(4.71)

其他

JQ-UniScan-UTS 全端原生扫码插件

JQ-UniScan-UTS 是一个面向 uni-app / uni-app x 的全端扫码插件，统一封装 Android、iOS、HarmonyOS、H5 与主流小程序扫码能力。

App、HarmonyOS、小程序端优先调用平台原生扫码能力，直接使用系统/平台扫码相机，识别速度快、聚焦稳定、码制识别准确；H5 端补齐 uni.scanCode 不支持浏览器扫码的问题，优先使用浏览器原生 BarcodeDetector，不支持时自动回退到 ZXing 解码。

插件同时提供全端二维码生成能力，Android、iOS、HarmonyOS、H5、小程序都可以生成 PNG dataURL，直接显示在 <image> 中。1.0.1 起失败回调会额外返回 suggestion，便于快速定位权限、H5 HTTPS、用户取消、图片不清晰等常见问题。

适合场景

• 商品条码、物流单号、票券二维码、门店核销码识别
• App、H5、小程序统一扫码入口
• 需要相册识别二维码/条形码的业务
• 后台、收银、仓储、巡检、会员核销、票务等高频扫码业务
• 需要在前端生成二维码并展示/保存/分享的业务

核心优势

• 原生相机扫码：Android/iOS/HarmonyOS/小程序优先复用平台扫码页面，识别快、稳定、准确。
• H5 可扫码：H5 内置摄像头扫码和相册图片识别，兼容移动浏览器。
• 自动双引擎：H5 优先 BarcodeDetector，不支持时使用 ZXing 回退。
• 统一返回值：不同平台扫码结果字段统一为 result、scanType、errMsg。
• 全端二维码生成：不依赖 DOM、不依赖 canvas，返回 PNG dataURL。
• Promise 和 callback 都支持：旧项目、新项目都能快速接入。
• 不上传数据：扫码、图片识别、二维码生成均在本地完成。

平台支持

安装方法

方法一：插件市场导入

1. 在 DCloud 插件市场打开本插件页面。
2. 点击“使用 HBuilderX 导入插件”。
3. 选择你的 uni-app 项目。
4. 导入后确认项目中存在：

uni_modules/JQ-UniScan-UTS

方法二：手动导入

1. 下载插件压缩包。
2. 解压后将 JQ-UniScan-UTS 目录复制到项目：

你的项目/uni_modules/JQ-UniScan-UTS

3. 重新运行或重新编译项目。

H5 依赖安装

如果需要在 H5 端使用摄像头扫码和图片识别，请在 HBuilderX 中执行：

工具 -> 插件安装三方依赖

或进入插件 H5 依赖目录安装：

cd uni_modules/JQ-UniScan-UTS/utssdk/web
npm install

H5 摄像头需要 HTTPS 或 localhost 环境，否则浏览器通常会禁止访问摄像头。

三分钟接入

在页面中引入插件：

import {
  createQRCode,
  decodeImage,
  getScanCapability,
  scanCode,
  scanCodeAsync
} from '@/uni_modules/JQ-UniScan-UTS/index.js'

1. 调起扫码

scanCode({
  scanType: ['all'],
  onlyFromCamera: false,
  success(res) {
    console.log('扫码结果：', res.result)
    console.log('码类型：', res.scanType)
  },
  fail(err) {
    console.log('扫码失败：', err.errMsg)
  }
})

2. 只允许相机扫码

scanCode({
  scanType: ['qrCode', 'barCode'],
  onlyFromCamera: true,
  success(res) {
    console.log(res.result)
  }
})

3. Promise 写法

async function scan() {
  try {
    const res = await scanCodeAsync({
      scanType: ['qrCode', 'barCode'],
      timeout: 30000
    })
    console.log(res.result)
  } catch (err) {
    console.log(err.errMsg)
  }
}

4. 相册识别

decodeImage({
  success(res) {
    console.log('图片识别结果：', res.result)
  },
  fail(err) {
    console.log(err.errMsg)
  }
})

说明：H5 端支持选择图片识别；App/小程序端建议使用 scanCode({ onlyFromCamera: false }) 调起平台扫码页，由平台扫码页提供相册入口。

5. 生成二维码

<template>
  <view>
    <image :src="qrCode" mode="aspectFit" style="width: 220px; height: 220px;" />
    <button @click="makeQRCode">生成二维码</button>
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { createQRCode } from '@/uni_modules/JQ-UniScan-UTS/index.js'

const qrCode = ref('')

function makeQRCode() {
  createQRCode({
    content: 'https://ext.dcloud.net.cn/',
    width: 280,
    margin: 2,
    darkColor: '#000000',
    lightColor: '#ffffff',
    errorCorrectionLevel: 'M',
    success(res) {
      qrCode.value = res.dataURL
    },
    fail(err) {
      console.log(err.errMsg)
    }
  })
}
</script>

createQRCode 返回 PNG dataURL，可直接赋值给 <image>。Android、iOS、HarmonyOS、H5、小程序均可使用。

6. 获取当前平台能力

const capability = getScanCapability()
console.log(capability)

返回示例：

{
  platform: 'uni-app',
  nativeScan: true,
  h5Camera: false,
  h5BarcodeDetector: false,
  h5ZXing: false,
  supportAlbum: true,
  supportFormats: ['barCode', 'qrCode', 'datamatrix', 'pdf417'],
  errMsg: 'getScanCapability:ok'
}

API 说明

scanCode(options)

兼容 uni.scanCode 的 callback 风格。

支持的 scanType：

[
  'all',
  'qrCode',
  'barCode',
  'datamatrix',
  'dataMatrix',
  'pdf417',
  'codabar',
  'code39',
  'code93',
  'code128',
  'ean8',
  'ean13',
  'itf',
  'upcA',
  'upcE',
  'aztec'
]

成功返回：

{
  result: string
  scanType: string
  charSet?: string
  path?: string
  rawData?: string
  errMsg: 'scanCode:ok'
}

失败返回：

{
  errMsg: string
  errCode?: number
  message?: string
  suggestion?: string
}

suggestion 是面向接入排查的中文建议，常见场景包括用户取消、摄像头权限未开、H5 非 HTTPS、扫码超时、相册图片不清晰等。

scanCodeAsync(options)

Promise 版本扫码 API。

const res = await scanCodeAsync({ scanType: ['all'] })

decodeImage(options)

识别图片中的二维码或条形码。

getScanCapability()

返回当前平台的扫码能力。

createQRCode(options)

生成二维码 PNG dataURL。

成功返回：

{
  dataURL: string
  tempFilePath: string
  errMsg: 'createQRCode:ok'
}

tempFilePath 当前默认为空，推荐直接使用 dataURL 显示。

完整页面示例

<template>
  <view class="page">
    <button @click="onScan">扫码</button>
    <button @click="onCreateQRCode">生成二维码</button>
    <image v-if="qrCode" :src="qrCode" mode="aspectFit" style="width: 220px; height: 220px;" />
    <text>{{ logText }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { createQRCode, scanCode } from '@/uni_modules/JQ-UniScan-UTS/index.js'

const logText = ref('等待操作')
const qrCode = ref('')

function onScan() {
  scanCode({
    scanType: ['all'],
    success(res) {
      logText.value = res.result
    },
    fail(err) {
      logText.value = err.errMsg
    }
  })
}

function onCreateQRCode() {
  createQRCode({
    content: 'https://ext.dcloud.net.cn/',
    width: 280,
    success(res) {
      qrCode.value = res.dataURL
      logText.value = res.errMsg
    },
    fail(err) {
      logText.value = err.errMsg
    }
  })
}
</script>

真机验证

当前功能链路已完成以下验证；1.0.1 为错误提示和资料迭代，市场上传前仍需按发布清单复跑 Android/iOS 真机：

• Android 真机：扫码成功，二维码生成成功。
• iPhone 真机：扫码成功，项目运行和资源同步成功。
• 微信小程序：编译通过。
• 本地校验：二维码 PNG dataURL 生成后可被 ZXing 反向解码。

权限说明

• Android/iOS/HarmonyOS/小程序：由平台扫码 API 申请摄像头权限。
• H5：浏览器会请求摄像头权限，需要 HTTPS 或 localhost。
• 相册识别：平台可能请求相册读取权限。

隐私说明

插件不采集、不存储、不上传扫码内容、图片内容或二维码内容。

• App/小程序扫码由平台本地扫码能力处理。
• H5 摄像头扫码在浏览器本地完成。
• H5 图片识别在浏览器本地完成。
• 二维码生成在本地内存中完成。

常见问题

H5 端打不开摄像头？

请确认页面运行在 HTTPS 或 localhost 环境，并且用户已允许浏览器摄像头权限。

返回 scanCode:fail cancel 是 bug 吗？

不是。用户点击返回、关闭扫码页或取消相册选择时，平台通常会返回 cancel。业务侧可以忽略该结果，或提示用户重新扫码。

App 端需要自定义基座吗？

基础扫码复用 uni-app 平台的 uni.scanCode，不额外集成第三方原生 SDK，通常可直接用 HBuilderX 标准基座测试。正式发布前仍建议在目标 Android/iOS 真机上跑一次示例项目，并确认摄像头权限正常。

购买前怎么确认当前平台能用？

先运行示例项目并调用 getScanCapability()。返回结果会列出当前端是否支持扫码、相册识别和二维码生成；H5 还需要 HTTPS 或 localhost 才能调用摄像头。

App 端相册识别为什么不是直接调用 decodeImage？

App、HarmonyOS、小程序端建议使用 scanCode({ onlyFromCamera: false })，由平台扫码页提供相册入口。H5 端才提供独立 decodeImage 图片识别。

H5 扫码超时怎么办？

先确认二维码完整入镜、光线充足、浏览器已授权摄像头。业务上可以调大 timeout，或让用户改用相册识别。

App 端为什么识别这么快？

App 端优先复用平台原生扫码相机，底层聚焦、曝光、识别链路由系统/平台能力完成，速度和准确率都优于普通 WebView 内自绘扫码。

小程序端是否需要单独配置？

通常不需要。小程序端调用平台扫码 API，具体码制和相册入口以对应小程序平台能力为准。

生成二维码是否依赖 canvas？

不依赖。插件内置纯 JS PNG 生成器，直接返回 dataURL，App/H5/小程序都可显示。

可以识别哪些码？

常用二维码、条形码、DataMatrix、PDF417 均已归一化支持；具体最终识别范围以平台扫码能力为准。

更新记录

详见 changelog.md。