给照片点一个缺陷位置:鸿蒙 PC React Native 标注台
React Native OpenHarmony 框架仓 · 本文完整工程源码
前言
复核照片时,备注里只写“左边那颗焊点”,接手的人还得再找一遍。照片放进另一个大小的预览区,留白变了,旁边又多了一列清单,原先记录的窗口位置更没有多少帮助。这篇在鸿蒙 PC 上做一个小型照片标注台:点一下照片,给这个位置选分类,同时保留它相对于原图的坐标。
这份鸿蒙 PC 工程使用 React Native OpenHarmony。照片显示、原生点选、列表和弹层由 React Native 组件完成,坐标换算放在独立的 TypeScript 模型里。样图是一张本地电路板照片,分类用于演示复核流程,并不表示照片里存在真实缺陷,也没有自动识别模型。
界面参考了 Label Studio 关键点标注示例中“分类、图片、标记”的关系,做成适合单张照片复核的布局。大部分空间留给照片,旁边按编号列出记录。原图始终完整显示,空余地方保留深色底,便于看清哪部分属于照片。界面参考
同一张照片,先确定一种坐标
标注记录里保存两个从零到一的数,横向为 u,纵向为 v。原图左上角对应零,右下角对应一。窗口里的位置只用来接收点击和绘制圆点,不进入标注记录。这样,下一次布局改变时,可以从同一组 u、v 重新计算显示位置。
这里有一个容易遗漏的前提:图片控件的矩形,不一定就是照片实际占据的矩形。完整显示模式会等比例缩放照片,宽高比不合适时留下空白。假设画布是一千乘一千,照片是两千乘一千,照片实际只占中间五百高的区域。直接用点击纵坐标除以整个画布高度,会把上方留白也算进去,越靠近边缘,误差越明显。
项目先用画布与原图的宽高比算出缩放比例,取横向、纵向比例中较小的一个,再求居中的照片矩形。点击落在矩形以外就返回空结果,不把它强行夹到照片边缘。下面是工程中这三个换算函数的实现,类型 Box 包含 x、y、width、height 四个数值字段。
export interface Box {
x: number; y: number; width: number; height: number;
}
export function containBox(
width: number, height: number,
imageWidth: number, imageHeight: number
): Box {
if (![width, height, imageWidth, imageHeight]
.every(x => Number.isFinite(x) && x > 0)) {
return { x: 0, y: 0, width: 0, height: 0 };
}
const scale = Math.min(width / imageWidth, height / imageHeight);
const w = imageWidth * scale, h = imageHeight * scale;
return { x: (width - w) / 2, y: (height - h) / 2,
width: w, height: h };
}
export function normalizedPoint(
x: number, y: number, box: Box
): { u: number; v: number } | null {
if (box.width <= 0 || box.height <= 0 ||
!Number.isFinite(x) || !Number.isFinite(y)) return null;
if (x < box.x || y < box.y ||
x > box.x + box.width || y > box.y + box.height) return null;
return { u: (x - box.x) / box.width,
v: (y - box.y) / box.height };
}
export function screenPoint(u: number, v: number, box: Box) {
return { x: box.x + u * box.width, y: box.y + v * box.height };
}
点击事件使用 locationX、locationY,它们相对于接收事件的元素。这里让透明的 Pressable 覆盖整个画布,与画布尺寸对齐;图片和圆点不接收触摸。窗口左边距、标题栏、照片的内边距由不同层次处理,不能再混用整个屏幕的位置来计算。这一层的接口语义可查看 React Native 0.84 PressEvent,鸿蒙端行为则以本次原生点选和数据读回为准。

第一次打包,顺着这几个目录走
先把这份鸿蒙 PC React Native 工程下载到鸿蒙电脑。在鸿蒙版 DevEco 打开 harmony/,React 页面位于上一级的 App.tsx,坐标模型是 geometry.ts。宿主 EntryAbility 继承 RNAbility,页面 Index 使用 ResourceJSBundleProvider 加载包内资源。本次在本机 IDE 编辑了入口,增加启动日志;照片和业务 bundle 也都在本机打包生成。
| 环境 | 本次配置与实际版本 |
| 鸿蒙电脑 | HUAWEI MateBook 14,MNTXM-24B;aarch64;2880 × 1920 |
| 真机系统 | HarmonyOS 7.0.0;7.0.0.115(SP11C00E103R12P2patch02);API 26.0.0 |
| 本机 IDE | DevEco Studio 26.0.0.220 |
| 本机工具 | hmos-clt 1.0.0;SDK 26.0.0.105;Node 24.18.1;OHPM 6.0.1 |
| React / React Native | 19.2.3 / 0.84.1 |
| 鸿蒙适配与打包 | RNOH 0.84.4;Harmony CLI 0.84.4;Metro 0.83.8,由锁文件固定 |
| 模拟器设备 | MateBook Pro 2in1;x86_64;3120 × 2080;管理器配置 6.1.1(API 24) |
| 模拟器实际系统 | 关于本机显示 6.1.0;6.1.0.125(SP12DEVC00E47R1P3);API 24 |
| 工程目标 | 兼容 6.1.1(24);支持 2in1;本机生成 ARM64 与 x86_64 产物 |
| 实际安装包 | com.aasd23.rnphotomarkers;1.0.0(1000000) |




在本机终端先确认 CLT 的 Node、OHPM、Hvigor 已加入 PATH。为避免下载总仓库中的其他文章与媒体,本次用鸿蒙电脑的 Node 取回这个项目的同版公开源码归档,校验后解包。文首仓库链接仍可直接查看完整工程。第一次恢复依赖需要正常访问相应的软件源,公开目录不包含 node_modules 或已生成的业务包。
mkdir -p photo-marker-source
cd photo-marker-source
node --input-type=module <<'NODE'
import { writeFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
const url = 'https://hxapgc-media-20261112.oss-cn-beijing.aliyuncs.com/ugc-new5-20261118/react-native-photo-markers/react-native-photo-markers-public-source.tar.gz';
const response = await fetch(url);
if (!response.ok) throw new Error('HTTP ' + response.status);
const bytes = Buffer.from(await response.arrayBuffer());
const digest = createHash('sha256').update(bytes).digest('hex');
if (digest !== '939905f2f371345a6e0326d378f6b709999afed6b6e3c644e7130e6d98f1be47') {
throw new Error('源码归档校验不一致');
}
writeFileSync('source.tar.gz', bytes);
NODE
tar -xzf source.tar.gz
cd react-native-photo-markers
export DEVECO_SDK_HOME=/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/sdk
export PATH=/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/node/bin:/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/ohpm/bin:/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin:$PATH
sh build-native.sh
脚本依次执行依赖恢复、坐标模型测试、前端类型检查,再调用 bundle-harmony。生成的业务入口是 harmony/entry/src/main/resources/rawfile/bundle.harmony.js,照片进入同级的 assets 目录。接下来 OHPM 引用锁定 npm 包中的官方 RNOH HAR,Hvigor 与 CMake 在鸿蒙电脑生成两种架构的原生产物并组装 HAP。框架分支链接用于查适配工程,本次 npm 依赖的具体版本以锁文件为准,不能把分支最新提交直接当作已安装版本。
看到“Created bundle”还不能退出终端,原生编译与打包在它后面。这次首次完整双架构构建约八分钟,后续保持依赖与构建目录后可复用本机缓存。这个时间只是本次构建记录,并非对其他机器的性能承诺。业务前端、宿主和原生产物都没有借用其他操作系统提前编译。


在鸿蒙 PC 真机安装前,在本机 DevEco 的项目结构中,为当前包名与本设备自动生成调试签名,再重新构建。公开配置的 signingConfigs 为空,密钥、证书与口令不进入源码。签名后的产物位于 harmony/entry/build/default/outputs/default/entry-default-signed.hap,不上架的这个工程验收到安装并运行。
hdc list targets -v
hdc -t <目标设备> install harmony/entry/build/default/outputs/default/entry-default-signed.hap
hdc -t <目标设备> shell aa start -b com.aasd23.rnphotomarkers -a EntryAbility
hdc -t <目标设备> shell bm dump -n com.aasd23.rnphotomarkers
明确选择目标后,再核对装上的包名、版本和实际页面。本机生成的同版双架构包也安装到模拟器运行;仅检查压缩包里有两个 ABI 目录不算通过。前端模板元数据中的零零一与 HAP 的一零零分别记录,装机版本看 AppScope 与设备查询结果。
一处标记,在状态里只占一条记录
每条记录包含编号、分类、u 和 v。点击画布时先判断图像是否加载完成,再进行边界检查。有效点击才分配编号,用函数式状态更新追加记录;原图尺寸固定保存在图片描述中,当前选中项和是否显示圆点则是另外的界面状态。
编号不会根据列表的位置重新计算。演示中先创建一号和二号,移除二号后再添加,得到的是三号。一号仍然保留原来的坐标与分类。React 列表的 key 也使用这个编号,避免移除一条后,下一条复用了错误的行身份。
分类按钮还有一个操作上的分工:它先决定下一次新增使用的分类。复核已有标记时,选择条目、选择分类,再点击“应用到此处”才修改那条记录。这样准备新增一个焊点时,不会顺带把正在查看的旧标记也改成焊点。更新分类只替换对应记录的 kind,u、v 原样保留。
setMarkers(old => old.map(marker =>
marker.id === chosen.id ? { ...marker, kind } : marker
));
setMarkers(old => old.filter(marker => marker.id !== chosen.id));
隐藏按钮只控制叠加层是否绘制,清单与数据不清空。JSON 弹层直接展示当前记录,同时给出按原图尺寸换算的整数像素,方便复核者知道数据将怎样交给下一个环节。它是可选择的文本查看,不会自动写盘,也没有把“弹层能看到”描述成“文件已经导出成功”。
这一版只有单张本地照片和会话状态。需要保存到磁盘时,还应增加文件选择、保存失败处理、重新打开读回等步骤,不能直接把当前界面当作已经具备了这些能力。样图来源与使用条件留在工程 assets/CREDITS.md,演示分类不构成对照片内容的检测结论。
把复核分成位置、记录和操作三层
第一层检查数学模型。项目在鸿蒙电脑运行四项测试,分别覆盖两个方向的留白、留白拒绝与边缘值、不同画布尺寸之间的往返换算,以及尚未测量或非法尺寸的输入。它们验证的是模型计算,不代表鼠标能在设备上输入无限精度的位置。
第二层检查已经写入的记录。真机窄窗复测中,一号的 u、v 分别为 0.199653、0.298908;改变窗口后,JSON 中这两个数逐项不变。界面上的圆点则按新的照片矩形重新投影,位置依然指向同一块区域。模拟器也执行了这组检查。
第三层才是实际输入。通过原生点选检查位置时,要把坐标误差换算到物理像素。本次真机窄窗一次中点输入得到的 v 为 0.496940,与按截图整数边界算出的中点相差约两个物理像素。这里采用三个物理像素的核对容差,不把这类输入量化差异写成精密测量结果。存储坐标是否被缩窗改写,与新点击能精确到多少像素,是两个不同的验收口径。


| 实际操作 | 预期 | 真机与模拟器结果 |
| 在照片内点两个位置 | 两个独立编号及分类 | 两端通过,JSON 与圆点投影对应 |
| 点击深色留白 | 不增加边缘标记 | 两端均保留原两条记录并提示留白 |
| 改一号分类 | 坐标和另一条记录不变 | 两端逐项检查通过 |
| 隐藏再显示 | 同一批记录仍存在 | 两端数据未清空,圆点恢复 |
| 删除二号再新增 | 剩余一号,新建三号 | 两端编号与坐标正确 |
| 改窄窗口并继续点选 | 旧坐标不变,新输入用新矩形 | 两端通过,真机记录物理像素容差 |
| 窄窗滚动到清单删除 | 可选中、可移除指定编号 | 两端通过,其他编号与坐标保留 |
| 退出再打开 | 按本版约定清空会话 | 两端回到零条标注 |
这份鸿蒙 PC React Native 工程两端各通过十六项业务检查,窄窗的投影、新输入与清单操作另外复测。录制保留了添加分类、留白拒绝、修改分类、隐藏恢复、删除后新增与查看 JSON 的过程,宽窄窗对照用截图说明。画面不是用反复拖边框来代替标注功能。


复核笔记与 FAQ
照片明明用了 contain,为什么第一版的标记仍然对不上? 首次设备截图暴露出图片沿用了本地资源的固有尺寸。单独设置完整显示方式,并不会替代图片控件自己的尺寸约束。修订后明确让 Image 的宽高填满画布容器,再用同一组 contain 矩形计算触摸位置和圆点投影。复测既看完整照片是否出现,也把点击后的 JSON 与圆点实际位置对照,不只检查属性名称。
前端类型检查和鸿蒙构建为什么要分开? 初次检查把 harmony 下的 Hvigor 配置也纳入普通 TypeScript 项目,产生了构建插件模块找不到的报错。现在前端检查范围排除宿主目录,鸿蒙配置交给自己的工具链处理。另一个真实报错是把 pointerEvents 直接放到 Image 上,当前类型声明不接受;改在外层 View 设置触摸屏蔽后通过检查。它们发生在不同层次,不能用跳过所有检查来一起解决。
照片坐标也有明确适用边界。当前样图已知宽高,使用完整显示,不涉及旋转、裁剪或镜像。如果以后加入这些显示变换,必须同步调整坐标转换;仅把新的显示效果放上去,原来的逆变换不会自动变正确。当前输入适合复核位置,不承担亚像素测量或自动判断缺陷的任务。
总结
这次的记录单位是一处原图位置:窗口可以换尺寸,分类可以修改,某个编号可以删除,其他记录仍然保留原来的身份与坐标。把图像矩形、归一化数据和显示投影分开以后,宽窗与窄窗的检查也有了可以逐项核对的依据。
这份 React Native 工程在鸿蒙 PC 上完成了依赖恢复、业务打包、双架构原生编译、调试签名与安装。下一步若要接真实巡检照片,应先补齐导入、保存与读回,再考虑标记数量较多时的清单性能;这些都是后续工作,不能从当前会话演示中直接推定已经具备。
更多推荐
所有评论(0)