一、当摄像头开始"读懂"世界

手机摄像头早已不只是记录画面的工具。十多年前，我们用它拍风景、拍家人；今天，我们更频繁地用它去"对准"——对准一张名片、一本图书的封底、一张身份证、一张发票。对准之后呢？如果设备能瞬间读懂上面的文字，并把这些文字变成可编辑、可检索、可联动的数字信息，那摄像头的角色就从"记录者"跃迁成了"理解者"。这种跃迁，正在成为移动智能体验真正的分水岭。

在 HarmonyOS NEXT 上，这条技术链路的起点是端侧 OCR（Optical Character Recognition，光学字符识别）。所谓"端侧"，意味着图像识别的推理过程完全发生在设备本地——既不把照片上传到云端，也不依赖远程服务器的算力。"识别"只是第一步，真正让人眼前一亮的是第二步：把识别结果以 AR（Augmented Reality，增强现实）的方式实时叠加在画面上，让数字信息"贴"在真实物体上。你镜头扫过一本杂志，书名、作者就浮在纸面上方；你扫过一张名片，对方姓名和电话立刻被框出来——这就是端侧 OCR 与 AR 交互合力带来的魔力。

有人会问：云端 OCR 不是更准吗？确实，大模型的识别能力往往更强，但代价是数据要离开设备。而证件、合同、名片这类场景，恰恰承载着我们最不愿意外泄的信息。端侧方案用略低一点的精度，换来了"数据不出设备"这个结构性优势。在隐私监管日益收紧的今天，这笔交易对很多应用来说是划算的。

为什么是现在？因为端侧算力的成熟让这件事第一次变得"既快又省"。近年来的移动 SoC 普遍集成了专用 NPU，算力从几个 TOPS 涨到几十个 TOPS，足以在毫秒级跑完一次轻量 OCR 推理；同时模型压缩技术（量化、剪枝、知识蒸馏）把原本庞大的识别网络压进了几 MB 的空间。硬件与算法的双向奔赴，才让"在手机上实时读懂文字"从实验室设想变成可量产的特性。HarmonyOS NEXT 把这些能力收口成统一的 @ohos.vision 接口，开发者不必关心底层跑在 NPU 还是 CPU，只需调用识别器即可。

这篇文章就带你走完这条从"看见"到"读懂"再到"标注"的完整路径。我们会先认识 @ohos.vision 提供的文字识别能力，再看如何把摄像头变成一台实时扫描仪，接着用 XComponent 在画布上画出识别框，最后聊聊证件、名片、文档这三类典型场景，以及端侧处理在隐私上的天然优势。每一节都配有短小精悍的代码片段，目标是讲透原理，而非堆砌 Production 代码。

下面，让我们从最底层的能力说起。

二、@ohos.vision 文字识别：从一张图到一串字

HarmonyOS 把机器视觉能力收敛在 @ohos.vision 体系之下，其中文字识别相关的核心入口是 textRecognition，而真正执行识别的实例被称为 textDetector（文本检测器）。理解它的使用流程，是掌握整个 OCR 模块的关键。很多开发者第一次接触时会困惑：为什么不直接给我一个 recognize(image) 就完事？原因在于，端侧模型有加载成本，把"初始化"和"识别"拆开，正是为了让你可以多次复用同一个模型实例。

整个流程可以拆成四个动作：创建检测器 → 初始化（加载模型）→ 喂入图像并识别 → 释放资源。看似简单，但每一步都有需要留意的细节，稍有不慎就会掉进性能或内存的坑。

第一，创建与初始化。识别器在首次使用前需要 init，这一步会把端侧模型权重从安装包加载进内存。模型是轻量化的，但仍建议在一次识别会话中复用同一个 detector 实例，而不是每识别一张图就 init 一次、release 一次——那样会反复触发模型加载，白白消耗数百毫秒。正确做法是：进入扫描页面时 init 一次，退出页面时 release 一次，中间的所有识别都复用它。

第二，喂图。识别的输入不是文件路径，而是一个 VisionInfo 对象，里面最核心的字段是 pixelMap——也就是鸿蒙统一的图像像素句柄。无论是从相册解码出的图片，还是相机预览的一帧，只要能转成 PixelMap，就能送进识别器。这种"一切皆 PixelMap"的设计，让静态图片、相机帧、截屏可以被同一套识别逻辑处理，无需为每种来源写不同代码。

第三，拿结果。recognizeText 返回的是一个 VisionText 结构，它不仅包含识别出的纯文本字符串，还包含每个文字块（block）、每行（line）、每个字符（character）的位置坐标。这些坐标，是后续做 AR 标注叠加的"原材料"。换句话说，OCR 给你的不只是"字"，还有"字在哪里"。

第四，释放。结束识别后务必 release，否则模型权重会一直占用内存。在 ArkTS 里，你可以把 init/release 配对放进 aboutToAppear / aboutToDisappear 生命周期，利用页面的生灭来管理资源，既不易遗漏，也最符合直觉。

下面这段代码展示了最精简的识别骨架，去掉了所有错误处理与线程细节，只为讲透主流程：

import { textRecognition } from '@ohos.vision';

// 1. 创建并初始化检测器
const detector: textRecognition.TextDetector =
  textRecognition.createTextRecognizer();
await detector.init();

// 2. 构造输入：PixelMap + 配置
const visionInfo: textRecognition.VisionInfo = { pixelMap: pm };
const config: textRecognition.TextRecognitionConfiguration = {
  language: 'zh',                        // 识别语言
  isDirectionDetectionSupported: true    // 支持文本方向检测
};

// 3. 执行识别
const result = await detector.recognizeText(visionInfo, config);
console.info('识别文本:', result.value); // 纯文本结果

await detector.release();                // 4. 用完释放

可以看到，result.value 是一整段文字，但真正有趣的是 result.blocks。每一个 block 都带着 boundingBox（外接矩形）和一个字符列表，列表里每个 element 都有自己的四边形顶点。这些顶点构成了"框选"的可能，让我们有机会在画面上精确圈住每一个字、每一行。

还有一个工程层面的建议：识别结果里的坐标，默认是基于"送入识别的那张 PixelMap 的尺寸"。如果你在送识别前对图像做了降采样，那么画框时也要按相同比例缩放，否则框会"张牙舞爪"地错位。这个小坑，我们在第四节会专门解决。

在深入坐标之前，先看清 VisionText 的层级结构，它直接决定了你能"框"到多细。最外层是 blocks（文字块，往往对应一段或一块独立文本），每个 block 内是 lines（行），每行内是 characters（字符）。如果你只想高亮整块，遍历 blocks 即可；想精确到单个字，就下沉到 characters。层级越深，绘制开销越大，所以"框到哪一层"本质上是体验与性能的权衡。

// 下沉到字符级：拿到每个字的四边形顶点
for (const block of result.blocks) {
  for (const line of block.lines) {
    for (const ch of line.characters) {
      const quad = ch.cornerPoints; // 四点坐标，可画任意四边形
      // quad 是四个 {x, y}，适合倾斜文字的精确贴合
    }
  }
}

再聊几个能直接提升准确率的小习惯。第一，引导用户把镜头放平、拉近距离，避免透视畸变——端侧模型对"拍歪了"的容忍度远不如云端大模型。第二，关注光照与对比度：阴影、反光、低对比度的纸质文档是识别杀手，UI 上做一点"光线不足"的提示，比事后纠错更省力。第三，识别前可对 PixelMap 做轻量预处理，比如灰度化、对比度增强，这些操作成本极低却常能救回几个模糊字符。

最后是关于健壮性。识别是异步的，recognizeText 可能抛异常（图像为空、模型未就绪等）。在 Production 里，至少要把 init 失败的回调兜住，避免页面因一次识别异常而白屏。一个干净的写法是用 try/catch 包裹识别，并在 catch 中提示"识别失败，请重试"，而不是让错误向上冒泡。把异常关进笼子里，体验才稳。

值得单独点出的是语言参数。端侧模型通常会针对特定语种优化，中文、英文、日文各有不同的权重集合。如果你明确知道场景只扫中文名片，就把 language 收窄，识别精度和速度都会更好。反之，频繁切换语言会带来模型切换开销，能固定就固定。一个实用的策略是：让用户在设置里选一次默认语言，而不是每次识别都动态探测。

配置里还有一个常被忽视的开关：isDirectionDetectionSupported。它让检测器判断文字是横排还是竖排、是否倾斜。对于扫描古籍、竖排标题、倾斜拍摄这类场景，这个开关能显著提升召回率——毕竟真实世界里的文字很少像打印稿那样端正。但对于规整的证件扫描，关掉它能省下一点算力。

到这里，我们已经能让设备"读"出一张图里的字。但静态图片只是热身，真正的挑战是——让摄像头"边看边读"。

三、相机实时识别：让预览流成为扫描仪

静止图片的 OCR 适合"拍完再识别"，但更多场景下，用户希望镜头一对准目标，屏幕上立刻浮现识别结果。这就需要一个持续运作的实时识别回路：相机不断吐出预览帧，每一帧都被送进识别器，识别结果再回传 UI。把这个回路搭好，普通的相机预览就变成了"实时扫描仪"。

在 HarmonyOS NEXT 中，承接这个角色的有两种思路。一种是 CameraPicker，一种是直接用 camera 模块驱动 XComponent 预览。两者定位不同，理解差异才能选对工具。

先说 CameraPicker。它本质上是一个系统级选择器（Picker），封装了拍照、选图的交互，开发者可以用极低的代码量拿到一张用户确认过的图像。它的好处是"快"——不必自己申请相机权限、不必自己管理相机生命周期、不必处理各种机型兼容性。但代价是：它更偏向"拍摄一张"的离散交互，而非逐帧的连续识别。所以当你的需求是"用户点一下，拍一张，再识别"，CameraPicker 是事半功倍的入口；当你需要镜头不关、画面在动、文字在变的连续 AR 体验，它就力不从心了。

下面是用 CameraPicker 拉起相机并取回图像的最小代码。注意它返回的是 URI，你需要再用图片解码接口把它变成 PixelMap 才能送识别：

import { cameraPicker } from '@ohos.multimedia.cameraPicker';
import { camera } from '@kit.CameraKit';

const mediaType: cameraPicker.PickerMediaType =
  cameraPicker.PickerMediaType.PHOTO;
const pickerProfile: cameraPicker.PickerProfile = {
  cameraPosition: camera.CameraPosition.CAMERA_POSITION_BACK
};
// 拉起系统相机，拿到用户拍摄的结果
const result = await cameraPicker.pick(
  getContext(), mediaType, pickerProfile
);
// result.resultUri 即拍摄图像 URI，可解码为 PixelMap 后识别

而当你真正需要"实时"——即镜头保持开启、画面持续流动、识别结果随画面刷新——就要用 camera 模块把预览流接到 XComponent 的 surface 上，并在合适时机抽取帧送识别。这里有一个关键取舍：并不是每一帧都要识别。60fps 的预览流如果帧帧都送进 OCR，端侧 NPU 也会被压垮，UI 还会因为主线程阻塞而卡顿。

为什么"实时"值得额外付出复杂度？因为它改变了交互的本质。离散拍照是"先拍后看"，用户要等结果、再决定下一步；而实时识别是"边看边懂"，框随景动，用户能在按下快门前就确认设备读懂了什么。这种即时反馈极大降低了误操作率，也让扫描从"任务"变成"游戏"。代价是我们要亲手管理相机生命周期、抽帧节流、坐标对齐——这些额外功夫，换来的正是那一份"它真的看懂了"的踏实感。

更聪明的做法是"节流 + 触发"。例如，每 300 毫秒取一帧识别，或者仅当用户点击"扫描"按钮时取当前帧。帧的抽取通常借助 ImageReceiver 或预览回调拿到 image，再转成 PixelMap 喂给 detector。识别是异步的，必须防止"上一帧还没识别完，下一帧又来了"的叠加拥堵——一个简单的布尔标志位 busy 就能锁住在途请求，超时的旧帧直接丢弃。

下面这段伪骨架，展示实时识别回路的核心逻辑，省略了相机创建与 surface 绑定的繁琐细节，只保留最关键的控制流：

let busy = false;  // 防止识别请求堆叠

async function onPreviewFrame(image: image.Image) {
  if (busy) { image.release(); return; }  // 上一帧还没算完，丢弃
  busy = true;
  const pm = await imageToPixelMap(image); // 帧 -> PixelMap
  const detector = getSharedDetector();    // 复用检测器（第二节强调过）
  const res = await detector.recognizeText(
    { pixelMap: pm }, defaultConfig()
  );
  emitRecognition(res);   // 把结果抛给 UI 层绘制
  pm.release();
  busy = false;
}

注意到我们再次复用了 getSharedDetector()，而不是每次新建。这正是第二节强调的"会话内复用"原则在实时场景下的体现——实时回路里，检测器的 init/release 成本会被无限放大，复用是刚需而非优化项。

还有一点工程经验值得展开：相机的预览分辨率往往远高于识别所需。把 4K 帧直接送识别，既慢又费电。建议在抽帧后先做降采样（downsample）到 720p 左右，再送识别。端侧 OCR 对分辨率没有那么贪婪，降采样带来的速度收益远大于那一点点精度损失。实测中，720p 与 1080p 的识别准确率差距微乎其微，但耗时可能差出一倍。

抽帧的另一个考量是"稳定性检测"。如果用户手在抖，连续几帧画面差异很大，识别结果也会跳变，UI 上的框会乱闪。一个简单的滤波策略是：只有当连续两帧的识别结果文本相似度较高时，才更新 UI；否则认为画面还在动，暂不刷新。这能让 AR 标注看起来"稳如磐石"。

除此之外，实时回路还要注意资源释放的对称性：相机、ImageReceiver、PixelMap 三者都要在页面退出时成对释放，漏掉任何一个都可能造成相机被占用、下次打不开。把资源释放集中到一个 cleanup 函数里，比散落在各处的释放更可靠。

讲清楚"怎么读"，接下来就是"怎么画"——让识别结果活现在画面之上。

四、AR 标注叠加：在 XComponent 画布上画框

OCR 的回报不止于"得到一段文字"，更在于"知道每个字在哪"。当我们把坐标画回预览画面，用户就能直观看到：设备确实读懂了这张名片上的姓名、电话、公司。这种"所见即所得"的反馈，正是 AR 交互的精髓——它把抽象的文本结果，重新锚定回用户正在看着的物理世界。

HarmonyOS 里承载自定义绘制的最合适控件是 XComponent。它允许我们在 ArkTS 侧拿到一块真实的图形表面（surface），在其上用 2D 绘制接口画出矩形、文字、高亮。把 XComponent 叠在相机预览的 XComponent 之上，一个负责"显示真实世界"，一个负责"绘制数字信息"，二者位置精确对齐，就成了最简单的 AR 叠加层。这种"分层"思路至关重要：不要把绘制逻辑混进相机预览本身，独立一层让职责清晰，也便于控制刷新频率。

绘制的核心，是把识别坐标映射到屏幕坐标。识别器返回的坐标基于"送入识别的那张 PixelMap 的尺寸"，而屏幕预览有自己的尺寸和缩放。如果两者不一致，画出来的框就会"跑偏"——这是几乎所有 AR 标注初学者都会踩的坑。解决方法是计算一个统一的变换：先求出预览画面在屏幕上实际显示的区域（要算上裁切 letterbox），再把识别坐标按相同比例映射过去。这个映射函数，我们起名叫 toScreenRect。

下面展示在 XComponent 的 2D canvas 上画识别框的精简逻辑，以及坐标映射的核心换算：

// 假设 previewRect 为预览在屏幕上的实际显示区域
function toScreenRect(box: Rect, srcW: number, srcH: number): Rect {
  const sx = previewRect.width / srcW;   // X 方向缩放比
  const sy = previewRect.height / srcH;  // Y 方向缩放比
  return {
    x: previewRect.x + box.x * sx,
    y: previewRect.y + box.y * sy,
    width: box.width * sx,
    height: box.height * sy
  };
}

这段代码虽然短，却点出了 AR 标注里最容易被忽视的一环：识别坐标系与屏幕坐标系的桥接。只要 srcW/srcH 用的是"送识别那张图"的真实尺寸（而不是原图尺寸），框就会稳稳贴住文字。我在第二节提醒过降采样会让坐标错位，这里就是解法——映射时用的源尺寸，必须和送识别时的尺寸严格一致。

下面则是把结果画到 canvas 上的主流程，它点出了 AR 标注的三个层次：

// ctx 为 XComponent 拿到的 Canvas 绘制上下文
function drawBlocks(ctx: CanvasRenderingContext2D, result: VisionText) {
  ctx.clearRect(0, 0, width, height);  // 先清屏
  ctx.strokeStyle = '#00E5FF';         // 青色高亮框
  ctx.lineWidth = 2;
  ctx.font = '14px sans-serif';
  for (const block of result.blocks) {
    const box = block.boundingBox;     // 基于 PixelMap 的坐标
    const r = toScreenRect(box);       // 映射到屏幕显示区
    ctx.strokeRect(r.x, r.y, r.width, r.height);
    ctx.fillText(block.value, r.x, r.y - 4); // 框上方标注文字
  }
}

第一层是"框"——用 strokeRect 画出文字块的边界，给用户明确的视觉锚点。第二层是"字"——直接在框旁标出识别出的文本，省去用户再去别处查看。第三层是"对齐"——toScreenRect 这个看似不起眼的函数，恰恰是体验好坏的分水岭。把这一步做对，框才会"粘"在文字上，而不是飘在空中。

更进一步，如果你想做出"扫描线"或"四角角标"那种更有科技感的 UI，可以在同一个 canvas 上叠加动画。例如一条自上而下循环移动的亮线，提示用户"正在扫描"；或者在识别框四角画 L 形标记，模仿专业扫描软件的质感。这类装饰不改变识别逻辑，却极大提升"智能感"与"专业感"。

需要提醒的是性能。AR 叠加是逐帧重绘的，如果识别结果每 300ms 更新一次，那么刷新频率也应与之匹配，而不是用独立的 60fps 动画无谓地清空重画。把绘制频率与识别频率对齐，能省下可观的 GPU 与电量开销。一个务实的做法是：识别有更新才重绘，没有更新就保持上一帧画面。

还有一个细节关乎"可信度"。识别并不是百分百准确，某些字符识别器自己也不确定。很多 OCR 结果会附带每个字符的置信度（confidence）。在 AR 标注时，可以只对置信度高于阈值的块高亮，低置信度的块用灰色虚线框提示"可能识别不准"，让用户心里有数。这种"诚实的 UI"，比一味把框画得漂亮更有价值。

讲到这里，技术骨架已经齐全：识别、实时、绘制。接下来我们把它放进三个真实场景里，看看这套能力如何落地。

五、三大扫描场景：证件、名片、文档

技术从来不是为技术本身存在的。端侧 OCR + AR 叠加这套组合，最容易在三类场景里发挥价值：证件扫描、名片识别、文档数字化。它们共享同一套底层能力，差异只在前端的"意图"与"后处理"。理解这些差异，才能让同一套骨架长出不同的血肉。

证件扫描关心的是"结构化抽取"与"边框引导"。身份证、护照这类证件版面高度规整，姓名、号码、有效期都有固定区域。实现思路是：先用 AR 框实时检测证件外轮廓（可借助视觉的形状检测或简单的边缘分析），当轮廓与屏幕中央的"取景框"大致重合、且文字清晰度达标时，提示用户"可以拍摄"。拍摄后，针对已知版式区域做定向 OCR，把号码、姓名切出来，填入表单。这里的关键体验是"防抖"——不要一检测到就自动拍，要等待画面稳定再触发，否则容易拍糊。一个常用的技巧是：当连续数帧轮廓位置变化小于阈值，才认为"稳定"，自动或提示用户拍摄。

名片识别则更偏向"联系人生成"。名片的非结构化程度更高，姓名、职位、电话、邮箱、公司交错排布，没有固定版式可言。思路是先整体 OCR 得到所有文本块与坐标，再依据排版规律做启发式归类。例如最醒目的大字号通常是姓名，带 @ 的是邮箱，连续数字可能是电话，含"公司/科技/有限"字样的是公司名。AR 叠加在这里尤其有用：用户拍摄前就能看到系统"认出"了哪些字段，拍摄后一键保存到通讯录，省去手动录入的繁琐。

下面是根据文本块内容做简单字段归类的示例。它不依赖云端 NLP，完全端侧可跑，对常见名片已足够好用：

function classify(block: TextBlock): ContactField {
  const t = block.value.trim();
  if (/^\d{11}$/.test(t)) return 'phone';        // 11 位手机号
  if (t.includes('@')) return 'email';           // 含 @ 即邮箱
  if (/(公司|科技|有限|股份)/.test(t)) return 'company';
  if (/(经理|工程师|总监|CEO)/.test(t)) return 'title';
  return 'name';  // 其余兜底为姓名
}

遇到复杂版面，再考虑把坐标关系（上下左右相邻）纳入判断，例如"公司名通常在姓名上方"“电话通常在姓名下方”。把文本内容与空间位置结合，归类的准确率会再上一个台阶。这类逻辑代码量很小，却最能体现"理解版面"的智能。

文档数字化是三者中最"重"的场景。它的目标不是抽几个字段，而是把一整页纸变成可搜索、可复制的电子文档。难点在于：手机拍的文档常有透视畸变（梯形变形），直接 OCR 精度会下降。因此文档扫描通常加一步"纠偏"——检测到文档四角后，用透视变换把梯形拉回矩形，再做 OCR。鸿蒙的图像处理能力里，配合 image 模块的变换接口即可实现。纠偏后的文档再送识别，准确率会明显提升，且能输出带版面结构的文本，而非一团乱麻。

这里多说一句透视变换的原理，它不神秘：你只要拿到文档四个角在图像中的坐标（source points），再定义目标矩形的四个角（destination points），就能解一个 3x3 的单应矩阵（homography），把原图中的任意点映射到目标矩形上。这套数学在 OpenCV 里叫 warpPerspective，在鸿蒙图像接口里对应变换与裁剪的组合调用。对开发者而言，真正难的不是算矩阵，而是"稳定地找到那四个角"——光照不均、背景复杂时角点容易丢，所以文档扫描往往结合边缘检测与轮廓近似，再用长宽比、面积等启发式过滤掉干扰轮廓。把这一步做稳，纠偏质量直接决定最终 OCR 的上限。

一个常被忽略的细节是"多页拼接"。文档数字化往往要扫好几页，每页识别完的文本应按顺序暂存，最后再统一导出。端侧处理的优势在这里再次显现：整本资料从头到尾都不离开设备，导出时也只是把本地文本拼起来而已。下面是把多页识别结果拼成一个 Markdown 文档的极简示例：

// pages: 每页识别出的纯文本数组，全部在本地
function exportMarkdown(pages: string[]): string {
  return pages
    .map((text, i) => `## 第 ${i + 1} 页\n\n${text}`)
    .join('\n\n---\n\n');
  // 返回后即可写入沙箱文件，全程不出设备
}

三个场景说完，技术实现上我们已经游刃有余。但还有一个维度，必须在任何涉及用户敏感信息的识别任务里被郑重讨论——隐私。

六、隐私考量：端侧处理为何是天然护城河

当我们用摄像头去扫身份证、名片、合同，这些画面里承载的是高度敏感的个人与商业信息。数据"去哪儿了"，是用户最该关心的问题，也是开发者最该守住的底线。端侧 OCR 在这件事上，有着云端方案难以比拟的结构性优势，值得单独用一节来展开。

最核心的一点：数据不出设备。识别推理在 NPU、CPU 本地完成，原始图像和识别结果都留在手机内存与沙箱存储里，不经过任何网络请求。这意味着即便你的后端服务器被攻破、即便传输链路被中间人监听，攻击者也拿不到用户的证件照——因为照片根本没离开过那台手机。这是一种"架构级"的隐私保护，不依赖任何运维纪律，而是由技术形态本身保证。

第二点是"用完即焚"的主动权回到了用户手里。在云端方案里，你很难确认服务商是否保留了你的图片、保留了多久、又用于了哪些别的训练。而端侧方案，开发者可以显式地做到：识别完成、抽取出所需字段后，立即 release 掉 PixelMap，删除临时帧缓存。数据生命周期完全由本地代码控制，可审计、可解释，也能在 UI 上向用户明确承诺"我们不会上传"。

第三点是权限与最小化。HarmonyOS 的权限模型要求相机、存储权限按需申请，且端侧识别不需要额外申请任何"数据外传"相关的许可。你甚至可以设计成"飞行模式下也能用"——这本身就是隐私最强的背书：一个断网也能工作的扫描仪，用户自然更放心。反观云端方案，断网即瘫痪，这种脆弱性在隐私语境下也是一种风险信号。

第四点是合规友好。随着《个人信息保护法》等法规落地，应用对敏感个人信息的处理面临越来越严的约束。端侧处理天然契合"最小必要"与"本地化"原则，在合规论证时阻力更小。当审计人员问"用户证件照流向了哪里"，你只需回答"从未离开用户设备"，即可闭环。从威胁建模的视角看，端侧方案直接消除了"传输链路"和"服务端存储"这两个最大的攻击面，攻击成本被显著抬高。

当然，端侧不是银弹。它的代价是设备算力上限与模型体积——你不可能在手机上跑一个云端级别的大模型。但回到 OCR 这件事上，中文、英文等主流语种的轻量化模型已经能在端侧跑出堪用的精度，对于证件、名片、文档这类版面相对规范的场景，完全够用。把"够用"和"不出设备"放在一起权衡，端侧往往是最优解，尤其是在隐私敏感的领域。

作为开发者，我们还能多做几件小事，把隐私友好从口号变成可感知的体验：在 UI 上明确告知用户"识别在本地完成，不会上传"；提供一键清除历史扫描记录的入口，让缓存不被遗忘在角落；对识别出的身份证号、手机号做本地脱敏显示（例如中间打星），即使屏幕被他人窥见也不会泄露全文。这些细节不增加多少代码，却能把"尊重用户"写进产品的每一帧。

写到这里，整条技术链路已经闭合。但要让它真正"好用"，还有一层工程化的功夫要做。

七、工程化调优：性能、稳定性与测试

能跑通 Demo 和能交付给用户，中间隔着一道叫"工程化"的鸿沟。端侧 OCR 的实时回路尤其经不起糙——掉帧、发热、卡顿，任何一项都会让"智能感"瞬间崩塌。这一节聊几个能直接落地、回报率很高的调优点。

性能上，最该守住的红线是"识别不阻塞 UI 线程"。识别本身是计算密集的，若直接在主线程同步调用，预览会卡住。务必走异步 await，必要时把重活挪到 TaskPool 或其他 worker 线程，让主线程只负责渲染。配合第三节的 busy 锁，既能防堆叠，又能保流畅。

稳定性上，最隐蔽的 bug 往往来自资源泄漏。相机、ImageReceiver、PixelMap、detector 四者生命周期要画成一张图，谁先开谁后关一目了然。一个好用的模式是：把所有释放集中到 onPageHide / aboutToDisappear，并加幂等保护（释放过就跳过），避免重复释放抛异常。

测试上，别只用自己的旗舰机。端侧模型在不同芯片、不同内存档位的设备上表现差异明显，建议覆盖高中低三档机型，重点看低端机的识别耗时与发热。另外，准备一组"刁钻样本"：模糊、倾斜、反光、手写体，它们最能暴露识别器的真实下限。

最后，给用户留一个"退路"。即使是端侧方案，也可能遇到极端低光或严重畸变导致识别失败。在 UI 上提供"切换为手动输入"或"重新拍摄"的入口，比让用户对着识别不出的画面干瞪眼更体面。智能的前提，是永远承认自己会失败。

八、把链路收拢成一句话

从 @ohos.vision 的 textDetector 初始化，到 CameraPicker 与实时预览帧的抽取，再到 XComponent 上那一个个青色识别框，最后落进证件、名片、文档的真实场景——端侧 OCR 与 AR 交互，本质上是在"设备看见"和"设备读懂"之间架起一座桥，再用 AR 把这理解可视化地交还给用户。

它的价值有两面。一面是体验：实时、直观、所见即所得，让冰冷的文字识别变成了有温度的交互。另一面是信任：数据留在本地，隐私有了天然护城河，让用户在把镜头对准最私密的证件时也能安心。在隐私监管日益收紧、用户权利意识不断觉醒的今天，后者或许比前者更值得我们在架构选型时优先考虑。

回顾全文，几个工程要点值得再次强调：检测器要会话内复用，别反复 init/release；实时识别要节流抽帧，用 busy 锁防止请求堆叠，并对帧降采样；AR 画框前务必算对坐标变换，让框"粘"在文字上而非飘在空中；场景落地时，把"版面理解"与"坐标关系"结合，归类会更聪明。剩下的，就是把这套骨架填进你自己的场景里。

如果你正打算在 HarmonyOS NEXT 上做一款带"扫一扫"能力的应用，希望这篇文章能帮你少走一点弯路。让镜头真正开始读懂世界，从把识别留在端侧这一步开始。

基于 HarmonyOS NEXT（API 12+）。