1. 折叠屏上那张"跑偏"的标注框，问题到底出在哪
先说结论：图片标注功能在折叠屏上出问题，十有八九不是手势坐标算错了，而是你拿到的坐标属于哪一套坐标系，和你回映时用的那套坐标系，根本不是同一个。我第一次接到这类需求时也以为是手势库的精度问题，花了整整两天在手指触摸的偏移量上打转，最后发现问题出在一行 Image 组件的 fit 属性上——改动一个字，标注框该在哪就在哪了。
这个题目要解决的核心问题可以拆成三件事：第一，用户在图片上画框，手指落点必须被换算成图片自身内容的归一化坐标（0 到 1 之间），这样才与屏幕尺寸、折叠状态、窗口大小彻底解耦；第二，图片在容器里必然要经过一次缩放和裁切才能铺满指定区域，这个变换过程由 Stack 的层叠布局配合 ImageFit 的填充策略共同决定，你得把这套变换算清楚；第三，当你把这批归一化坐标存下来、传给后端或换一台设备显示时，还要能准确"回映"到新的显示区域上，做到折起来画、展开看、换个屏幕还是严丝合缝。
适合谁看？正在做鸿蒙应用里图片查看器、证件拍摄、医疗影像标记、装修量房、在线教育批注这类功能的朋友，只要你的页面里同时出现了"一张图 + 一堆覆盖物"，这篇内容都用得上。完全没接触过 ArkUI 的新手也能看，我会把每个换算写得足够笨，能代入数字算一遍；有经验的可以直接跳到坐标映射的推导和折叠态切换那一节。
需要提前说明的是，项目中并没有给出具体的代码和页面结构，下面涉及的组件用法、布局思路和参数取值，都是基于 ArkUI 常见能力与我在实际项目中的通用做法补全的，我会在关键处标注哪些属于"常规可以这样写"的落地方案，你按自己工程的实际情况微调即可。
2. 为什么偏偏是折叠屏把问题放大了
2.1 普通手机上"碰巧对"的假象
单屏设备上做标注，很多人是这么写的：Stack 里放 Image 铺满父容器，Image 的 fit 设成 Cover，上面叠一层可以画矩形的画布。手指点下去，直接拿事件里的 localX / localY 存起来，画框也直接用这套坐标画。在某一台固定尺寸的手机上跑，看着完全正确，于是就这么上线了。
这个"正确"其实是个巧合。因为你存下来的坐标是屏幕像素坐标，画框用的也是屏幕像素坐标，两边口径一致，自然对得上。一旦图片换了个尺寸、容器换了个比例，这个平衡立刻就被打破——图片在 Cover 模式下被裁掉了左右两条边或者上下两条边，而你的坐标还是基于完整容器的，标注框看起来就"飘"到了图片外面。
这个坑最阴险的地方在于：它不会在开发机上暴露。你在固定尺寸的模拟器里反复测试都是好的，直到用户把手机横过来，或者把应用拖进分屏，问题才第一次出现。
2.2 折叠态切换撕开的三个口子
折叠屏把这套隐患一次撕开三个口子。第一个是宽高比剧烈变化：展开态接近方形，折叠态细长，同一张竖构图照片在两种状态下的裁切方向可能完全不同，展开时裁的是上下，折叠时裁的是左右。第二个是运行时的持续变化：分屏、悬浮窗、折叠悬停、横竖屏旋转，容器尺寸会频繁地重新测量和布局，如果你的标注坐标绑定的是旧尺寸，重新布局后就全部失效。第三个是数据要跨形态存活：用户在折叠态画了三个框，展开后这三个框必须还在正确位置，否则这个功能就是不可用的。
所以真正的解法只剩一条路——把坐标从"屏幕像素"这种易变的东西，升级成"相对于图片内容的比例"。比例是与尺寸无关的量，1 米对应 100 厘米，不管尺子多长都是这个比例。这就是归一化坐标存在的全部理由，它不是什么架构洁癖，而是折叠屏场景下的唯一活路。
2.3 ImageFit 的不同取值，决定了坐标要不要反向补偿
把 Image 塞进一个固定宽高比的容器，必然要做一个取舍：是让图片完整显示但留白，还是铺满容器但裁切。ArkUI 的 ImageFit 提供了多种策略，标注场景下最常用的几种，它们的坐标处理方式截然不同，必须先分清楚。
| ImageFit 取值 | 显示效果 | 图片内容区与容器区的关系 | 标注坐标的补偿需求 |
|---|---|---|---|
| Contain | 完整显示，可能留白 | 内容区小于等于容器区 | 需要减去偏移量，再按缩放比换算 |
| Cover | 铺满容器，可能裁切 | 内容区大于等于容器区 | 需要加上被裁掉的偏移量再换算 |
| Fill | 拉伸铺满，比例失真 | 内容区等于容器区 | 直接按容器尺寸换算，但圆形会变形 |
| None | 原始像素尺寸居中 | 内容区等于原图尺寸 | 按原图像素换算，与容器无关 |
| ScaleDown | 取 Contain 与 None 的较小者 | 视情况而定 | 两种逻辑都要兼容 |
这张表是整个功能的地基。我见过不少实现直接默认 Cover，然后发现 Contain 模式下的标注全偏了，回头补一个 if 判断，代码里到处是魔法数字。正确的做法是先明确你的产品到底要哪种显示策略，然后只针对这一种策略写一套干净的换算函数，其他策略要么不支持，要么单独封装，绝不在同一段代码里混着判断。
3. Stack 的层叠关系，先摆正再谈计算
3.1 覆盖层必须和图片严格同框
Stack 是个层叠容器，子组件默认从中心对齐、按顺序从下往上堆。标注功能的标准结构是：Image 在下，画布或覆盖层在上，两者尺寸必须完全一致。这一点听起来简单，实际工程里出错率极高，因为很多人会给覆盖层加 padding、圆角、边框，或者让覆盖层自己去撑满父容器，结果覆盖层和 Image 的边界错开了几个像素，画出来的框就整体偏移。
我在实际项目里会强制要求覆盖层和 Image 使用同一个宽高来源——通常是把两者都设成父容器的 100% 宽高，并且明确标注覆盖层不允许设置任何内边距和位移。如果视觉上确实需要圆角和边框，加在 Stack 的外层容器上，让 Stack 整体被裁切，而不是加在任何一个子层上。这个规矩一旦定下来，后面所有的坐标换算才能有一个唯一的、可信的参照系。
3.2 容器尺寸要在布局完成后拿，不要在构建时拿
另一个高频坑是尺寸获取时机。ArkUI 的布局是异步的，组件构建完成的那一刻，它实际渲染出来的宽高往往还是 0 或者上一轮的旧值。如果你在 aboutToAppear 里去读容器尺寸来算缩放比，几乎必然拿到错误数据。
我自己的做法是通过 onAreaChange 回调持续监听容器区域的变化，把最新的宽高存进状态变量里，坐标换算全部基于这个状态值。这个回调的好处是它能覆盖折叠态切换、分屏拖拽、横竖屏旋转等所有会引起尺寸变化的场景，等于给你提供了一个统一的"尺寸变更锚点"。需要注意的是，这个回调触发时状态变量更新会引发重新渲染，所以不要在回调里做重量级计算，只存尺寸，换算放在使用时做，或者用派生状态算。
3.3 手势坐标到底属于谁
这是最容易被忽略的一环。在覆盖层上绑手势，事件回调里给的坐标通常是相对于触发手势的那个组件的局部坐标；如果你把坐标系搞混，把父组件的坐标当成子组件的，或者反过来，就会出现一个稳定的偏移量。判断方法很简单：在容器的左上角点一下，看回调给的坐标是不是接近 0,0。如果接近但差了几十像素，那就是层级搞错了。
我习惯在开发阶段临时开一个坐标调试模式，把触摸点的原始坐标、换算前的容器尺寸、换算后的归一化坐标同时显示在页面上，画框的边缘再画一条细线。这个土办法能省掉大量猜测时间——因为你能直接看到偏移是在哪一步产生的，而不是在最终结果上瞎猜。
4. 归一化坐标的推导：把四个量算明白
这一节是整套方案的核心。我把它拆成四个量：容器宽高、图片原始宽高、显示缩放比、显示偏移量。这四个量算清楚，任何 fit 策略都能推导出正确的换算公式。
先定义符号。容器宽高是 CW 和 CH，来自 onAreaChange 监听到的实际渲染尺寸；图片原始宽高是 IW 和 IH，来自图片加载完成后回调里拿到的 intrinsicSize；归一化坐标记作 nx 和 ny，取值 0 到 1，其中 0,0 表示图片内容的左上角，1,1 表示图片内容的右下角。
在 Contain 模式下，图片要完整显示，缩放比取容器与图片在两个方向上的比例中较小的那个：
scale = min(CW / IW, CH / IH)由此得到图片内容实际占据的显示尺寸 DW = IW × scale，DH = IH × scale。因为内容区小于容器区，所以居中显示产生了偏移：
offsetX = (CW - DW) / 2 offsetY = (CH - DH) / 2反过来，把触摸点 tx、ty 换算成归一化坐标：
nx = (tx - offsetX) / DW ny = (ty - offsetY) / DH在 Cover 模式下，图片要铺满容器，缩放比取较大的那个：
scale = max(CW / IW, CH / IH)此时 DW 和 DH 中有一个会大于容器尺寸，偏移量是负值：
offsetX = (CW - DW) / 2 // 负数 offsetY = (CH - DH) / 2 // 负数但公式本身不用改，nx = (tx - offsetX) / DW 依然成立，因为负偏移会自然地把超出部分抵消掉。这就是我建议把两种模式统一成一套公式的原因——只改变 scale 的取法，其余推导完全一致，代码里只有一个三元表达式不同，不容易出错。
回映是同一套公式的逆运算。给你一个归一化坐标和一个新的容器尺寸，先按新容器重新算 scale、DW、DH、offsetX、offsetY，再反算屏幕坐标：
tx = nx * DW + offsetX ty = ny * DH + offsetY举个例子验证一下。假设一张 4000×3000 的横图，放进折叠态下 360×780 的容器，Contain 模式。scale = min(360/4000, 780/3000) = min(0.09, 0.26) = 0.09。DW = 360，DH = 270。offsetX = 0，offsetY = (780 - 270) / 2 = 255。用户在屏幕 (180, 390) 处点击，nx = (180 - 0) / 360 = 0.5，ny = (390 - 255) / 270 = 0.5，正好是图片中心。换成展开态 700×700 的容器，scale = min(700/4000, 700/3000) = min(0.175, 0.2333) = 0.175，DW = 700，DH = 525，offsetX = 0，offsetY = 87.5。回映 tx = 0.5 × 700 + 0 = 350，ty = 0.5 × 525 + 87.5 = 350。在新容器里依然是正中心。手推一遍你就知道这套公式是闭环的。
5. 一个矩形标注的完整生命周期
5.1 落指、拖动、抬手：三个状态要分清
画一个矩形标注，需要记录四个点：起点、当前点、以及由这两个点推出来的左上角和宽高。手势回调里，按下时记录起点并置为绘制中，移动时更新当前点并实时重绘预览框，抬起时固化结果并生成一条标注数据。
这里有个细节值得单独说：预览框和已提交框必须用同一套绘制逻辑。我见过为了实现简单，预览阶段直接用屏幕坐标画，提交时才转成归一化的做法，结果预览框位置和最终框位置有细微差别，用户一眼就能看出来。正确做法是在按下那一刻就把起点转成归一化坐标，整个拖动过程都在归一化空间里计算，绘制时再统一回映到屏幕。虽然多一次换算，但显示和存储永远是同一份数据，不会有"看起来对，存下来错"的情况。
另外，换算时要对结果做范围钳制。手指可能拖到图片内容区之外（Contain 模式下的留白区），此时归一化坐标会小于 0 或大于 1，必须裁到 0 到 1 之间。否则你会得到一个超出图片范围的框，回映到另一个容器上时直接跑到屏幕外。
5.2 数据结构：存比例，不存像素
一条矩形的数据我一般这么设计：
interface MarkRect { id: string; x: number; // 左上角，归一化，0~1 y: number; // 左上角，归一化，0~1 w: number; // 宽度，归一化，0~1 h: number; // 高度，归一化，0~1 label?: string; createdAt: number; }关键点是宽高也必须是归一化的，而不是像素。因为图片缩放时，框的像素宽度会跟着变，但占图片的比例不变。存储时只用这四个比例值，加上标注内容，就足够在任意尺寸的设备上完美还原，存数据库、传接口、跨端同步都是安全的。
如果后端要求传像素坐标，那就在上传前的一刻用原始图片尺寸换算一次：像素 x = nx × IW，像素 y = ny × IH。注意这里用的是原图尺寸而不是显示尺寸，这样后端拿到的就是与图片本身对齐的坐标，跟你在什么设备上画的完全没有关系。这个约定一定要在接口文档里写清楚，我踩过一次因为前后端对坐标基准理解不同而返工三天的坑。
5.3 撤回与编辑，要靠归一化坐标撑住
标注功能上线后一定会被要求加撤回、删除、拖动调整。这几项功能在归一化坐标体系下都很轻：撤回只需要维护一个数组栈；删除按键命中检测时，把每条标注回映成屏幕坐标，再判断触点是否落在矩形内；拖动调整时，把拖动位移除以当前的 DW 和 DH，得到归一化增量，加到原坐标上即可。
如果你的坐标是屏幕像素，那么任何一次折叠态切换都会让所有已存数据失效，撤回和编辑就无从谈起。这也是我一直强调"在最早的版本就把归一化做对"的原因——后面加功能的时候，这个选择会持续给你回报。
6. 折叠态切换：让标注跟着画面一起变形
6.1 尺寸变更不重建，只重算
折叠屏最典型的交互是用户在折叠态标注、展开态查看。理想的行为是：尺寸一变，所有标注框自动重新计算位置和大小，视觉上看起来像是跟着图片一起放大了。实现方式就是在 onAreaChange 里更新容器尺寸状态，而在渲染每个标注时，实时用当前容器尺寸回映，而不是在数据里缓存屏幕坐标。
这么做的性能代价几乎可以忽略，因为回映只是几次乘除法；但它带来的正确性收益是巨大的——你永远不用担心数据过期。我做过一次压力测试，一百个标注框、拖拽过程中每帧重算，实测在主流设备上毫无压力，瓶颈根本不在这里。
6.2 悬停态下的特殊处理
折叠屏悬停时，屏幕会分成两半，上半部分显示内容，下半部分可能是操作区。这时候标注页面的容器高度可能只剩下全屏的一半多一点。如果还是用一个 Stack 撑满，图片会被压得很扁，用户体验很差。
我的建议是给容器设一个最小显示高度的下限，低于这个阈值时把布局从"图片铺满 + 覆盖标注"切换成"图片按比例自适应 + 标注区域在下方列表显示"。这是一个产品层面的降级策略，需要在设计阶段就确认，否则等到开发完发现悬停态不可用，改起来会牵一发而动全身。
6.3 一个容易被忘掉的地方：图片加载时序
折叠态切换会触发重新布局，但图片本身通常不需要重新加载（同一个资源会被缓存）。问题出在首次进入页面时：图片还没加载完，intrinsicSize 还是 0，此时算 scale 会得到无穷大或 0，标注全乱。
处理办法是给图片加载完成加一个状态标记，加载完成前把覆盖层设为不可交互或者直接隐藏，加载完成回调里拿到真实尺寸后再开启标注。这个门控看起来是个小细节，但它是"偶现标注全堆在左上角"这类 bug 的常见来源。
7. 那些我真实踩过的坑与验证方法
7.1 边界钳制的顺序不能错
先钳制再算宽高，和先算宽高再钳制，结果完全不同。如果你先算出起点和终点的归一化坐标再钳制，当手指拖出边界时，框的宽高可能算出 0 甚至负数。正确顺序是先把两个端点的坐标分别钳制到 0 到 1，然后从钳制后的端点推导左上角和宽高，保证 w 和 h 恒为正。
7.2 别用百分比布局去对齐标注层
有人会想，既然坐标都是 0 到 1，那我直接把标注框的 left 和 top 写成百分比不就完了？在 Stack 里确实可以用百分比定位，但百分比是基于父容器的，而我们的归一化坐标是基于图片内容区的。在 Contain 模式下两者不等价，会稳定地偏出偏移量那一段距离。这个坑很隐蔽，因为 Cover 模式下（无留白时）百分比是恰好对的，换一张图、换一个屏幕比例立刻就错。
7.3 我的验证清单
每次改完坐标相关逻辑，我会跑这几项，缺一不可：
- 四角打点：在图片四个角点一下，归一化值应接近 (0,0)、(1,0)、(0,1)、(1,1)，误差在一个像素对应比例以内。
- 中心打点：图片正中点击，应接近 (0.5, 0.5)。
- 往返一致性：写一个调试按钮，把存下来的归一化坐标立即回映并覆盖在原图上，视觉偏移肉眼不可见。
- 跨形态比对：在折叠态画框，展开后截图，再用第三方工具量一下框相对图片的比例，与折叠态一致才算通过。
- 旋转与分屏：横竖屏各跑一遍，进出分屏各跑一遍，确认无漂移。
7.4 关于浮点误差的一点经验
归一化坐标是浮点数，多次往返换算会产生极小的误差，单次完全无感，但如果你的编辑功能是"拖动后再存回去"，反复拖十几次，框的尺寸可能出现肉眼可见的细微变化。我的做法是在提交时对归一化值保留四位小数，既保证精度（对一张 4000 像素宽的图，四位小数对应 0.4 像素，远小于显示精度），又能把累积误差掐死。
做这类事情多了，我最大的体会是：坐标系的清晰度决定了功能的寿命。同一套功能，用屏幕像素写，第一个版本能跑，第二个需求就要推倒；用归一化写，第一次多花半天理清公式，后面加功能、换形态、接后端都是顺水推舟。上面这些公式你可以直接抄过去用，但我更建议你拿张纸把 Contain 和 Cover 两种情况的偏移量各画一遍，手推一次之后，这套东西就真正变成你自己的了。
