更新记录

1.3.0（2026-09-04）

1.3.0（2026-08-29）

新增

• scanStyle.cornerStyle 新增 rounded 完整圆角边框和 rounded-corner 四角圆角边框。
• 新增 scanStyle.cornerRadius，单位 dp，范围 0 ~ 160，默认 20。
• 两种圆角扫描框启用遮罩时，遮罩缺口和扫描线同步按同一圆角路径裁剪。

兼容性

• 保留 corner 四角边框与 full 完整矩形边框的原有绘制和调用方式。
• 圆角半径会自动限制在扫描框短边的一半以内，适配窄条码扫描框。

1.2.0（2026-08-28）

新增

• 新增独立的 scanStyle 配置，不再将视觉表现与 scanRegion 识别区域混合。
• 支持 showMask，可控制扫描框外遮罩的显示与隐藏。
• 支持 showBeam，可控制扫描线的显示与隐藏。
• 支持 borderColor、maskColor、beamColor 自定义边框、遮罩和扫描线颜色。
• 支持 beamDuration 配置扫描线移动周期，原生层限制为 100 ~ 60000 毫秒。
• 支持 cornerStyle：corner 四角边框、full 完整矩形边框。
• README 补充扫描区域、视觉样式、扫码页交互、生命周期回调和错误码说明。
• 新增 9021005 ~ 9021011 细化错误码，覆盖相机占用/初始化、相册读取与无条码、非法 formats 和单次扫码超时。
• 新增可选 scanTimeout，单次扫码可设置 1000 ~ 600000 毫秒超时；连续扫码不启用超时。

兼容性

• 保持原有 openCodeScan 调用方式不变。
• 未传 scanStyle 时使用默认样式：绿色边框、半透明黑色遮罩、绿色扫描线、四角边框。
• scanStyle 仅影响 Android 扫描页绘制，不改变条码识别逻辑。
• 同屏多码定格后的绿色点选标记增加呼吸波纹动画，帮助用户快速定位可点击目标。

平台兼容性

uni-app(5.0)

其他

mas-code-scan

Android 端扫码 UTS API 插件（非 Vue 组件）。
基于 CameraX + Google ML Kit，支持全格式条码/二维码、多码同屏点选、识别区域过滤、扫描框视觉配置、智能变焦、手势缩放、相册识图、连续扫码、手电筒策略、结果确认和暂停控制。

插件对外只提供 openCodeScan 一个 UTS API。扫码页由原生 Android Activity 提供，识别结果通过 success、fail、complete 回调返回。

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

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

插件定位与工作流程

mas-code-scan 是一个打开原生 Android 扫码 Activity 的 UTS API 插件，不是 Vue 组件，也不是对 uni.scanCode 的简单包装。一次扫码流程如下：

1. 业务页面调用 openCodeScan(options)。
2. 插件启动全屏竖屏原生扫码页，并根据参数初始化 CameraX、ML Kit 和界面控件。
3. 相机帧交给 ML Kit 识别；如果配置了 scanRegion，实时结果还会经过扫描框中心点过滤。
4. 单码按照 resultMode 返回；多码进入定格点选；连续模式通过 success 多次上报。
5. Activity 结束后通过 complete 收尾；失败场景同时通过 fail 和 complete 通知。

能力边界

• 识别引擎：Google ML Kit Barcode Scanning。
• 相机管线：CameraX，使用后置摄像头，预览采用 FILL_CENTER 填充显示。
• 图片来源：实时相机帧、系统相册图片。
• 原生页面：全屏、竖屏、无标题栏；关闭、相册、手电筒和连续扫码暂停按钮由插件绘制。
• 生命周期：每次调用创建一个扫码会话；关闭、成功、权限失败、超时或初始化失败后会话结束。

目录

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

功能一览

安装

将插件拷贝到业务项目：

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

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

要求：

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

本仓库演示页：/pages/scan/prototype.vue`，用于在 Android 自定义基座中验证插件能力。页面包含：

• 智能变焦、成功震动、手电筒策略、结果处理模式和连续扫码暂停按钮。
• 扫码页标题、扫描引导语、成功提示语、无结果提示语自定义。
• 连续扫码成功提示停留时长、单次扫码超时配置。
• 二维码正方形框、横向条码框和全屏识别三种识别区域预设；横向条码框支持上/中/下位置、自定义上下微调和三档高度。
• 扫描框遮罩、扫描线、边框颜色、遮罩颜色、扫描线颜色、扫描线周期、四种边框形态和圆角半径配置。
• 二维码、CODE 128、EAN-13 码制筛选，相册识图、单次扫码、连续扫码和本地结果列表。

演示页的“最近结果”仅保存在当前页面内，用于展示回调结果，不会提交业务接口。

制作自定义基座（必做）

插件依赖：

• 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/mas-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/mas-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/mas-code-scan'

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

进阶用法

自定义扫码页文案

以下参数只影响原生扫码页显示文字，不影响识别逻辑：

openCodeScan({
  title: '扫描商品码',
  hint: '请将商品条码放入框内',
  successHint: '识别成功',
  emptyHint: '图片中没有商品条码',
  success: (res) => console.log(res.content)
})

• title：顶部标题，默认 扫一扫。
• hint：扫描框下方引导语，默认 请将条码放入扫描框内。
• successHint：连续扫码成功提示层标题，也用于部分原生提示，默认 扫码成功。
• emptyHint：相册图片未识别到条码时的提示，默认 未识别到有效条码。
• 空字符串或全空格会回退到默认文案；原生层会去除首尾空格。

只扫二维码

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

手电筒和结果处理

openCodeScan({
  torch: 'auto', // 'off' | 'on' | 'auto'
  resultMode: 'confirm', // 'immediate' | 'confirm' | 'pause'
  success: (res) => console.log(res.content)
})

confirm 会弹出结果确认框；pause 会暂停识别并提供“继续扫描/确认”操作。两种模式下，点击确认才会结束并触发 success、complete；点击重新扫描或继续扫描会恢复相机识别，不会触发失败回调。

设置单次扫码超时

openCodeScan({
  scanTimeout: 15000,
  success: (res) => console.log(res.content),
  fail: (err) => {
    if (err.errCode === 9021011) console.log('15 秒内未识别到条码')
  }
})

scanTimeout 单位为毫秒。只有单次扫码且值在 1000 ~ 600000 时启用；不传、传 0 或小于 1000 时不启用。连续扫码始终不启用单次超时。

关闭智能变焦 / 震动

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

配置扫描区域

scanRegion 同时决定扫描框的位置和实时识别过滤区域。宽度、高度、中心点均使用 0 ~ 1 的比例值；宽高以预览宽度为参考，越界值会由原生层收敛到可显示范围。scanRegion 只作用于实时相机，不裁剪或过滤相册图片。

openCodeScan({
  scanRegion: {
    width: 0.96,
    height: 0.24,
    centerX: 0.5,
    centerY: 0.5
  },
  success: (res) => console.log(res.content)
})

• 不传 scanRegion：保持全屏识别，同时保留默认扫描框显示。
• scanRegion: { fullScreen: true }：整画面识别，不显示扫描框，也不进行区域过滤。
• 配置扫描区域后，条码中心点必须落在扫描框内才会被实时相机识别结果接受。
• 相册识图不受 scanRegion 限制。

配置扫描框视觉样式

scanStyle 只控制扫描页视觉表现，不改变识别区域。颜色支持 #RRGGBB、#AARRGGBB；遮罩还支持 rgba(r, g, b, a)。

openCodeScan({
  scanRegion: {
    width: 0.96,
    height: 0.24,
    centerX: 0.5,
    centerY: 0.5
  },
  scanStyle: {
    showMask: true,
    showBeam: true,
    borderColor: '#19be6b',
    maskColor: 'rgba(0, 0, 0, 0.45)',
    beamColor: '#12e880',
    beamDuration: 1800,
    cornerStyle: 'rounded',
    cornerRadius: 20
  },
  success: (res) => console.log(res.content)
})

• showMask: false 仅隐藏框外遮罩，不会扩大或改变识别范围。
• showBeam: false 隐藏扫描线；扫描线周期 beamDuration 单位为毫秒，原生层限制在 100 ~ 60000。
• cornerStyle: 'corner' 显示直角四角边框，'full' 显示完整矩形边框，'rounded' 显示完整圆角边框，'rounded-corner' 显示四角圆角边框。
• cornerRadius 为圆角半径，单位为 dp，范围 0 ~ 160，在两种圆角边框样式下均生效；圆角遮罩缺口和扫描线会同步裁剪为相同圆角。
• rounded 是四边完整的圆角边框；rounded-corner 只绘制四个带圆弧过渡的角，中间不连接四条边。
• 圆角半径最终还会限制在扫描框短边的一半以内，适合二维码框和横向条码框。
• 当未启用 scanRegion 时，视觉样式仅作用于默认扫描框；fullScreen: true 时不会显示扫描框。

打开后直接进相册

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

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

连续扫码

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

const list = []

openCodeScan({
  continuous: true,
  showPauseButton: 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

ScanRegion

区域映射会补偿 PreviewView 的 FILL_CENTER 裁剪偏移和图像旋转；最终判断的是 ML Kit 包围盒的中心点是否在区域内，而不是要求整个条码完全位于框内。

建议：二维码使用接近正方形的区域，横向条码使用较宽且较矮的区域；如果业务只需要识别、不需要框选提示，可使用 fullScreen: true。

组合约束与默认行为

CodeScanStyle

默认值：showMask: true、showBeam: true、borderColor: '#19be6b'、maskColor: 'rgba(0, 0, 0, 0.45)'、beamColor: '#12e880'、beamDuration: 1800、cornerStyle: 'corner'、cornerRadius: 20。非法颜色会回退到默认值，beamDuration 会限制在 100 ~ 60000 毫秒，cornerRadius 会限制在 0 ~ 160 dp。

示例：

openCodeScan({
  scanRegion: {
    width: 0.96,
    height: 0.24,
    centerX: 0.5,
    centerY: 0.5
  },
  scanStyle: {
    showMask: true,
    showBeam: true,
    borderColor: '#19be6b',
    maskColor: 'rgba(0, 0, 0, 0.45)',
    beamColor: '#12e880',
    beamDuration: 1800,
    cornerStyle: 'rounded',
    cornerRadius: 20
  },
  success: (res) => console.log(res.content)
})

scanRegion 控制实时识别区域，scanStyle 只控制扫描页的视觉表现；两者可以独立配置。不传 scanRegion 时实时相机按全画面识别，但仍显示原生默认扫描框；需要隐藏扫描框时请传 scanRegion: { fullScreen: true }。

回调返回值与生命周期

单次扫码成功：

success({ content: '...', format: 'QR_CODE', fromAlbum: false })
complete({ content: '...', format: 'QR_CODE', fromAlbum: false })

单次扫码失败或用户取消：

fail({ errCode: 9021003, errMsg: '用户取消扫码', errSubject: 'mas-code-scan' })
complete({ errCode: 9021003, ... })

连续扫码关闭：

complete({ closed: true, hitCount: 3 })

连续扫码如果一次命中都没有就关闭，通常会先触发 fail(9021003)，随后触发 complete({ closed: true, hitCount: 0, failed: true, errCode: 9021003 })。已有命中后关闭只触发 complete，不会触发 fail。

CodeScanSuccess

CodeScanFail

继承 UniError：

回调规则：

• 单次扫码成功：依次调用 success、complete，成功对象包含 content、format 和 fromAlbum。
• 单次扫码失败或取消：依次调用 fail、complete。
• 连续扫码：每次命中调用一次 success；关闭页面时调用 complete({ closed: true, hitCount })。
• 连续扫码在已有命中后关闭：不会再调用 fail，只调用 complete。
• 相册识图成功：fromAlbum 为 true；相机实时识别成功时为 false。

类型定义（摘录）

type CodeScanOptions = {
  title?: string
  hint?: string
  successHint?: string
  emptyHint?: string
  smartZoom?: boolean
  formats?: string[]
  vibrate?: boolean
  torch?: 'off' | 'on' | 'auto'
  resultMode?: 'immediate' | 'confirm' | 'pause'
  continuous?: boolean
  continuousSuccessDuration?: number
  showPauseButton?: boolean
  fromAlbum?: boolean
  scanRegion?: {
    fullScreen?: boolean
    width?: number
    height?: number
    centerX?: number
    centerY?: number
  }
  scanStyle?: {
    showMask?: boolean
    showBeam?: boolean
    borderColor?: string
    maskColor?: string
    beamColor?: string
    beamDuration?: number
    cornerStyle?: 'corner' | 'full' | 'rounded' | 'rounded-corner'
    cornerRadius?: number
  }
  // 单次扫码超时（毫秒）；小于 1000 或不传则不启用，最大 600000；连续扫码不启用超时
  scanTimeout?: number
  success?: (res: CodeScanSuccess) => void
  fail?: (res: CodeScanFail) => void
  complete?: (res: any) => void
}

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

错误码

说明：

• 9021001 ~ 9021004 为已有错误码，含义保持不变；新增错误码从 9021005 开始。
• fail 与 complete 在失败时都会触发（连续扫「已有命中后关闭」除外：只 complete）。
• 打开即相册且无相机权限时，仍可用相册；点关闭且无命中 → 一般为 9021003。
• 无闪光灯不影响扫码，因此 9021006 仅通过扫码页提示展示，不会触发 fail。

扫码页交互说明

码制 formats 取值

传入字符串数组；空/缺省时按全格式。若 formats 非空但全部不受支持，调用失败并返回 9021010。

补充规则：插件会忽略未知 token；只要数组中存在一个有效 token 就使用有效 token。数组非空但全部无效时返回 9021010。ALL 与其他有效码制同时传入时最终使用全格式。

示例：

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

常见问题

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

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

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

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

3. 连续扫只回调一次？

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

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

图中可能没有清晰条码，或被 formats 过滤掉。可先不传 formats 试全格式；打开即相册且没有可用相机时，会以 9021009 返回无条码错误。

5. 为什么会提示扫码超时（9021011）？

仅在单次扫码传入 scanTimeout（1000 ~ 600000 毫秒）后启用。超时不会影响连续扫码；不需要限制时不传该参数或传 0。

6. iOS / 鸿蒙能用吗？

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

7. 能否当组件标签用？

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

8. 演示页可以直接当业务页面使用吗？

prototype.vue 是能力验证页面，结果列表是本地状态，不包含业务接口提交、权限引导和业务字段转换。正式业务建议复制 openScan 调用方式，在自己的页面中处理 success、fail 和 complete，并在 complete 中恢复 loading、页面状态等资源。

9. scanStyle 不生效怎么办？

确认调用的是包含当前插件的自定义调试基座或正式打包应用。修改 UTS 原生代码后需要重新制作自定义基座或重新云打包，普通标准基座不会加载插件原生依赖和最新实现。

10. 扫描框显示了但框外条码没有识别？

这是 scanRegion 的预期行为。扫描框不仅是视觉提示，也会作为实时识别过滤区域；如需整屏识别，请不传 scanRegion 或传入 fullScreen: true。

11. resultMode 和 continuous 一起传会怎样？

连续扫码以连续模式为准，不显示单次扫码确认框，每次识别成功都会通过 success 上报；如需单个结果确认，请不要传 continuous: true。

12. fromAlbum 和相机权限有什么关系？

Android 13 及以上优先使用系统 Photo Picker；Android 12 及以下使用系统图片选择器，可能需要读取相册权限。打开即相册时，即使没有相机权限，也可以先完成相册识图；相册无结果且无法继续使用相机时返回 9021009。

13. 为什么识别框位置和相机画面看起来不完全一致？

预览采用 FILL_CENTER，相机画面会按比例填充并裁剪边缘；插件会在识别过滤时补偿裁剪和旋转，但不同设备的相机传感器比例、状态栏和厂商裁剪策略可能存在少量视觉差异。

注意事项

1. 仅 Android App-Plus；发布市场包请走正式打包，勿依赖标准基座调试结果。
2. 首次使用实时相机需要相机权限；插件不会主动跳转系统设置，权限被拒绝后由业务决定是否引导用户开启。
3. 震动权限由插件 Manifest 声明；设置 vibrate: false 可关闭成功震动。
4. 相册选图走系统选择器；Android 12 及以下可能需要读取相册权限，Android 13 及以上优先使用 Photo Picker。
5. scanRegion 只过滤实时相机，且按条码包围盒中心点判断；相册识图始终分析整张图片。
6. 连续扫依赖原生命中队列和 UTS 桥接轮询，业务应在 complete 中收尾，不要只在 success 中恢复状态。
7. 多码点选依赖 ML Kit 返回定位框；多码中只有一个可解码码时会直接返回，无法定位的结果不能作为可点击目标。
8. 智能变焦和双指缩放共享相机变焦能力；不支持变焦的设备会保持原始比例。
9. 大尺寸相册图片会先缩放到最长边约 1920 像素再识别，以降低内存压力。
10. 文档与演示不保证覆盖所有机型相机差异，建议使用真实目标机型回归。

目录结构

mas-code-scan/
├── package.json
├── readme.md
├── changelog.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。

相关链接

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