更新记录

1.0.0（2026-07-19） 下载此版本

初次提交

平台兼容性

uni-app x(4.66)

其他

laoqianjunzi-scan

laoqianjunzi-scan 是一个面向 uni-app x / uni-app 的统一扫码插件，围绕“同一套 API 覆盖全屏扫码、嵌入式扫码、图片识别、二维码生成与能力探测”来设计。

文档只说明当前插件的正式能力与公开 API，不涉及旧插件、旧接口或兼容层。

功能概览

• 全屏扫码：通过 openScan() 拉起插件内部扫码页，支持标题、提示文案、扫描框、补光灯、相册按钮与多码策略配置。
• 嵌入式扫码：通过 laoqianjunzi-scan 组件把扫码预览直接嵌入业务页面。
• 图片识别：支持本地图片路径、Base64、URL、直接选图识别。
• 二维码生成：通过 createQrCodeImage() 生成二维码图片文件。
• 统一结果模型：所有扫码结果都归一到 ScanSuccess / ScanItem / ScanPayload。
• 运行时能力探测：通过 getScanCapabilities() 判断当前平台是否支持多码、变焦、预热、镜头切换等能力。
• 会话状态追踪：通过 getCurrentSession() 获取当前扫码会话快照。

适用版本

平台支持

插件包当前声明支持：Android、iOS、Harmony、Web、微信小程序。

能力矩阵

建议在业务中先调用 getScanCapabilities()，再按平台动态开启多码、自动变焦、预热等高级特性。

安装与引入

将插件安装到项目 uni_modules 后，可直接从 utssdk/index.uts 引入 API：

import {
    openScan,
    pickImageAndScan,
    createQrCodeImage,
    getScanCapabilities
} from '@/uni_modules/laoqianjunzi-scan/utssdk/index.uts'

嵌入式组件可直接使用 easycom：

<laoqianjunzi-scan @scan="handleScan"></laoqianjunzi-scan>

快速开始

1. 打开全屏扫码

openScan({
    mode: 'page',
    continuous: false,
    multiCodePolicy: 'first',
    allowAlbum: true,
    defaultTorchOn: false,
    parseSemantic: true,
    outputAllCodeData: false,
    formats: ['all'],
    legacyFormatMask: 'all',
    ui: {
        brandTitle: '***',
        hintText: '将二维码或条码放入取景框内即可自动识别',
        showAlbumButton: true,
        showTorchButton: true,
        showCloseButton: true,
        showCornerMarkers: true,
        showScanLine: true,
        localeText: null
    },
    success: (result) => {
        console.log('scan success', result.primary.rawText)
    },
    fail: (error) => {
        console.log('scan fail', error.errMsg)
    },
    cancel: () => {
        console.log('scan cancel')
    },
    complete: null
})

2. 页面内嵌扫码

<template>
    <laoqianjunzi-scan
        :autoOpen="false"
        :allowAlbum="true"
        :continuous="true"
        :outputAllCodeData="false"
        :multiCodePolicy="'first'"
        :formatMask="'all'"
        @scan="handleScan"
        @error="handleError"
        @cancel="handleCancel"
    ></laoqianjunzi-scan>
</template>

组件内部已经集成了开始扫码、关闭、补光灯、识别图片等控制按钮，适合作为业务页里的直接演示或中型表单辅助录入区。

3. 直接选图识别

pickImageAndScan({
    parseSemantic: true,
    outputAllCodeData: false,
    formats: ['all'],
    legacyFormatMask: 'all',
    success: (result) => {
        console.log('image scan', result.primary.rawText)
    },
    fail: (error) => {
        console.log(error.errMsg)
    },
    cancel: () => {
        console.log('user cancel')
    },
    complete: null
})

4. 生成二维码图片

createQrCodeImage({
    content: 'https://example.com',
    width: 480,
    height: 480,
    margin: 2,
    foregroundColor: '#0D5E54',
    backgroundColor: '#FFFFFF',
    fileName: 'demo-qrcode.png',
    success: (filePath) => {
        console.log(filePath)
    },
    fail: (error) => {
        console.log(error.errMsg)
    },
    complete: null
})

5. 读取能力探测结果

const capabilities = getScanCapabilities()
console.log(capabilities.page)
console.log(capabilities.multiCode)
console.log(capabilities.autoZoom)

公开 API

扫码与识别

二维码生成

openScan() 常用参数

码制枚举

支持的 formats 值包括：

all、qrCode、aztec、codabar、code39、code93、code128、dataMatrix、ean8、ean13、itf、pdf417、upcA、upcE、rss14、rssExpanded、maxiCode、wxCode、code25。

嵌入式组件 laoqianjunzi-scan

组件属性

组件事件

组件实例方法

组件内部实现了以下同名方法：openScanner()、closeScanner()、toggleTorch()、pickImage()、switchCamera()。

如果你通过模板 ref 获取到组件实例，可按需调用这些方法；如果只是常规业务接入，直接使用组件内置按钮即可。

返回结果结构

ScanSuccess

ScanItem

示例页面

插件自带两类页面：

• pages/index.uvue：对外演示页，集中展示能力探测、全屏扫码、嵌入式扫码、图片识别和二维码生成。
• pages/scan-dialog/index.uvue：插件内部全屏扫码承载页，由 openScan() 自动拉起，业务侧无需手动跳转。

如果你想快速验证插件效果，直接打开 uni_modules/laoqianjunzi-scan/pages/index 即可。

权限与接入建议

• Android / iOS：需要相机权限；使用图片识别时还需要相册读取权限。
• Harmony：需要相机权限；图片识别和文件写入能力依赖当前平台运行环境。
• Web：相机、补光灯、镜头切换受浏览器能力与 HTTPS 环境影响。
• 微信小程序：多码、自动变焦、预热等高级能力请先用 getScanCapabilities() 判定。
• 如果业务页需要滚动展示多个说明块，App 端请用 scroll-view 承载页面内容。

调试建议

• 先跑 getScanCapabilities()，确认当前平台能力边界。
• 先在 pages/index.uvue 验证公开 API，再迁移到业务页。
• 多码、自动变焦、补光灯、镜头切换这些体验差异较大的功能，建议分平台逐项验证。
• 如果需要和业务表单联动，优先消费 ScanSuccess.primary.rawText 与 ScanSuccess.option。