33 CoreVisionKit 概述与系统能力检测

引言

HarmonyOS 5.0 引入"Kit"化 SDK 组织方式后，视觉类 AI 能力被统一收敛进 @kit.CoreVisionKit（基础视觉服务）。"拍照识别文字"工程只用到其中的一个模块——文字识别 textRecognition，但工程代码里有一行很容易被忽略的关键判断：

if (canIUse('SystemCapability.AI.OCR.TextRecognition')) {
  // 走 OCR 识别
} else {
  recognitionString = context.resourceManager.getStringSync($r('app.string.Device_not_support').id);
}

这行判断决定了应用在不同设备上的"生死"：鸿蒙的 AI 能力不是所有设备都具备，OCR 等能力只存在于特定芯片与系统版本的设备上。本文系统梳理 CoreVisionKit 的能力矩阵，讲透 canIUse 系统能力检测的用法，以及"不支持时的降级策略"，并结合工程代码演示完整的防御式写法。

正文知识点

Kit 聚合：一次导入，多能力可用

传统 API 按模块散落（@ohos.ai.textRecognition、@ohos.ai.faceDetection……），Kit 化之后统一从聚合包导入：

import { textRecognition } from '@kit.CoreVisionKit';  // 工程实际写法
import { image } from '@kit.ImageKit';                 // 图像能力同理

优点显而易见：编译期依赖更清晰、Tree-shaking 更友好、文档入口统一。@kit.CoreVisionKit 内部按能力拆成多个子模块，textRecognition 只是其中之一。

CoreVisionKit 能力矩阵

CoreVisionKit（基础视觉服务）聚合了机器视觉相关的系统级 AI 能力，其核心能力与典型场景如下：

能力（模块）

能力说明

系统能力（检测用）

典型场景

文字识别 textRecognition	OCR：图像 → 字符信息，输出文本与坐标	SystemCapability.AI.OCR.TextRecognition	拍照识字、票据录入（本文工程）
文档检测 documentDetection	检测文档边缘，输出四角坐标与角度	SystemCapability.AI.OCR.* 系列	拍文档自动切边、扫描矫正
通用卡证识别 generalCardRecognition	检测并识别卡证类主体	同上	身份证、银行卡翻拍
表格识别 formRecognition	检测表格区域、单元格结构并识别内容	同上	报表数字化、Excel 录入
人手关键点检测 handKeypointsDetection	检测人手关键点（手指关节点坐标）	同上	手势交互、指尖跟随
文字图像增强 textEnhancement	对低清/模糊文字图做超分增强	同上	放大后的文字更利于 OCR
人脸检测（faceDetection 等）	检测人脸框、关键点、姿态	SystemCapability.AI.* 其他系列	相机美颜、相册聚类

上表"系统能力"列除文字识别外均以 SystemCapability.AI.OCR.* 系列示意（同属 OCR 能力族，具体名以官方文档为准），其命名规则与模块名一一对应，例如文字识别即 TextRecognition。结论：工程里检测的是 SystemCapability.AI.OCR.TextRecognition，任何设备只要系统裁剪掉了该能力，canIUse 就会返回 false。

canIUse：系统能力检测的入口

canIUse 是全局函数（无需 import），用来查询当前设备/系统是否支持某个特性，入参可以是系统能力名、API 版本等：

// 返回 boolean
let supportOcr: boolean = canIUse('SystemCapability.AI.OCR.TextRecognition');

对 AI 能力而言，检测的意义在于：同一个应用可能跑在手机、平板、2in1、智慧屏等不同形态设备上，各设备的系统裁剪（system_capability 配置）不同，OCR 这类依赖专属算力的能力并非处处可用。不检测直接调用，轻则接口抛错（如 201 能力不存在），重则直接 crash。

能力降级策略

检测到不支持后，应用应当优雅降级，而不是报错崩溃。降级策略一般分三层：

• 提示层：给用户明确文案（工程返回 Device_not_support："当前设备不支持该功能"）；
• 功能层：隐藏/禁用入口按钮，避免用户点了才提示；
• 替代层：无 OCR 时退化为"仅保存图片"等基础能力。

工程采用的是 1+2 组合：检测失败直接返回固定文案并打日志，UI 侧弹窗展示文案。

代码示例

工程中的完整防御式识别代码（源码参考：entry/src/main/ets/common/utils/Camera.ets），逐段解读：

async recognizeImage(buffer: ArrayBuffer): Promise<string> {
  let imageResource = image.createImageSource(buffer);
  let pixelMapInstance = await imageResource.createPixelMap();
  let visionInfo: textRecognition.VisionInfo = { pixelMap: pixelMapInstance };
  let textConfiguration: textRecognition.TextRecognitionConfiguration = {
    isDirectionDetectionSupported: true
  };
  let recognitionString: string = '';
  const context: common.UIAbilityContext = AppStorage.get('context') as common.UIAbilityContext;
  try {
    // 能力检测：不支持则走降级文案
    if (canIUse('SystemCapability.AI.OCR.TextRecognition')) {
      await textRecognition.recognizeText(visionInfo, textConfiguration).then((TextRecognitionResult) => {
        if (TextRecognitionResult.value === '') {
          recognitionString = context.resourceManager.getStringSync($r('app.string.unrecognizable').id);
        } else {
          recognitionString = TextRecognitionResult.value;
        }
      })
      pixelMapInstance.release();
      imageResource.release();
    } else {
      recognitionString = context.resourceManager.getStringSync($r('app.string.Device_not_support').id);
      Logger.error(TAG, `device not support`);
    }
  } catch (error) {
    let err = error as BusinessError;
    hilog.error(0x0000, 'Camera', `recognizeImage failed. code=${err.code}, message=${err.message}`);
  }
  return recognitionString;
}

更可复用的做法是抽出独立的检测函数，供多处使用：

// 封装：能力检测 + 兜底文案，返回 (是否可用, 不可用时的提示)
function checkOcrSupport(): { supported: boolean; tip: string } {
  if (canIUse('SystemCapability.AI.OCR.TextRecognition')) {
    return { supported: true, tip: '' };
  }
  // 从资源读取多语言兜底文案，等价于工程的 $r('app.string.Device_not_support')
  const context: common.UIAbilityContext = AppStorage.get('context') as common.UIAbilityContext;
  return {
    supported: false,
    tip: context.resourceManager.getStringSync($r('app.string.Device_not_support').id)
  };
}

再如工程第 72 行的按钮点击入口，也可以先检测再决定是否放行拍照按钮：

aboutToAppear() {
  // 不支持 OCR 时，识别按钮置灰并提示，避免用户空等
  if (!canIUse('SystemCapability.AI.OCR.TextRecognition')) {
    this.ocrDisabled = true; // 配合 .enabled(!this.ocrDisabled)
  }
}

运行效果与注意事项

• 真机差异：canIUse 返回结果与设备型号、系统裁剪强相关，务必在真机（而非模拟器）验证——OCR 官方约束明确"不支持模拟器"；
• 字符串资源优先：降级文案放 resources/base/element/string.json（如工程 Device_not_support、unrecognizable），配合 resourceManager.getStringSync 自动完成多语言适配；
• 检测 ≠ 成功：canIUse 为 true 只代表"能力存在"，实际识别仍可能因输入图像不合格（如分辨率超出范围）抛错，所以工程同时保留 try-catch 双保险；
• 不要每个像素都检测：canIUse 开销极小，但也不需要每次拍照都查；在页面初始化（aboutToAppear）时检测一次、缓存结果即可；
• 注意 kit 版本：5.0.5 SDK 下 @kit.CoreVisionKit 已完全可用；旧版本（API 11 之前）对应 @ohos.ai.* 老模块，迁移时同步替换 import 与系统能力名。

总结

CoreVisionKit 是鸿蒙视觉 AI 能力的统一入口，文字识别只是其一；能力矩阵决定了"有什么"，而 canIUse('SystemCapability.AI.OCR.TextRecognition') 决定了"这台设备上能不能用"。工程的做法值得直接借鉴：能力检测 → 支持则识别 → 结果为空给"无法识别"文案；不支持则给"设备不支持"文案，全程 try-catch 兜底。这种"检测 + 降级 + 兜底"的三段式防御，是鸿蒙 AI 类应用在上真机前必须补齐的最后一块拼图。