更新记录

1.3.3（2026-10-04） 下载此版本

• package.json 的 displayName 改为简介内容去掉标点符号的版本
  • 与 description 信息保持一致，便于插件市场的检索匹配
  • 去掉中英文标点（，。、/ 等），并合并多余空格
  • 当前长度 107 字

1.3.2（2026-10-04） 下载此版本

• 调整 demo 页结构，解决「小程序端点哪个扫码都一样」的困惑
  • 现象：使用者在小程序端依次点击各 API 按钮，发现界面全无区别， 误以为插件失效（控制台其实已打印被忽略的参数警告）
  • 原因：demo 页把「组件用法」放在了最底部，而小程序端只有组件能自定义界面， API 按钮全部走微信原生扫码页
  • 处理：
  • 把「组件用法」卡片移到页面最顶部，并用主推样式（蓝色边框）突出
  • 小程序端说明卡片改为对比式说明（API vs 组件 的能力差异）， 并明确指向「用组件打开扫码」按钮
  • 小程序端在 API 区块前加一条分段提示 「以下均为 API 用法 · 小程序端界面参数不生效」

平台兼容性

uni-app(5.0)

simple-scan 扫码插件

跨平台扫码 UTS 插件，内置自定义全屏扫码页。支持二维码与条形码、手电筒、相册识别，可定制标题、提示与扫码框配色。

平台支持

⚠️ 小程序与鸿蒙端无法自定义界面（重要）

微信小程序与鸿蒙端的扫码界面由系统提供，插件只能调起系统扫码页。 因此 frameColor、frameSize、frameStyle、titleColor、buttonColor、 continuous、multi、customButtons 等所有界面与交互参数在这两端都不生效。

表现为：无论怎么配置，扫码页看起来都一样。

这不是 bug，是平台限制：

• 小程序端转发到 uni.scanCode，唤起的是微信原生扫码页， 该接口没有任何 UI 定制参数
• 鸿蒙端调用系统 Scan Kit，界面同样由系统控制

👉 小程序端需要自定义界面，请改用 <simple-scan-view> 组件 —— 组件在小程序端用 <camera> + cover-view 自绘界面，界面参数全部生效， 详见「组件用法」。 也可以改用 App（Android / iOS）或 H5，这两端用 scanCode() API 即可自定义。

小程序端在传入上述界面参数时，控制台会打印一条 [simple-scan] 开头的 警告并列出被忽略的参数，便于排查「配了没效果」的困惑。

功能支持矩阵

小程序分两列：组件 指 <simple-scan-view>，API 指 scanCode()。 两者能力差异很大，建议小程序端优先用组件，见上文「组件用法」。

界面类参数

功能类参数

矩阵说明

• ⚠️ scanLine 在小程序·组件：cover-view 对 CSS 动画支持有限， 目前是静态线条，没有上下往返动画
• ⚠️ showTorch 在 H5：依赖浏览器的 torch 能力，仅部分设备支持
• ❌ scanType 在 H5：底层 jsQR 只解二维码，返回类型固定为 qrCode
• ❌ scanType 在小程序·组件：<camera mode="scanCode"> 没有码类型过滤参数
• ❌ showAlbum 在小程序·组件：<camera mode="scanCode"> 只能实时扫码， 不支持从相册选图（需要相册识别请用 API 或 App / H5）
• ❌ multi 在 H5：jsQR 单帧只能解出一个码
• ❌ 鸿蒙的界面类参数：界面由系统 Scan Kit 提供，无法定制

小程序端自定义扫码界面

微信小程序可以自定义扫码界面，但需要用页面级的 <camera> 组件， 而不是 uni.scanCode：

<template>
    <view class="scan-page">
        <camera
            mode="scanCode"
            device-position="back"
            flash="auto"
            @scancode="onScanCode"
            @error="onCameraError"
        >
            <!-- camera 是原生组件，层级高于普通 view，
                 叠加 UI 必须用 cover-view / cover-image -->
            <cover-view class="scan-frame" />
        </camera>
    </view>
</template>

关键点：

插件已提供组件实现，不需要你自己写页面

上述逻辑已封装进 <simple-scan-view> 组件（见上文「组件用法」）， 小程序端直接用即可：

<simple-scan-view
    v-model:visible="showScan"
    frame-color="#19be6b"
    frame-style="border"
    @success="onSuccess"
/>

下面这些要点是组件内部的实现细节，列出来是为了方便你排查问题 （比如覆盖层被遮挡、相机不释放等），日常使用不需要关心。

H5 端依赖安装（必做）

H5 端的解码使用 jsQR， 依赖声明在 utssdk/web/package.json 中。

从插件市场导入后需要在该目录安装依赖，否则运行到 H5 会报 Failed to resolve import "jsqr"：

cd uni_modules/simple-scan/utssdk/web
npm install

说明：web/package.json 只声明依赖，不会自动安装。 这是 UTS 插件在 web 平台引入 npm 依赖的标准做法。

如果不想引入这个依赖，也可以改用浏览器原生的 BarcodeDetector API（零依赖）， 但 Safari 与 Firefox 不支持该 API，会失去这两个浏览器的扫码能力。

安装

1. 在 HBuilderX 中打开你的项目
2. 访问 DCloud 插件市场，搜索 simple-scan
3. 点击「下载插件并导入 HBuilderX」，选择你的项目

导入后插件位于 uni_modules/simple-scan。

快速上手

<script>
import { scanCode } from '@/uni_modules/simple-scan'

export default {
    methods: {
        onScan() {
            scanCode({
                success: (res) => {
                    console.log('扫描结果:', res.result)
                    console.log('码类型:', res.scanType)
                },
                fail: (err) => {
                    console.log('失败:', err.errCode, err.errMsg)
                }
            })
        }
    }
}
</script>

组件用法（推荐）

除 scanCode() API 外，插件还提供 <simple-scan-view> 组件。 easycom 已自动注册，无需 import。

<template>
    <view>
        <simple-button text="扫码" @click="showScan = true" />

        <simple-scan-view
            v-model:visible="showScan"
            title="组件扫码"
            tip="对准二维码即可识别"
            frame-color="#19be6b"
            frame-style="border"
            @success="onSuccess"
            @fail="onFail"
        />
    </view>
</template>

export default {
    data() {
        return { showScan: false }
    },
    methods: {
        onSuccess(res) {
            console.log('扫描结果:', res.result)
        }
    }
}

组件 vs API 怎么选

组件内部按平台分流：

为什么 App / H5 也转交 UTS？ 因为 uni-app 的 <camera> 组件只在各小程序端支持， App 与 H5 没有 camera 组件，组件内无法渲染相机预览。

组件属性

属性名与 scanCode() 的参数一一对应，仅多一个 visible：

组件事件

API

scanCode(options)

调起扫码页。

参数

success 回调参数

complete 回调参数

普通模式与 success 参数相同。连续模式下在关闭扫码页时触发，参数为：

onButtonTap 回调参数

fail 回调参数

错误码

9010008 是 H5 最常见的报错。浏览器的 navigator.mediaDevices 只在安全上下文中存在，因此用 http:// + 局域网 IP （如 http://192.168.1.100:5173/）打开页面时会报此错。 改用 http://localhost:5173/ 或部署到 https 即可。

用法示例

只识别二维码（更快）

scanCode({
    scanType: ['qrCode'],
    title: '扫一扫',
    tip: '将二维码放入框内',
    success: (res) => { console.log(res.result) }
})

自定义配色与文案

scanCode({
    title: '扫码核销',
    tip: '请对准商品二维码',
    frameColor: '#19be6b',
    maskColor: '#B3000000',
    showTorch: true,
    showAlbum: true,
    vibrate: true,
    success: (res) => { console.log(res.result) }
})

只允许相机扫码

scanCode({
    onlyFromCamera: true,
    success: (res) => { console.log(res.result) }
})

连续扫码（盘点 / 入库）

相机不关闭，扫一个回调一次，适合批量录入场景。

scanCode({
    continuous: true,
    title: '连续扫码',
    tip: '对准二维码，可连续扫描',
    success: (res) => {
        // 每识别到一个就回调一次，自行累积即可
        console.log('第', res.index + 1, '个:', res.result)
    },
    complete: (res) => {
        // 关闭扫码页时触发，res.count 为本次累计数量
        console.log('共识别', res.count, '个')
    }
})

同一个码在 2 秒内只会回调一次，避免相机每秒几十帧导致重复触发。

多码同时识别

一帧画面里的多个码会一次性全部返回。

scanCode({
    multi: true,
    success: (res) => {
        console.log('第', res.index + 1, '/', res.total, '个:', res.result)
    }
})

相册批量识别

scanCode({
    albumMultiple: true,   // 相册多选
    multi: true,           // 配合多码识别，一张图里的多个码也都能识别
    success: (res) => {
        console.log(res.result, res.index + 1, '/', res.total)
    }
})

自定义按钮位

UTS 插件无法接收 Vue 插槽，因此用「传配置数组」的方式在扫码页上加按钮。

scanCode({
    customButtons: [
        { id: 'manual', text: '手动输入' }
    ],
    onButtonTap: (res) => {
        if (res.id === 'manual') {
            // 这里可以跳转到自己的「手动输入」页
        }
    },
    success: (res) => { console.log(res.result) }
})

关闭扫描线动画

scanCode({
    scanLine: false,
    success: (res) => { console.log(res.result) }
})

界面定制

扫码页的所有视觉元素都可以通过参数定制，不需要写代码。

限制说明：UTS 插件是原生能力层，无法接收 Vue 插槽， 因此不能把自定义的 Vue 组件放进扫码页。 需要在扫码页上增加交互入口时，用 customButtons（见上文「自定义按钮位」）。

可定制项一览

完整示例：品牌主题

scanCode({
    title: '扫码核销',
    tip: '请对准商品二维码',
    frameColor: '#ff6b00',        // 扫码框橙色
    frameSize: 0.75,              // 放大到短边的 75%
    frameRadius: 16,              // 圆角
    frameStyle: 'border',         // 完整边框
    scanLineColor: '#ffcc00',     // 扫描线单独配色
    maskColor: '#B3000000',       // 遮罩加深
    titleColor: '#ffffff',
    titleSize: 18,
    tipColor: '#ffd8a8',
    tipSize: 15,
    buttonColor: '#ff6b00',
    buttonBgColor: '#33ff6b00',
    success: (res) => { console.log(res.result) }
})

完整示例：极简

scanCode({
    title: '',                    // 不要标题
    tip: '',
    showClose: true,              // 保留关闭按钮，否则没法退出
    frameStyle: 'none',           // 不画框
    scanLine: false,              // 不要扫描线
    maskColor: '#66000000',       // 遮罩调浅
    success: (res) => { console.log(res.result) }
})

⚠️ title 与 tip 传空字符串即可隐藏，但建议保留 showClose: true—— 否则用户在扫码页上没有可见的退出入口（Android 物理返回键仍可退出）。

生效平台

上述界面参数仅 Android / iOS / H5 生效。 鸿蒙与微信小程序由系统提供扫码界面，配色、字号、框样式等参数不生效。

已知限制

不支持 DPM 码

DPM（Direct Part Marking，直接零件打标）码无法识别。

DPM 指激光蚀刻在金属 / 塑料表面的点状 DataMatrix 码，常见于工厂零部件盘点。 本插件底层依赖的 ML Kit Barcode Scanning 不支持 DPM （Google 官方仓库 issue #1053 已确认「DPM Data Matrix / ECC 200 检测不到」），iOS 的 Vision 同样不支持。

这是底层引擎的限制，不是插件实现问题。DPM 需要专门的工业解码算法， 目前只有商业方案提供：

DPM 场景建议直接使用工业扫码枪，手机方案的识别率难以满足产线要求。

识别率受图像质量影响

本插件未做额外的图像增强预处理。若场景对识别率有更高要求， 建议在采集端改善光照与对焦——效果远好于事后算法补偿。

App 端运行环境（Android）

本插件在 Android 端依赖以下三方库，因此无法用标准基座直接运行：

运行到 Android 真机时若报 kotlin编译失败 / 找不到名称 "camera"， 说明本地编译环境尚未配置，HBuilderX 无法下载上述依赖。二选一：

方案一：配置本地运行环境（推荐）

HBuilderX【设置 - 运行配置】（4.27 之前为「设置 - 插件配置」）需填三项：

SDK 可通过安装 Android Studio 获得（首次启动会自动下载）， 或单独下载 Command line tools 后手动安装：

sdkmanager --sdk_root=%sdk路径% --install "build-tools;30.0.0"
sdkmanager --sdk_root=%sdk路径% --install "platforms;android-30"

配置完成后首次运行会自动下载依赖，缓存到 用户目录/.gradle/caches， 之后运行会跳过检测和下载。

官方文档：Android UTS 扩展开发

方案二：云端打包自定义基座

不想装本地环境时，可提交云端打包自定义基座。 代价是每次改动原生代码都要重新打包，调试较慢。

⚠️ 若报错信息末尾出现 [AI修复]，不用理会—— 这属于运行环境未配置，不是代码问题，AI 修复也改不动环境。

注意事项

1. App 端需自定义基座：插件依赖 CameraX 与 ML Kit（Android）、AVFoundation（iOS）， 这些原生依赖需云端打包才能生效。标准基座无法运行 App 端扫码。

   Kotlin 混编代码本身标准基座即可生效，但 config.json 中声明的第三方依赖需要自定义基座。

2. iOS 需要相机权限描述：在 manifest.json 的 iOS 配置中补充 NSCameraUsageDescription 与 NSPhotoLibraryUsageDescription，否则提交审核会被拒。
3. 鸿蒙与小程序端 UI 由系统提供：frameColor / maskColor 两个配色参数在这两端不生效， 其余参数（标题、提示、手电筒、相册、码类型）正常。
4. H5 端需要 https：浏览器出于安全限制，非 https / localhost 环境无法访问摄像头。
5. 相册识别：Android 走 SAF 选图，无需存储权限；iOS 走系统相册选择器。

目录结构

uni_modules/simple-scan/
├── components/
│   └── simple-scan-view/
│       └── simple-scan-view.vue   # Vue 组件（小程序端自绘界面）
├── utssdk/
│   ├── interface.uts          # 对外 API 声明
│   ├── unierror.uts           # 错误码实现
│   ├── utils.uts              # 参数归一化与回调分发（各平台共用）
│   ├── index.uts              # 兜底实现（未支持平台）
│   ├── app-android/
│   │   ├── config.json        # CameraX + ML Kit 依赖
│   │   ├── AndroidManifest.xml
│   │   ├── ScanNative.kt      # UTS 桥接
│   │   ├── ScanActivity.kt    # 全屏扫码页
│   │   ├── ScanFrameView.kt   # 扫码框遮罩
│   │   └── index.uts
│   ├── app-ios/
│   │   ├── config.json
│   │   ├── ScanNative.swift   # UTS 桥接
│   │   ├── ScanViewController.swift
│   │   └── index.uts
│   ├── app-harmony/index.uts
│   ├── web/
│   │   ├── package.json       # jsqr 依赖
│   │   └── index.uts
│   └── mp-weixin/index.uts
├── package.json
├── readme.md
└── changelog.md

更新日志

见 changelog.md