499 lines
13 KiB
Markdown
499 lines
13 KiB
Markdown
# mas-code-scan 自定义识别区域方案
|
||
|
||
## 1. 目标
|
||
|
||
在 Android 扫码页面中提供可配置的实时识别区域（ROI，Region of Interest）：
|
||
|
||
- 摄像头打开后显示一个矩形扫描框；
|
||
- 只有条码位于矩形区域内时才允许识别成功；
|
||
- 扫描框外的条码不触发单次扫码成功；
|
||
- 支持自定义扫描框宽度、高度、水平位置和垂直位置；
|
||
- 支持不同屏幕尺寸和横竖屏适配；
|
||
- 不破坏现有的单次扫码、连续扫码、相册识图、多码点选、智能变焦和码制过滤能力。
|
||
|
||
## 2. 当前实现核对
|
||
|
||
### 2.1 现有接口
|
||
|
||
文件：`uni_modules/mas-code-scan/utssdk/interface.uts`
|
||
|
||
当前 `CodeScanOptions` 支持：
|
||
|
||
```ts
|
||
{
|
||
smartZoom?: boolean
|
||
formats?: string[]
|
||
vibrate?: boolean
|
||
continuous?: boolean
|
||
fromAlbum?: boolean
|
||
success?: (res) => void
|
||
fail?: (res) => void
|
||
complete?: (res) => void
|
||
}
|
||
```
|
||
|
||
当前没有识别区域配置字段。
|
||
|
||
### 2.2 预览层
|
||
|
||
文件：`uni_modules/mas-code-scan/utssdk/app-android/CodeCaptureActivity.kt`
|
||
|
||
- 使用 `PreviewView.ScaleType.FILL_CENTER` 显示相机预览；
|
||
- `ScanFrameDecorView` 覆盖在预览层上方绘制扫描动画；
|
||
- 预览层和装饰层都是全屏 `FrameLayout`；
|
||
- 触摸缩放绑定在 `PreviewView` 上。
|
||
|
||
文件：`uni_modules/mas-code-scan/utssdk/app-android/ScanFrameDecorView.kt`
|
||
|
||
当前扫描框是固定的正方形：
|
||
|
||
```kotlin
|
||
val frameWidth = ...
|
||
val frameHeight = frameWidth
|
||
```
|
||
|
||
它只负责画扫描线，不参与实际识别。
|
||
|
||
### 2.3 识别层
|
||
|
||
文件：`uni_modules/mas-code-scan/utssdk/app-android/CodeCaptureActivity.kt`
|
||
|
||
当前把完整的 `ImageProxy` 图像交给 ML Kit：
|
||
|
||
```kotlin
|
||
val inputImage = InputImage.fromMediaImage(mediaImage, rotationDegrees)
|
||
scanner.process(inputImage)
|
||
```
|
||
|
||
因此当前扫描框只是视觉提示，框外条码仍可能被识别。
|
||
|
||
## 3. 推荐接口设计
|
||
|
||
建议新增 `scanRegion`，使用相对比例配置，不使用固定像素作为公共接口。
|
||
|
||
```ts
|
||
openCodeScan({
|
||
scanRegion: {
|
||
width: 0.92,
|
||
height: 0.18,
|
||
centerX: 0.5,
|
||
centerY: 0.5
|
||
}
|
||
})
|
||
```
|
||
|
||
字段定义：
|
||
|
||
| 字段 | 类型 | 默认值 | 范围 | 含义 |
|
||
|---|---|---:|---|---|
|
||
| `fullScreen` | `boolean` | `false` | - | 为 `true` 时整画面识别，不绘制扫描框且不进行区域过滤 |
|
||
| `width` | `number` | `0.74` | `0.1 ~ 1` | 扫描框宽度，占预览宽度的比例 |
|
||
| `height` | `number` | `0.74` | `0.1 ~ 1` | 扫描框高度，占预览宽度的比例 |
|
||
| `centerX` | `number` | `0.5` | `0 ~ 1` | 扫描框中心的水平位置比例 |
|
||
| `centerY` | `number` | `0.5` | `0 ~ 1` | 扫描框中心的垂直位置比例 |
|
||
|
||
全屏识别示例：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
scanRegion: { fullScreen: true }
|
||
})
|
||
```
|
||
|
||
二维码区域约束：
|
||
|
||
- `width` 与 `height` 使用相同值，严格锁定 `1:1` 正方形比例；
|
||
- 默认值为 `width: 0.74`、`height: 0.74`；
|
||
- 原生扫描框使用直角，不绘制圆角。
|
||
|
||
推荐默认值：
|
||
|
||
```ts
|
||
{
|
||
width: 0.74,
|
||
height: 0.74,
|
||
centerX: 0.5,
|
||
centerY: 0.5
|
||
}
|
||
```
|
||
|
||
业务页面可针对一维码使用横向区域，并通过 `centerY` 调整上下位置、通过 `height` 调整框高：
|
||
|
||
```ts
|
||
{
|
||
width: 0.96,
|
||
height: 0.24,
|
||
centerX: 0.5,
|
||
centerY: 0.5
|
||
}
|
||
```
|
||
|
||
原型页提供三档横向条码框高度：
|
||
|
||
- 中：`0.24`（24%）；
|
||
- 大：`0.32`（32%）；
|
||
- 特大：`0.40`（40%）。
|
||
|
||
### 3.1 为什么使用比例
|
||
|
||
- 不依赖具体手机分辨率和 density；
|
||
- 适配不同 Android 设备；
|
||
- 与当前全屏预览布局一致；
|
||
- 后续可在页面中通过滑块或预设配置调整；
|
||
- 避免将前端 `rpx` 直接与原生像素混用。
|
||
|
||
## 4. 实现分层
|
||
|
||
### 4.1 UTS 接口层
|
||
|
||
修改：`utssdk/interface.uts`
|
||
|
||
新增：
|
||
|
||
```ts
|
||
export type ScanRegion = {
|
||
width?: number
|
||
height?: number
|
||
centerX?: number
|
||
centerY?: number
|
||
}
|
||
```
|
||
|
||
并在 `CodeScanOptions` 中增加：
|
||
|
||
```ts
|
||
scanRegion?: ScanRegion
|
||
```
|
||
|
||
要求：
|
||
|
||
- 字段全部可选；
|
||
- 不传时保持现有默认扫描框；
|
||
- 对非法值进行原生端裁剪和兜底；
|
||
- 不把 UI 颜色、文案等表现层参数与识别区域参数混在一起。
|
||
|
||
### 4.2 UTS 到 Android Intent
|
||
|
||
修改：`utssdk/app-android/index.uts`
|
||
|
||
新增一个 JSON 字符串 Extra，例如：
|
||
|
||
```text
|
||
mas_scan_region
|
||
```
|
||
|
||
将 `scanRegion` 序列化后传递给 `CodeCaptureActivity`。
|
||
|
||
推荐传递 JSON，而不是增加多个 Intent Extra，原因是：
|
||
|
||
- 字段集中；
|
||
- 后续增加圆角、边框颜色等非识别参数时更容易扩展；
|
||
- 保持接口和 Activity 参数数量可控。
|
||
|
||
### 4.3 Activity 参数解析
|
||
|
||
修改：`CodeCaptureActivity.kt`
|
||
|
||
新增：
|
||
|
||
```kotlin
|
||
private data class ScanRegionConfig(
|
||
val width: Float,
|
||
val height: Float,
|
||
val centerX: Float,
|
||
val centerY: Float
|
||
)
|
||
```
|
||
|
||
初始化时：
|
||
|
||
1. 读取 Intent Extra；
|
||
2. 解析 JSON；
|
||
3. 将数值限制在安全范围；
|
||
4. 对过小区域、越界中心点进行兜底；
|
||
5. 将同一份配置传给 `ScanFrameDecorView` 和识别过滤逻辑。
|
||
|
||
最终必须保证：
|
||
|
||
```text
|
||
视觉扫描框区域 == 实际有效识别区域
|
||
```
|
||
|
||
## 5. 坐标体系设计
|
||
|
||
这是本需求的核心难点。项目中至少存在三套坐标：
|
||
|
||
1. **屏幕/装饰层坐标**：`ScanFrameDecorView` 的 view 坐标；
|
||
2. **预览可视区域坐标**：`PreviewView` 中用户看到的相机画面；
|
||
3. **ImageProxy 图像坐标**：ML Kit `Barcode.boundingBox` 使用的图像坐标。
|
||
|
||
由于预览使用 `FILL_CENTER`，图像可能在屏幕两侧或上下被裁剪，不能简单按照屏幕宽高直接换算。
|
||
|
||
### 5.1 统一区域定义
|
||
|
||
推荐先在预览层坐标中计算扫描框：
|
||
|
||
```text
|
||
frameLeft = viewWidth * (centerX - width / 2)
|
||
frameTop = viewHeight * (centerY - height / 2)
|
||
frameRight = viewWidth * (centerX + width / 2)
|
||
frameBottom = viewHeight * (centerY + height / 2)
|
||
```
|
||
|
||
并限制在预览层范围内。
|
||
|
||
### 5.2 预览坐标映射到图像坐标
|
||
|
||
当前 `PreviewView` 使用 `FILL_CENTER`，映射应考虑：
|
||
|
||
```text
|
||
scale = max(viewWidth / rotatedImageWidth, viewHeight / rotatedImageHeight)
|
||
```
|
||
|
||
相机图像在屏幕上的实际显示尺寸为：
|
||
|
||
```text
|
||
displayWidth = rotatedImageWidth * scale
|
||
displayHeight = rotatedImageHeight * scale
|
||
offsetX = (viewWidth - displayWidth) / 2
|
||
offsetY = (viewHeight - displayHeight) / 2
|
||
```
|
||
|
||
扫描框转回旋转后的图像坐标：
|
||
|
||
```text
|
||
imageLeft = (frameLeft - offsetX) / scale
|
||
imageTop = (frameTop - offsetY) / scale
|
||
imageRight = (frameRight - offsetX) / scale
|
||
imageBottom = (frameBottom - offsetY) / scale
|
||
```
|
||
|
||
然后再根据 `rotationDegrees` 转换到 `ImageProxy` 原始坐标。
|
||
|
||
注意：实际代码需要以 `PreviewView` 的 `viewPort`、绑定的 UseCase 分辨率和设备方向为准验证，不能只凭静态公式上线。
|
||
|
||
## 6. 识别限制策略
|
||
|
||
### 6.1 第一阶段：结果过滤，推荐先实现
|
||
|
||
ML Kit 仍分析整帧，但只接受扫描区域内的条码：
|
||
|
||
```kotlin
|
||
val validBarcodes = barcodes.filter { barcode ->
|
||
val box = barcode.boundingBox ?: return@filter false
|
||
isBarcodeInsideScanRegion(box, imageProxy, rotationDegrees)
|
||
}
|
||
```
|
||
|
||
区域判断建议使用条码边界框中心点，默认规则：
|
||
|
||
```text
|
||
条码中心点位于扫描框内 => 允许识别
|
||
条码中心点位于扫描框外 => 忽略
|
||
```
|
||
|
||
对于严格业务场景，可以改为：
|
||
|
||
```text
|
||
条码边界框完全位于扫描框内 => 允许识别
|
||
```
|
||
|
||
本项目建议默认使用“中心点在区域内”，原因是：
|
||
|
||
- 用户将条码移入框内时体验更自然；
|
||
- 条码边缘轻微超出时不会频繁丢失；
|
||
- 对一维横向条码更友好。
|
||
|
||
### 6.2 多码识别
|
||
|
||
过滤应发生在多码判断之前：
|
||
|
||
```text
|
||
原始 barcodes
|
||
-> 过滤无 boundingBox 的结果
|
||
-> 过滤框外结果
|
||
-> 再执行单码 / 多码判断
|
||
```
|
||
|
||
这样框外多码不会触发点选页面，也不会影响智能变焦。
|
||
|
||
### 6.3 相册识图
|
||
|
||
实时摄像头的 `scanRegion` 不应默认限制相册识图：
|
||
|
||
- 相册图片没有实时预览框坐标；
|
||
- 用户选择的是整张图片；
|
||
- 继续保持相册识别整图的现有行为。
|
||
|
||
如果未来确实需要对相册图片裁剪，应单独设计 `albumRegion`，不要复用实时预览坐标。
|
||
|
||
### 6.4 识别前裁剪
|
||
|
||
第二阶段可选做真正的 ROI 图像裁剪，只将区域图像提交给 ML Kit。
|
||
|
||
暂不作为第一阶段实现，原因：
|
||
|
||
- 需要处理 ImageProxy YUV 裁剪；
|
||
- 需要处理旋转和 cropRect；
|
||
- 需要重新映射多码点选坐标；
|
||
- 可能影响智能变焦依据和现有连续扫码稳定性；
|
||
- 设备兼容性验证成本更高。
|
||
|
||
## 7. 扫描框视觉设计
|
||
|
||
修改：`ScanFrameDecorView.kt`
|
||
|
||
扫描框应从固定正方形改为配置矩形：
|
||
|
||
- 宽度由 `width` 决定；
|
||
- 高度由 `height` 决定；
|
||
- 位置由 `centerX`、`centerY` 决定；
|
||
- 扫描线只在矩形内部移动；
|
||
- 扫描线左右留出固定 inset；
|
||
- 其他区域可增加半透明遮罩，增强用户对有效范围的理解。
|
||
|
||
建议提供清晰的 UI 语义：
|
||
|
||
```text
|
||
框内：有效识别区域
|
||
框外：不识别
|
||
```
|
||
|
||
当前截图的横向条码场景推荐：
|
||
|
||
```ts
|
||
scanRegion: {
|
||
width: 0.96,
|
||
height: 0.16,
|
||
centerX: 0.5,
|
||
centerY: 0.5
|
||
}
|
||
```
|
||
|
||
## 8. 原型页面示例规划
|
||
|
||
文件：`pages/scan/prototype.vue`
|
||
|
||
原型页增加“识别区域”配置区，但不直接实现摄像头 UI。页面负责展示和传递配置：
|
||
|
||
### 8.1 预设
|
||
|
||
提供三个预设：
|
||
|
||
- 默认正方形：适合二维码；
|
||
- 横向条码：适合设备码、物料码；
|
||
- 自定义：通过宽度、高度、水平位置、垂直位置调整。
|
||
|
||
### 8.2 示例数据
|
||
|
||
```js
|
||
scanRegion: {
|
||
width: 0.96,
|
||
height: 0.16,
|
||
centerX: 0.5,
|
||
centerY: 0.5
|
||
}
|
||
```
|
||
|
||
### 8.3 原型页交互
|
||
|
||
- 使用滑块或步进按钮调整四个比例参数；
|
||
- 页面实时显示当前区域参数；
|
||
- 单次扫码、连续扫码都使用当前 `scanRegion`；
|
||
- 相册识图按钮不传实时扫描区域，继续整图识别；
|
||
- 在 Web 预览中展示“仅 Android App-Plus 支持原生扫码”的提示。
|
||
|
||
## 9. 兼容性策略
|
||
|
||
### 9.1 不传配置
|
||
|
||
现有调用全部保持兼容：
|
||
|
||
```ts
|
||
openCodeScan({
|
||
smartZoom: true,
|
||
vibrate: true
|
||
})
|
||
```
|
||
|
||
行为继续使用默认正方形区域。
|
||
|
||
### 9.2 旧构建包
|
||
|
||
如果前端代码传入 `scanRegion`，但运行的是旧插件包，旧原生代码会忽略未知 Extra，仍可正常扫码，但不会限制区域。因此必须重新制作自定义基座或正式 APK。
|
||
|
||
### 9.3 非 Android 平台
|
||
|
||
继续由 `#ifdef APP-PLUS` 控制插件导入和调用，Web、iOS、小程序不加载 Android UTS 实现。
|
||
|
||
### 9.4 参数安全
|
||
|
||
原生端必须再次校验参数，不能只依赖前端：
|
||
|
||
- `width`、`height` 限制在 `0.1 ~ 1`；
|
||
- `centerX`、`centerY` 限制在 `0 ~ 1`；
|
||
- 区域超出屏幕时进行边界收敛；
|
||
- 宽高过小导致不可用时回退默认值。
|
||
|
||
## 10. 实施顺序
|
||
|
||
### 阶段一：方案验证
|
||
|
||
1. 增加 `scanRegion` 接口定义；
|
||
2. 将参数传入 Android Activity；
|
||
3. 扫描框支持矩形和位置配置；
|
||
4. 根据条码中心点过滤框外结果；
|
||
5. 原型页提供横向条码预设；
|
||
6. 保持相册整图识别。
|
||
|
||
### 阶段二：真机验证
|
||
|
||
至少验证：
|
||
|
||
- 二维码默认正方形识别；
|
||
- 横向一维码识别；
|
||
- 框内识别成功；
|
||
- 框外完全不识别；
|
||
- 条码横跨边界时的行为；
|
||
- 多个条码一内一外时只处理框内条码；
|
||
- 连续扫码只回传框内结果；
|
||
- 智能变焦不会被框外条码触发；
|
||
- 横竖屏和不同分辨率设备；
|
||
- 相册识图不受实时区域影响；
|
||
- 关闭、取消、权限拒绝和页面销毁流程。
|
||
|
||
### 阶段三：可选优化
|
||
|
||
根据真机效果再决定是否：
|
||
|
||
- 改为识别前裁剪 ROI；
|
||
- 增加边框颜色、圆角、遮罩透明度配置；
|
||
- 增加“中心点在框内 / 完全包含”两种命中规则；
|
||
- 增加一维码专用默认模板。
|
||
|
||
## 11. 验收标准
|
||
|
||
功能验收：
|
||
|
||
- 扫描框宽高和位置可以通过 `openCodeScan` 参数调整；
|
||
- 用户看到的扫描框与实际识别区域一致；
|
||
- 框外条码不会触发成功回调；
|
||
- 框内条码可以正常触发成功回调；
|
||
- 多码点选只展示有效区域内的条码；
|
||
- 旧调用不传 `scanRegion` 时行为不变；
|
||
- 单次、连续、相册三种模式互不回归。
|
||
|
||
工程验收：
|
||
|
||
- UTS 接口类型、Intent Extra、Activity 解析三层字段一致；
|
||
- 不在页面中直接修改原生插件内部逻辑；
|
||
- 所有新增配置有默认值和越界保护；
|
||
- 真机重新构建自定义基座后验证；
|
||
- 不以 Web 预览结果代替 Android 真机验证。
|
||
|
||
## 12. 结论
|
||
|
||
本项目适合采用“**比例配置 + 原生扫描框绘制 + 条码结果区域过滤**”作为第一版实现。
|
||
|
||
该方案能满足截图所示的横向矩形识别场景，改动范围可控，且能保留当前插件已有能力。真正的图像裁剪 ROI 作为后续优化，不在第一版中引入，以降低旋转、坐标映射和多码点选的回归风险。
|