618 lines
14 KiB
Markdown
618 lines
14 KiB
Markdown
# 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 基础调用
|
||
|
||
```ts
|
||
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 全屏识别
|
||
|
||
```ts
|
||
openCodeScan({
|
||
scanRegion: {
|
||
fullScreen: true
|
||
},
|
||
success: (res) => {
|
||
console.log(res.content)
|
||
}
|
||
})
|
||
```
|
||
|
||
全屏模式的行为：
|
||
|
||
- 整个相机预览区域均可识别；
|
||
- 不显示扫描框；
|
||
- 不显示扫描框遮罩；
|
||
- 不过滤扫描框外的条码；
|
||
- 不影响 `formats`、`smartZoom`、`vibrate`、`continuous` 等其他设置。
|
||
|
||
### 2.3 二维码正方形区域
|
||
|
||
```ts
|
||
openCodeScan({
|
||
formats: ['QR_CODE'],
|
||
scanRegion: {
|
||
width: 0.74,
|
||
height: 0.74,
|
||
centerX: 0.5,
|
||
centerY: 0.5
|
||
}
|
||
})
|
||
```
|
||
|
||
二维码区域要求：
|
||
|
||
- `width` 和 `height` 使用相同值；
|
||
- 严格保持 1:1 正方形比例；
|
||
- 扫描框使用直角，不使用圆角。
|
||
|
||
### 2.4 横向条码区域
|
||
|
||
```ts
|
||
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 控制
|
||
|
||
当前已经有扫码页手电筒按钮，建议继续增加调用参数，用于控制打开扫码页时的默认状态。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
torch?: 'auto' | 'on' | 'off'
|
||
```
|
||
|
||
建议行为：
|
||
|
||
| 值 | 行为 |
|
||
|---|---|
|
||
| `auto` | 使用系统或插件默认状态，不强制打开 |
|
||
| `on` | 打开扫码页后自动开启手电筒 |
|
||
| `off` | 打开扫码页后保持关闭 |
|
||
|
||
适用场景：弱光仓库、货架底部、设备背面标签、夜间扫码。
|
||
|
||
---
|
||
|
||
### 3.2 连续扫码去重策略
|
||
|
||
连续扫码时建议开放更明确的去重配置。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
continuous: true,
|
||
duplicatePolicy: 'cooldown',
|
||
duplicateCooldown: 1500
|
||
})
|
||
```
|
||
|
||
建议支持：
|
||
|
||
| 策略 | 行为 |
|
||
|---|---|
|
||
| `allow` | 同一个码可以重复回调 |
|
||
| `ignore` | 同一次扫码会话中，相同内容只回调一次 |
|
||
| `cooldown` | 相同内容在指定时间内不重复回调 |
|
||
|
||
建议参数：
|
||
|
||
- `duplicatePolicy`：去重策略；
|
||
- `duplicateCooldown`：去重时间，单位毫秒；
|
||
- `maxResults`：连续扫码最多保存的结果数量。
|
||
|
||
这是批量盘点场景中最值得增加的功能之一。
|
||
|
||
---
|
||
|
||
### 3.3 多码识别策略
|
||
|
||
当前同屏多个条码时可以进入点选。建议增加自动选择策略，减少用户额外操作。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
multiCodeMode: 'nearestCenter'
|
||
})
|
||
```
|
||
|
||
建议取值：
|
||
|
||
| 值 | 行为 |
|
||
|---|---|
|
||
| `select` | 保持当前交互，暂停画面并由用户点选 |
|
||
| `first` | 取 ML Kit 返回的第一个有效条码 |
|
||
| `nearestCenter` | 选择距离扫描框中心最近的条码 |
|
||
| `largest` | 选择画面中面积最大的条码 |
|
||
| `all` | 一次返回全部有效条码 |
|
||
|
||
建议默认使用 `nearestCenter`，更符合扫描框交互习惯。
|
||
|
||
---
|
||
|
||
### 3.4 扫码结果确认模式
|
||
|
||
目前单次扫码识别成功后会自动返回。建议增加确认模式，避免误扫。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
resultMode: 'confirm'
|
||
})
|
||
```
|
||
|
||
建议取值：
|
||
|
||
| 值 | 行为 |
|
||
|---|---|
|
||
| `immediate` | 识别成功后立即返回，保持当前行为 |
|
||
| `confirm` | 显示结果，用户确认后返回 |
|
||
| `pause` | 识别成功后暂停相机，用户可确认或继续扫描 |
|
||
|
||
适用场景：设备绑定、物料入库、资产登记等不能容忍误扫的业务。
|
||
|
||
---
|
||
|
||
### 3.5 前后摄像头切换
|
||
|
||
建议支持默认摄像头和扫码页内切换。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
camera: 'back'
|
||
})
|
||
```
|
||
|
||
建议取值：
|
||
|
||
- `back`：后置摄像头，默认；
|
||
- `front`：前置摄像头；
|
||
- `auto`：由插件选择可用摄像头。
|
||
|
||
扫码页可以增加一个左下角或右上角切换按钮。
|
||
|
||
---
|
||
|
||
## 4. 识别准确率和性能设置
|
||
|
||
### 4.1 稳定识别帧数
|
||
|
||
要求同一个条码连续出现在若干帧后才判定成功。
|
||
|
||
```ts
|
||
openCodeScan({
|
||
stableFrames: 2
|
||
})
|
||
```
|
||
|
||
优点：
|
||
|
||
- 减少模糊画面误触发；
|
||
- 减少条码刚进入画面时的误扫；
|
||
- 对连续扫码更稳定。
|
||
|
||
注意：数值过高会增加识别延迟，建议默认 1 或 2。
|
||
|
||
---
|
||
|
||
### 4.2 智能变焦参数
|
||
|
||
当前只有开关，后续可以细化为：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
smartZoom: true,
|
||
smartZoomMaxRatio: 2.5,
|
||
smartZoomTriggerSize: 0.12
|
||
})
|
||
```
|
||
|
||
建议参数：
|
||
|
||
- `smartZoomMaxRatio`：最大自动变焦倍率；
|
||
- `smartZoomTriggerSize`：条码小于指定比例时触发；
|
||
- `smartZoomResetAfterSuccess`：识别成功后是否恢复倍率。
|
||
|
||
---
|
||
|
||
### 4.3 最小条码尺寸过滤
|
||
|
||
用于忽略过远或过小的无关条码。
|
||
|
||
```ts
|
||
openCodeScan({
|
||
minBarcodeWidth: 0.08,
|
||
minBarcodeHeight: 0.03
|
||
})
|
||
```
|
||
|
||
注意：该功能和 `scanRegion` 不同：
|
||
|
||
- `scanRegion` 解决“条码是否在有效区域内”；
|
||
- 最小尺寸过滤解决“条码是否足够大、是否值得识别”。
|
||
|
||
---
|
||
|
||
## 5. 扫描框和交互设置
|
||
|
||
### 5.1 扫描框视觉样式
|
||
|
||
目前扫描框已经支持尺寸、位置和直角样式。增加独立的视觉配置：
|
||
|
||
```ts
|
||
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 扫码页提示文案
|
||
|
||
不同业务可以使用不同的引导语。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
title: '设备绑定',
|
||
hint: '请将设备条码放入扫描框内'
|
||
})
|
||
```
|
||
|
||
建议支持：
|
||
|
||
- `title`：页面标题；
|
||
- `hint`：扫描框下方提示；
|
||
- `successHint`：识别成功提示；
|
||
- `emptyHint`：暂未识别到条码时的提示。
|
||
|
||
---
|
||
|
||
### 5.3 暂停与继续扫描
|
||
|
||
连续扫码可以增加暂停和继续按钮。
|
||
|
||
建议行为：
|
||
|
||
- 点击暂停后停止分析帧；
|
||
- 相机预览可以继续显示，也可以冻结画面；
|
||
- 点击继续后恢复分析；
|
||
- 连续扫码结果列表不清空。
|
||
- 实时帧中只有一条已解码条码时必须直接上报；ML Kit 额外返回的无内容候选框不能触发多码点选或跳过该单码。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
continuous: true,
|
||
showPauseButton: true
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 扫码结果增强
|
||
|
||
### 6.1 返回条码位置
|
||
|
||
当前结果主要返回内容和码制。后续可以返回条码在图像中的位置。
|
||
|
||
建议结果：
|
||
|
||
```ts
|
||
{
|
||
content: 'EQ-12345678',
|
||
format: 'CODE_128',
|
||
fromAlbum: false,
|
||
bounds: {
|
||
left: 120,
|
||
top: 360,
|
||
width: 480,
|
||
height: 96
|
||
}
|
||
}
|
||
```
|
||
|
||
用途：
|
||
|
||
- 调试扫描框映射；
|
||
- 保存条码位置；
|
||
- 多码场景二次判断；
|
||
- 识别结果可视化。
|
||
|
||
---
|
||
|
||
### 6.2 结果校验
|
||
|
||
建议在插件外层或调用参数中增加结果校验能力。
|
||
|
||
```ts
|
||
openCodeScan({
|
||
formats: ['CODE_128'],
|
||
validator: {
|
||
pattern: '^EQ-[A-Z0-9]{8}$',
|
||
message: '请扫描有效设备编码'
|
||
}
|
||
})
|
||
```
|
||
|
||
建议支持：
|
||
|
||
- 正则表达式；
|
||
- 固定前缀；
|
||
- 固定长度；
|
||
- 自定义校验回调；
|
||
- 校验失败后继续扫描，不关闭扫码页。
|
||
|
||
建议优先在业务层实现，避免把业务规则过度耦合到通用插件。
|
||
|
||
---
|
||
|
||
### 6.3 扫码状态回调
|
||
|
||
用于业务页面展示状态或进行调试。
|
||
|
||
建议接口：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
onStatus: (status) => {
|
||
console.log(status)
|
||
}
|
||
})
|
||
```
|
||
|
||
建议状态：
|
||
|
||
- `opening`：正在打开扫码页；
|
||
- `cameraReady`：相机已准备完成；
|
||
- `scanning`：正在识别；
|
||
- `paused`：已暂停；
|
||
- `result`：识别到结果；
|
||
- `closed`：扫码页关闭。
|
||
|
||
---
|
||
|
||
## 7. 相册识图增强
|
||
|
||
### 7.1 多图批量识别
|
||
|
||
```ts
|
||
openCodeScan({
|
||
fromAlbum: true,
|
||
albumMultiple: true,
|
||
maxAlbumImages: 9
|
||
})
|
||
```
|
||
|
||
适用场景：
|
||
|
||
- 批量导入物料标签照片；
|
||
- 历史图片盘点；
|
||
- 一次处理多个设备照片。
|
||
|
||
### 7.2 图片裁剪后识别
|
||
|
||
相册选择图片后增加裁剪步骤：
|
||
|
||
- 用户手动裁剪识别区域；
|
||
- 使用当前扫描框比例作为裁剪建议；
|
||
- 裁剪后再交给 ML Kit 识别。
|
||
|
||
复杂照片中存在多个标签时，该功能可以明显提高识别准确率。
|
||
|
||
---
|
||
|
||
## 8. 调试和错误处理
|
||
|
||
### 8.1 调试模式
|
||
|
||
建议增加：
|
||
|
||
```ts
|
||
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 扫码页固定竖屏。后续可以评估：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
orientation: 'portrait'
|
||
})
|
||
```
|
||
|
||
建议取值：
|
||
|
||
- `portrait`：竖屏，当前默认行为；
|
||
- `landscape`：横屏；
|
||
- `auto`：跟随设备方向。
|
||
|
||
适用设备：
|
||
|
||
- 平板；
|
||
- 工业手持终端；
|
||
- 横向固定安装设备；
|
||
- 长条码集中扫描场景。
|
||
|
||
---
|
||
|
||
## 10. 推荐开发优先级
|
||
|
||
### 第一阶段：直接提升日常可用性
|
||
|
||
1. 手电筒默认状态 API；
|
||
2. 连续扫码去重策略；
|
||
3. 多码自动选择策略；
|
||
4. 扫码结果确认模式；
|
||
5. 前后摄像头切换。
|
||
|
||
### 第二阶段：提升业务适配能力
|
||
|
||
1. 扫码页提示文案；
|
||
2. 扫描状态回调；
|
||
3. 稳定识别帧数；
|
||
4. 扫描框视觉样式配置；
|
||
5. 结果位置 `bounds` 返回。
|
||
|
||
### 第三阶段：扩展复杂业务场景
|
||
|
||
1. 相册多图批量识别；
|
||
2. 图片裁剪后识别；
|
||
3. 横屏和平板支持；
|
||
4. 扫码结果校验器；
|
||
5. 调试模式和性能指标。
|
||
|
||
---
|
||
|
||
## 11. 开发注意事项
|
||
|
||
1. 新增功能应优先保持 `openCodeScan(options)` 的兼容性，不要破坏现有调用。
|
||
2. 识别区域参数和视觉样式参数应分开设计。
|
||
3. 全屏模式必须保持“整画面识别、不绘制扫描框、不进行区域过滤”的语义。
|
||
4. 二维码区域必须继续保持 1:1，不能因为屏幕比例或边界收敛发生变形。
|
||
5. 连续扫码新增去重策略时，不能削弱当前已有的基本去重行为。
|
||
6. 相册识图和实时相机识别应保持清晰区分，相册识图默认不受实时扫描框限制。
|
||
7. 新增 Android 原生能力后，应同步更新 UTS 类型定义、插件 README 和演示页。
|
||
8. 每次修改原生相机、图像坐标映射或区域过滤逻辑后，都需要使用 Android 真机或自定义调试基座验证。
|
||
9. 新增错误码时只能追加，不能改变已有错误码的含义。
|
||
10. 涉及权限、相机、闪光灯和设备方向的功能，需要至少验证主流 Android 设备和不同屏幕尺寸。
|