更新记录

1.1.0（2026-07-22） 下载此版本

增强：权限错误码区分、关闭/相册识图、码制过滤、成功震动、连续扫码；Kotlin 模块拆分

平台兼容性

uni-app(5.0)

uni-app x(5.0)

其他

kex-code-scan

Android 端扫码 UTS API 插件（非 Vue 组件）。
基于 CameraX + Google ML Kit，支持全格式条码/二维码、多码同屏点选、智能变焦、相册识图、连续扫码。

支持：Android App（uni-app Vue2/Vue3）。
暂不支持：iOS / 鸿蒙 / H5 / 小程序 / nvue。

依赖原生三方库，必须使用自定义调试基座或正式云打包后才能真机调用。

目录

1. 功能一览
2. 安装
3. 制作自定义基座（必做）
4. 快速上手
5. 进阶用法
6. API
7. 错误码
8. 扫码页交互说明
9. 码制 formats 取值
10. 常见问题
11. 注意事项
12. 目录结构
13. 版本

功能一览

安装

将插件拷贝到业务项目：

你的项目/uni_modules/kex-code-scan/

UTS 插件需 import 后调用，不会 easycom 自动注册组件。

要求：

• HBuilderX ≥ 3.6.8（建议较新版本）
• uni-app Vue2 / Vue3 均可
• 仅 Android；需制作自定义基座

本仓库演示页：首页 → kex-code-scan，或路径 /pages/demos/code-scan/index。

制作自定义基座（必做）

插件依赖：

• androidx.camera:* 1.4.1
• com.google.mlkit:barcode-scanning 17.3.0

标准基座不含上述库，不制作自定义基座会调用失败 / 编译不过。

步骤

1. HBuilderX 菜单：运行 → 运行到手机或模拟器 → 制作自定义调试基座
2. 选择当前项目，填写 Android 包名、证书（可用公共测试证书）
3. 云打包，等待完成并安装到手机
4. 之后每次运行选择 「自定义调试基座」，再打开演示页或业务页调试扫码

正式发版：使用 云打包 / 本地打包 生成安装包即可（打包流程会带上 UTS 原生依赖）。

快速上手

1. uni-app（Vue3 <script setup>）

<template>
  <view>
    <button type="primary" @click="doScan">扫码</button>
    <text>{{ tip }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { openCodeScan } from '@/uni_modules/kex-code-scan'

const tip = ref('')

const doScan = () => {
  openCodeScan({
    success: (res) => {
      tip.value = res.content + ' / ' + res.format
    },
    fail: (err) => {
      tip.value = err.errMsg + '（' + err.errCode + '）'
    }
  })
}
</script>

2. uni-app（Options API）

import { openCodeScan } from '@/uni_modules/kex-code-scan'

export default {
  methods: {
    doScan() {
      openCodeScan({
        success: (res) => {
          console.log(res.content, res.format, res.fromAlbum)
        },
        fail: (err) => {
          console.log(err.errCode, err.errMsg)
        },
        complete: () => {
          console.log('扫码流程结束')
        }
      })
    }
  }
}

3. 最少参数

import { openCodeScan } from '@/uni_modules/kex-code-scan'

openCodeScan({
  success: (res) => console.log(res.content)
})

进阶用法

只扫二维码

openCodeScan({
  formats: ['QR_CODE'],
  success: (res) => console.log(res.content)
})

关闭智能变焦 / 震动

openCodeScan({
  smartZoom: false,
  vibrate: false,
  success: (res) => console.log(res.content)
})

打开后直接进相册

openCodeScan({
  fromAlbum: true,
  success: (res) => {
    console.log(res.content, res.fromAlbum) // fromAlbum === true
  }
})

扫码页内也可随时点左下角 相册 按钮选图识别。

连续扫码

页内不关闭，每识别一次触发一次 success；用户点左上角关闭（或系统返回）后走 complete（若已有命中，不会再走 fail）。

const list = []

openCodeScan({
  continuous: true,
  vibrate: true,
  success: (res) => {
    list.push(res.content)
    console.log('命中', res.content, res.format)
  },
  fail: (err) => {
    // 一次都没扫到就关闭 → 一般是 9021003 取消
    console.log('失败', err.errCode, err.errMsg)
  },
  complete: (res) => {
    if (res && res.closed) {
      console.log('结束，共', res.hitCount, '次', list)
    }
  }
})

组合：仅二维码 + 连续扫 + 相册入口

openCodeScan({
  formats: ['QR_CODE'],
  continuous: true,
  smartZoom: true,
  vibrate: true,
  success: (res) => console.log(res),
  complete: (res) => console.log('done', res)
})

API

openCodeScan(options?)

打开全屏扫码页。

CodeScanOptions

CodeScanSuccess

CodeScanFail

继承 UniError：

类型定义（摘录）

type CodeScanOptions = {
  smartZoom?: boolean
  formats?: string[]
  vibrate?: boolean
  continuous?: boolean
  fromAlbum?: boolean
  success?: (res: CodeScanSuccess) => void
  fail?: (res: CodeScanFail) => void
  complete?: (res: any) => void
}

type CodeScanSuccess = {
  content: string
  format: string
  fromAlbum?: boolean
}

错误码

说明：

• fail 与 complete 在失败时都会触发（连续扫「已有命中后关闭」除外：只 complete）。
• 打开即相册且无相机权限时，仍可用相册；点关闭且无命中 → 一般为 9021003。

扫码页交互说明

码制 formats 取值

传入字符串数组，非法值忽略；若解析后为空则按全格式。

示例：

formats: ['QR_CODE', 'CODE_128', 'EAN_13']

常见问题

1. 点击没反应 / 报找不到类？

未使用自定义基座。请按上文制作并选择「自定义调试基座」再运行。

2. 提示相机权限被拒绝（9021002）？

到系统设置打开应用相机权限后重试。

3. 连续扫只回调一次？

确认传了 continuous: true。同一内容约 1.2 秒内会去重，避免狂刷；换个码或稍等再扫。

4. 相册选了图但提示未识别？

图中可能没有清晰条码，或被 formats 过滤掉。可先不传 formats 试全格式。

5. iOS / 鸿蒙能用吗？

当前版本仅 Android。目录未包含 iOS/鸿蒙实现。

6. 能否当组件标签用？

不能。这是 UTS API，请 import { openCodeScan } from '@/uni_modules/kex-code-scan' 后调用。

注意事项

1. 仅 Android；发布市场包请走正式打包，勿依赖标准基座调试结果。
2. 需相机权限；震动权限已在插件 Manifest 声明（vibrate: false 可不震动）。
3. 相册选图走系统选择器，一般无需额外存储权限（视系统版本而定）。
4. 连续扫依赖原生命中队列 + 桥接轮询，关闭页后务必以 complete 收尾业务状态。
5. 多码点选依赖定位框；少数码无包围盒时走单码自动完成逻辑。
6. 文档与演示不保证覆盖所有机型相机差异，建议主流机型回归。

目录结构

kex-code-scan/
├── package.json
├── readme.md
├── changelog.md
├── FEATURES.md
└── utssdk/
    ├── interface.uts          # 对外类型与 API 声明
    ├── unierror.uts           # 错误实现
    └── app-android/
        ├── index.uts          # JS/UTS 桥接
        ├── config.json        # 原生依赖
        ├── AndroidManifest.xml
        ├── CodeCaptureActivity.kt
        ├── MultiCodePickView.kt
        ├── ScanFrameDecorView.kt
        ├── YuvFrames.kt
        ├── SymbologyUtil.kt
        ├── CodeScanHitBus.kt
        └── res/drawable/      # 关闭/相册等资源

版本

更多变更见 changelog.md。能力清单见 FEATURES.md。

相关链接

• UTS 语法
• UTS API 插件
• 制作自定义调试基座