Files

T

2026-09-03 19:56:19 +08:00

14 KiB

Raw Blame History

mas-code-scan 功能与设置规划

本文用于整理 mas-code-scan 当前已有能力、可继续增加的功能，以及建议的开发优先级。

状态说明：

已实现：当前插件代码已经支持；

建议增加：功能方向已经明确，但尚未实现；

后续评估：需要结合实际业务、设备兼容性和实现成本再决定。

1. 插件当前能力

功能	状态	说明
Android 相机扫码	已实现	基于 CameraX + Google ML Kit
全格式识别	已实现	未传 `formats` 时按全格式识别
指定码制识别	已实现	通过 `formats` 限定二维码、条形码等格式
单次扫码	已实现	成功后自动返回结果
连续扫码	已实现	`continuous: true`，识别后继续停留在扫码页
相册识图	已实现	支持打开后直接进入相册，也支持扫码页内打开相册
多码识别	已实现	同屏多个码时进入点选逻辑
智能变焦	已实现	`smartZoom: true` 时对较小条码自动放大
双指手势缩放	已实现	扫码页内手动调整相机倍率
手电筒	已实现	扫码页右下角手动开关
成功震动	已实现	通过 `vibrate` 控制
自定义有效区域	已实现	通过 `scanRegion` 控制识别区域
二维码正方形区域	已实现	`width` 与 `height` 使用相同值，锁定 1:1
横向条码区域	已实现	默认宽度较大、高度可调
条码框上下位置	已实现	支持上、中、下、自定义位置
条码框高度选择	已实现	原型页支持 24%、32%、40% 三档
全屏识别模式	已实现	`scanRegion: { fullScreen: true }`，整画面识别且不显示扫描框
扫描框直角样式	已实现	当前不绘制圆角

2. 当前 API 概览

2.1 基础调用

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

openCodeScan({
  smartZoom: true,
  vibrate: true,
  success: (res) => {
    console.log(res.content, res.format)
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  },
  complete: () => {
    console.log('扫码结束')
  }
})

2.2 全屏识别

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

全屏模式的行为：

整个相机预览区域均可识别；
不显示扫描框；
不显示扫描框遮罩；
不过滤扫描框外的条码；
不影响 formats、smartZoom、vibrate、continuous 等其他设置。

2.3 二维码正方形区域

openCodeScan({
  formats: ['QR_CODE'],
  scanRegion: {
    width: 0.74,
    height: 0.74,
    centerX: 0.5,
    centerY: 0.5
  }
})

二维码区域要求：

width 和 height 使用相同值；
严格保持 1:1 正方形比例；
扫描框使用直角，不使用圆角。

2.4 横向条码区域

openCodeScan({
  formats: ['CODE_128', 'EAN_13'],
  scanRegion: {
    width: 0.96,
    height: 0.24,
    centerX: 0.5,
    centerY: 0.5
  }
})

其中：

width 控制横向宽度；
height 控制扫描框内高度；
centerY 控制扫描框上下位置；
目前原型页提供 24%、32%、40% 三档高度；
框内条码才会进入有效识别结果。

3. 建议优先增加的功能

以下功能对仓库、设备管理、物料盘点等场景最有价值。

3.1 手电筒 API 控制

当前已经有扫码页手电筒按钮，建议继续增加调用参数，用于控制打开扫码页时的默认状态。

建议接口：

torch?: 'auto' | 'on' | 'off'

建议行为：

值	行为
`auto`	使用系统或插件默认状态，不强制打开
`on`	打开扫码页后自动开启手电筒
`off`	打开扫码页后保持关闭

适用场景：弱光仓库、货架底部、设备背面标签、夜间扫码。

3.2 连续扫码去重策略

连续扫码时建议开放更明确的去重配置。

建议接口：

openCodeScan({
  continuous: true,
  duplicatePolicy: 'cooldown',
  duplicateCooldown: 1500
})

建议支持：

策略	行为
`allow`	同一个码可以重复回调
`ignore`	同一次扫码会话中，相同内容只回调一次
`cooldown`	相同内容在指定时间内不重复回调

建议参数：

duplicatePolicy：去重策略；
duplicateCooldown：去重时间，单位毫秒；
maxResults：连续扫码最多保存的结果数量。

这是批量盘点场景中最值得增加的功能之一。

3.3 多码识别策略

当前同屏多个条码时可以进入点选。建议增加自动选择策略，减少用户额外操作。

建议接口：

openCodeScan({
  multiCodeMode: 'nearestCenter'
})

建议取值：

值	行为
`select`	保持当前交互，暂停画面并由用户点选
`first`	取 ML Kit 返回的第一个有效条码
`nearestCenter`	选择距离扫描框中心最近的条码
`largest`	选择画面中面积最大的条码
`all`	一次返回全部有效条码

建议默认使用 nearestCenter，更符合扫描框交互习惯。

3.4 扫码结果确认模式

目前单次扫码识别成功后会自动返回。建议增加确认模式，避免误扫。

建议接口：

openCodeScan({
  resultMode: 'confirm'
})

建议取值：

值	行为
`immediate`	识别成功后立即返回，保持当前行为
`confirm`	显示结果，用户确认后返回
`pause`	识别成功后暂停相机，用户可确认或继续扫描

适用场景：设备绑定、物料入库、资产登记等不能容忍误扫的业务。

3.5 前后摄像头切换

建议支持默认摄像头和扫码页内切换。

建议接口：

openCodeScan({
  camera: 'back'
})

建议取值：

back：后置摄像头，默认；
front：前置摄像头；
auto：由插件选择可用摄像头。

扫码页可以增加一个左下角或右上角切换按钮。

4. 识别准确率和性能设置

4.1 稳定识别帧数

要求同一个条码连续出现在若干帧后才判定成功。

openCodeScan({
  stableFrames: 2
})

优点：

减少模糊画面误触发；
减少条码刚进入画面时的误扫；
对连续扫码更稳定。

注意：数值过高会增加识别延迟，建议默认 1 或 2。

4.2 智能变焦参数

当前只有开关，后续可以细化为：

openCodeScan({
  smartZoom: true,
  smartZoomMaxRatio: 2.5,
  smartZoomTriggerSize: 0.12
})

建议参数：

smartZoomMaxRatio：最大自动变焦倍率；
smartZoomTriggerSize：条码小于指定比例时触发；
smartZoomResetAfterSuccess：识别成功后是否恢复倍率。

4.3 最小条码尺寸过滤

用于忽略过远或过小的无关条码。

openCodeScan({
  minBarcodeWidth: 0.08,
  minBarcodeHeight: 0.03
})

注意：该功能和 scanRegion 不同：

scanRegion 解决“条码是否在有效区域内”；
最小尺寸过滤解决“条码是否足够大、是否值得识别”。

5. 扫描框和交互设置

5.1 扫描框视觉样式

目前扫描框已经支持尺寸、位置和直角样式。增加独立的视觉配置：

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'
  }
})

建议支持：

showMask：是否显示框外遮罩；
showBeam：是否显示扫描线；
borderColor：边框颜色；
maskColor：遮罩颜色和透明度；
beamColor：扫描线颜色；
beamDuration：扫描线移动周期；
cornerStyle：完整边框或四角边框。

建议将这些属性放在 scanStyle 中，不要和识别区域参数混在一起。

5.2 扫码页提示文案

不同业务可以使用不同的引导语。

建议接口：

openCodeScan({
  title: '设备绑定',
  hint: '请将设备条码放入扫描框内'
})

建议支持：

title：页面标题；
hint：扫描框下方提示；
successHint：识别成功提示；
emptyHint：暂未识别到条码时的提示。

5.3 暂停与继续扫描

连续扫码可以增加暂停和继续按钮。

建议行为：

点击暂停后停止分析帧；
相机预览可以继续显示，也可以冻结画面；
点击继续后恢复分析；
连续扫码结果列表不清空。
实时帧中只有一条已解码条码时必须直接上报；ML Kit 额外返回的无内容候选框不能触发多码点选或跳过该单码。

建议接口：

openCodeScan({
  continuous: true,
  showPauseButton: true
})

6. 扫码结果增强

6.1 返回条码位置

当前结果主要返回内容和码制。后续可以返回条码在图像中的位置。

建议结果：

{
  content: 'EQ-12345678',
  format: 'CODE_128',
  fromAlbum: false,
  bounds: {
    left: 120,
    top: 360,
    width: 480,
    height: 96
  }
}

用途：

调试扫描框映射；
保存条码位置；
多码场景二次判断；
识别结果可视化。

6.2 结果校验

建议在插件外层或调用参数中增加结果校验能力。

openCodeScan({
  formats: ['CODE_128'],
  validator: {
    pattern: '^EQ-[A-Z0-9]{8}$',
    message: '请扫描有效设备编码'
  }
})

建议支持：

正则表达式；
固定前缀；
固定长度；
自定义校验回调；
校验失败后继续扫描，不关闭扫码页。

建议优先在业务层实现，避免把业务规则过度耦合到通用插件。

6.3 扫码状态回调

用于业务页面展示状态或进行调试。

建议接口：

openCodeScan({
  onStatus: (status) => {
    console.log(status)
  }
})

建议状态：

opening：正在打开扫码页；
cameraReady：相机已准备完成；
scanning：正在识别；
paused：已暂停；
result：识别到结果；
closed：扫码页关闭。

7. 相册识图增强

7.1 多图批量识别

openCodeScan({
  fromAlbum: true,
  albumMultiple: true,
  maxAlbumImages: 9
})

适用场景：

批量导入物料标签照片；
历史图片盘点；
一次处理多个设备照片。

7.2 图片裁剪后识别

相册选择图片后增加裁剪步骤：

用户手动裁剪识别区域；
使用当前扫描框比例作为裁剪建议；
裁剪后再交给 ML Kit 识别。

复杂照片中存在多个标签时，该功能可以明显提高识别准确率。

8. 调试和错误处理

8.1 调试模式

建议增加：

openCodeScan({
  debug: true
})

调试信息可包括：

预览 View 尺寸；
实际扫描框像素坐标；
输入图像尺寸；
图像旋转角度；
cropRect；
区域过滤前后的条码数量；
智能变焦触发记录；
每帧识别耗时。

正式环境默认关闭，避免性能损耗和敏感信息泄露。

8.2 更细的错误码

状态：已实现。 现有 9021001 ~ 9021004 的含义保持不变，新增错误码从 9021005 开始：

错误码	场景	处理方式
`9021005`	相机被其他应用占用或当前不可用	关闭其他相机应用后重试
`9021006`	设备没有闪光灯	仅在扫码页提示，不中断扫码会话
`9021007`	相机初始化失败	检查设备相机状态，必要时重启应用
`9021008`	相册图片无法读取	重新选择本地图片
`9021009`	图片中没有有效条码	仅打开即相册且无可用相机回退时结束会话
`9021010`	指定码制不支持	`formats` 非空且全部不受支持时返回
`9021011`	扫描超时	单次扫码传入 `scanTimeout: 1000 ~ 600000` 后启用；连续扫码不启用

错误码增加遵循兼容原则：不修改已有错误码的含义；致命错误走 fail 后 complete；无闪光灯不会影响相机扫码，因此只提示，不触发 fail。

9. 横屏和平板支持

当前 Android 扫码页固定竖屏。后续可以评估：

openCodeScan({
  orientation: 'portrait'
})

建议取值：

portrait：竖屏，当前默认行为；
landscape：横屏；
auto：跟随设备方向。

适用设备：

平板；
工业手持终端；
横向固定安装设备；
长条码集中扫描场景。

10. 推荐开发优先级

第一阶段：直接提升日常可用性

手电筒默认状态 API；
连续扫码去重策略；
多码自动选择策略；
扫码结果确认模式；
前后摄像头切换。

第二阶段：提升业务适配能力

扫码页提示文案；
扫描状态回调；
稳定识别帧数；
扫描框视觉样式配置；
结果位置 bounds 返回。

第三阶段：扩展复杂业务场景

相册多图批量识别；
图片裁剪后识别；
横屏和平板支持；
扫码结果校验器；
调试模式和性能指标。

11. 开发注意事项

新增功能应优先保持 openCodeScan(options) 的兼容性，不要破坏现有调用。
识别区域参数和视觉样式参数应分开设计。
全屏模式必须保持“整画面识别、不绘制扫描框、不进行区域过滤”的语义。
二维码区域必须继续保持 1:1，不能因为屏幕比例或边界收敛发生变形。
连续扫码新增去重策略时，不能削弱当前已有的基本去重行为。
相册识图和实时相机识别应保持清晰区分，相册识图默认不受实时扫描框限制。
新增 Android 原生能力后，应同步更新 UTS 类型定义、插件 README 和演示页。
每次修改原生相机、图像坐标映射或区域过滤逻辑后，都需要使用 Android 真机或自定义调试基座验证。
新增错误码时只能追加，不能改变已有错误码的含义。
涉及权限、相机、闪光灯和设备方向的功能，需要至少验证主流 Android 设备和不同屏幕尺寸。

14 KiB Raw Blame History Unescape Escape

mas-code-scan 功能与设置规划

1. 插件当前能力

2. 当前 API 概览

2.1 基础调用

2.2 全屏识别

2.3 二维码正方形区域

2.4 横向条码区域

3. 建议优先增加的功能

3.1 手电筒 API 控制

3.2 连续扫码去重策略

3.3 多码识别策略

3.4 扫码结果确认模式

3.5 前后摄像头切换

4. 识别准确率和性能设置

4.1 稳定识别帧数

4.2 智能变焦参数

4.3 最小条码尺寸过滤

5. 扫描框和交互设置

5.1 扫描框视觉样式

5.2 扫码页提示文案

5.3 暂停与继续扫描

6. 扫码结果增强

6.1 返回条码位置

6.2 结果校验

6.3 扫码状态回调

7. 相册识图增强

7.1 多图批量识别

7.2 图片裁剪后识别

8. 调试和错误处理

8.1 调试模式

8.2 更细的错误码

9. 横屏和平板支持

10. 推荐开发优先级

第一阶段：直接提升日常可用性

第二阶段：提升业务适配能力

第三阶段：扩展复杂业务场景

11. 开发注意事项

14 KiB

Raw Blame History