HarmonyOS 7 Scan Kit 硬件探测与扫码降级实战
背景：泛终端扫码绑定为什么需要前置探测在泛终端项目中，“扫码绑定设备”经常被低估。同一应用可能运行在旗舰手机、轻量智能手表、无摄像头智慧屏、只有前置弱摄像头的教育平板上。早期做法是硬编码机型，或在拉起相机流后捕获异常。这种被动防御很脆弱：低内存设备上强行拉起带 AR 动画和复杂取景框的 Custom Scan，可能触发 OOM 崩溃；更严重时相机 HAL 死锁，影响系统稳定性；即使捕获异常，用户面对黑屏后的延迟报错，体验也很糟糕。
HarmonyOS 7.0（API 26）的 Scan Kit 增加了硬件探测能力。系统级 API 可直接查询当前设备是否支持自定义界面扫码、是否支持默认界面扫码。这样可在业务逻辑发生前，根据硬件拓扑设计 UI 降级：能力不足时降级到系统默认低开销扫码，无摄像头设备则降级为手动输入或局域网发现。
Scan Kit 两个探针 API 的定位
API 26 中，@kit.ScanKit 模块下的 scanCore 命名空间新增了 isCustomScanSupported() 和 isDefaultScanSupported()。它们返回 boolean，背后联动操作系统设备信息树与硬件资源水位线。
isCustomScanSupported() 面向自定义扫码。Custom Scan 需要应用自行接管相机数据流，通常为 YUV 格式，在应用进程空间分配大量 Buffer，并通过 NPU 或 CPU 做高频图像帧特征提取和解码。返回 true 的隐式条件很苛刻：设备必须有满足基础分辨率和对焦能力的后置摄像头；系统评估当前可用连续内存足够承载高频渲染与解码流水线；设备 CPU 或 NPU 有足够算力在规定时间完成条码识别，避免主线程阻塞或发热过载。任一条件不满足就返回 false，从源头阻止应用强行拉起沉重自定义 UI。
isDefaultScanSupported() 面向默认扫码。Default Scan 是 HarmonyOS 系统提供的独立 Applet（小程序态或系统级 UI 进程）。相机流接管、解码运算、内存分配全部在操作系统特权进程中完成，应用进程只需等待返回的扫码结果 String。优势包括：极低进程开销，应用不需为相机流分配庞大内存；硬件级优化，系统进程可直接调用更底层硬件加速通道，低端手表也能流畅解析；安全性与解耦，避免应用直接操作底层相机 HAL 带来的不合规风险。在手表等穿戴设备上，通常 isCustomScanSupported() 返回 false，而 isDefaultScanSupported() 返回 true，这就是优雅降级的基础。
决策链路与工程结构
企业级架构要把硬件探测、权限申请、UI 路由分发串成健壮状态机。原则是：先探测高配，后探测低配，最后全面降级。这样可把业务从盲目试错转为确定性调度，消除弱摄像能力设备上的崩溃风险。
示例工程采用高内聚服务层封装，代码结构如下：
entry/src/main/ets/
├── entryability/
│ └── EntryAbility.ets
├── pages/
│ ├── ScanEntryPage.ets
│ ├── CustomScanPage.ets
│ └── FallbackInputPage.ets
└── services/
├── ScanHardwareProbe.ets
└── PermissionManager.ets
ScanHardwareProbe 是硬件能力探测与决策中枢，PermissionManager 负责相机权限调度。
封装硬件探针：能力分级
在 services/ScanHardwareProbe.ets 中，定义能力枚举，严格区分旗舰级自定义、标准级默认、无能力三档：
export enum ScanCapabilityLevel {
CUSTOM_SUPPORTED = 0,
DEFAULT_ONLY_SUPPORTED = 1,
UNSUPPORTED = 2
}
评估方法建议异步实现，因为底层可能实时读取硬件设备树状态，避免阻塞应用主线程。核心探测顺序是：
import { scanCore } from '@kit.ScanKit';
const canCustom = scanCore.isCustomScanSupported();
if (canCustom) {
return ScanCapabilityLevel.CUSTOM_SUPPORTED;
}
const canDefault = scanCore.isDefaultScanSupported();
if (canDefault) {
return ScanCapabilityLevel.DEFAULT_ONLY_SUPPORTED;
}
return ScanCapabilityLevel.UNSUPPORTED;
异常应统一视为 UNSUPPORTED，确保应用不崩溃，符合防御性编程。原文代码还使用 hilog 记录探针结果，便于在不同设备上追踪降级链路。
入口页调度与默认扫码降级
在 ScanEntryPage.ets 中，用户点击扫码按钮后先调用探针，再按能力分发。用 isLoading 防止重复点击引发竞态。分发逻辑如下：
const capability = await ScanHardwareProbe.evaluateScanCapability();
switch (capability) {
case ScanCapabilityLevel.CUSTOM_SUPPORTED:
router.pushUrl({ url: 'pages/CustomScanPage' });
break;
case ScanCapabilityLevel.DEFAULT_ONLY_SUPPORTED:
this.launchSystemDefaultScan();
break;
case ScanCapabilityLevel.UNSUPPORTED:
router.pushUrl({ url: 'pages/FallbackInputPage' });
break;
}
当进入 DEFAULT_ONLY_SUPPORTED，应用调用系统默认扫码。构造 ScanOptions 时可限制只扫描二维码和一维码，以提高系统底层解码速度，并开启自动连续对焦。startVisibleScan 会拉起系统扫码 UI，应用进程挂起等待结果：
const options: scanBarcode.ScanOptions = {
scanTypes: ,
enableMultiMode: true
};
scanBarcode.startVisibleScan(getContext(this), options)
.then((result: scanBarcode.ScanResult) => {
this.processBindLogic(result.originalValue);
})
.catch((error: BusinessError) => {
// 处理用户取消或超时
});
拿到 originalValue 后继续绑定验证。UNSUPPORTED 则路由到 FallbackInputPage，让用户手动输入设备 SN 码，或在无摄像头智慧屏上走手动绑定码、局域网发现模式。原文提到，无摄像头智慧屏端可隐藏扫码按钮，或点击后平滑过渡到“请输入设备绑定码”纯表单界面。
四类真实场景的分发结果
1. 折叠屏旗舰手机（如 Mate X 系列）：顶级 NPU、大运存、主摄性能极速。isCustomScanSupported 返回 true，进入 CustomScanPage，可渲染环境光监测动态按钮和复杂 AR 扫描取景框，提供顺滑科技感体验。
2. 轻量级智能手表（Watch 系列）：屏幕小、运存紧张、摄像头以基础前置为主。Custom 返回 false，Default 返回 true。应用拦截拉起 Custom Scan 的危险操作，转入系统独立进程的 Default Scan，降低内存吃紧，避免 OOM，同时完成扫码。
3. 无摄像头商显智慧屏：两个探测 API 均返回 false。探测到全无支持后，直接路由 FallbackInputPage，提示用户用遥控器输入设备配对码，或展示局域网内的自动发现设备列表。
4. 高负载发热降频手机：硬件本身好，但后台任务繁重、内存剩余极低。系统在 API 内部评估内存水位低，Custom 动态返回 false，Default 返回 true。系统自我保护机制生效，自动降级默认扫码，保证核心扫码可用，而不是在内存危急时强行分配巨量 Buffer 导致进程被杀。
避坑指南
第一，权限状态与硬件探针不是强关联。isCustomScanSupported 探测的是物理硬件架构和系统运力，不是用户是否授予相机权限。即使用户在系统设置拒绝相机权限，只要旗舰机硬件满足，该方法仍可能返回 true。因此执行探测前必须配合 abilityAccessCtrl 显式检查和请求 ohos.permission.CAMERA，不能用探针结果替代权限校验。
第二，多模态平板横竖屏旋转陷阱。教育平板等设备上，若探测支持 Custom Scan 并进入自定义界面，开发者需自行处理 display.on('change') 带来的屏幕旋转；不做矩阵重映射，相机预览流会被拉伸变形。若降级到 Default Scan，系统级 Applet 会自动处理横竖屏，这是默认扫码的隐性红利。
第三，异步探针可能引发 UI 主线程挂起。虽然用 await 等待探针返回，但如果底层硬件总线处于异常重启状态，探针可能存在几十毫秒延迟。调用 evaluateScanCapability 期间应提供 Loading 反馈，例如 this.isLoading = true，避免用户毫无响应而疯狂连击，造成状态机紊乱。
第四，不要强制绕过探测。有些开发者为了统一多端视觉风格，忽略 isCustomScanSupported 返回 false，硬写代码强制初始化 Custom Scan。在 API 26 环境中，这种不合规行为会被底层系统服务层强行熔断，直接抛出未捕获的 C++ 侧异常。必须尊重探针决策。
总结
HarmonyOS 7.0 的 Scan Kit 通过 isDefaultScanSupported 与 isCustomScanSupported，把系统底层硬件拓扑和资源水位线传递给应用层。基于硬件探针的优雅降级架构，改变了过去依赖机型黑名单和异常捕获的被动防御。通过前置探测、状态分发、系统进程接管、表单兜底，跨设备部署的稳定性更好，也避免了非授权访问底层 HAL 资源带来的合规风险。泛终端开发中，感知硬件水位、执行优雅降级应成为架构习惯：尊重不同形态设备的物理约束，才能写出企业级健壮的万物互联应用。
Re: HarmonyOS 7 Scan Kit 硬件探测与扫码降级实战
楼主这篇总结得很实在，扫码绑定确实不能一上来就硬拉自定义相机流。前置探测把相机 HAL、内存水位和算力问题挡在业务前面，比事后捕获异常再黑屏报错稳得多。能力分三档、异常统一归到 UNSUPPORTED、入口页用 isLoading 防竞态，这些细节都很工程化。默认扫码降级到系统进程处理，在手表或弱摄像头设备上确实更合理，限制码类型和开启连续对焦也能减少等待。想请教下 PermissionManager 在自定义扫码和默认扫码两条路径下的权限申请时机是否一样？另外无摄像头设备降级到手动输入或局域网发现后，有没有做超时或重试兜底？期待后续分享。Re: HarmonyOS 7 Scan Kit 硬件探测与扫码降级实战
楼主这个降级思路很清晰，先探测高配再探测低配最后兜底，比拉起相机后捕异常靠谱多了。特别是手表这种 isCustomScanSupported 为 false、isDefaultScanSupported 为 true 的场景，用系统默认扫码确实能少很多内存和相机 HAL 风险。 我有个小疑问：入口页 evaluateScanCapability 如果底层读取设备树偶发慢，是不是给个超时和缓存会更稳，不然 isLoading 一直转也影响体验。还有 UNSUPPORTED 分支目前只进 FallbackInputPage，如果那个页面同时要承载手动输入和局域网发现，建议把二次分流也做成明确状态，避免页面内又出现硬编码判断。 权限这块也想看后续，默认扫码和自定义扫码的权限申请时机是否一致，在无摄像头设备上会不会直接跳过申请。整体架构值得借鉴，感谢分享。Re: HarmonyOS 7 Scan Kit 硬件探测与扫码降级实战
这个前置探测的思路很赞同。很多扫码绑定问题确实不是扫码本身，而是没先看设备能力就把 Custom Scan 拉起来，低内存设备 OOM、相机 HAL 死锁这些风险太伤了。把 isCustomScanSupported 和 isDefaultScanSupported 分成三档，再按 CUSTOM_SUPPORTED、DEFAULT_ONLY_SUPPORTED、UNSUPPORTED 路由，异常统一按 UNSUPPORTED 兜底，基本就把崩溃路径掐掉了。 我比较关心两个落地细节：一是探针调用频率，是每次点扫码都实时查，还是入口初始化时缓存？首帖提到返回结果背后联动硬件资源水位线，穿戴设备上资源状态可能变化，缓存会不会导致误判。二是默认扫码里限制 QR_CODE 和 EAN13、开多码模式，在低端设备上是否经过实测，解码速度和系统 UI 拉起耗时大概什么表现。 另外无摄像头设备降级到手动输入或局域网发现，和后续绑定流程怎么衔接？是统一成同一种设备标识回调，还是各走各的？整体这套服务层封装和状态机思路很清晰，对泛终端项目很有参考价值。
页:
[1]