Demo：HingePopoverLab
页面：ProductBoardPage
任务 ID：hinge_20261001_20

商品看板在普通直板机上一直正常：点卡片右上角的“更多”，Popover 就贴着按钮出现。换到一台处于半折叠姿态的设备后，问题变得很怪——菜单视觉上已经被挪到右侧安全区，但点“置顶”时，命中的却是原来位置下面的卡片。连续折叠、展开几次，偶尔还会有菜单一半压在铰链区里。

这不是响应式布局少写一个断点。窗口宽度仍是 860 vp，铰链占据 x=421..439 vp，真正变化的是可交互区域从一个连续矩形变成了两个安全区域。布局、浮层和触控如果各自保存一份坐标，就会在某次姿态切换后互相错开。HingePopoverLab 最终记录到 18 次锚点重算，越界浮层从 9 次降为 0，误触从 7 次降为 0，重算耗时 P95 为 7.8 ms。

一、先把“窗口够宽”这个判断删掉

旧代码只有一条规则：宽度超过 720 vp 就切双栏，Popover 优先放在锚点右下方。它把 860 vp 当成一整块画布，因此 product_p12 的更多按钮在铰链左边时，菜单仍可能跨过 421 vp；后来补的 clamp() 只保证不出窗口，却不知道中间还有一个不可用区域。

我先把一次失败过程完整记下来。设备从 EXPANDED 进入 HALF_FOLDED，Window Kit 的窗口变化回调先到，ArkUI 下一帧才完成网格重排。此时如果立刻读取按钮位置，拿到的还是上一代布局坐标；Popover 按旧锚点计算，随后网格移动，浮层却没有再次刷新。更糟的是触控层保存了第一次打开时的热区，视觉位置和命中区域从这一刻开始分家。

因此状态不能只写成“已折叠”。Demo 使用 EXPANDED → HALF_FOLDED → RELOCATING → LAYOUT_STABLE：窗口或姿态变化只更新几何输入并增加 generation；等 ArkUI 完成本轮布局，再用同一 generation 重新测量锚点、放置浮层、发布热区。任何迟到的测量结果都会被丢弃。

二、把铰链转换成两个可计算的安全区域

当前要解决的问题，是把窗口矩形与铰链排除矩形转换成 Popover 引擎能使用的安全区域，而不是让每个组件自己判断“在左边还是右边”。Demo 只处理竖向铰链，但把算法写成纯数据函数，方便单元测试。

export interface RectVp {
  x: number
  y: number
  width: number
  height: number
}

export class SafeRegionSplitter {
  static split(windowRect: RectVp, hinge: RectVp): RectVp[] {
    const leftWidth = Math.max(0, hinge.x - windowRect.x)
    const rightX = hinge.x + hinge.width
    const rightWidth = Math.max(0, windowRect.x + windowRect.width - rightX)
    return [
      { x: windowRect.x, y: windowRect.y, width: leftWidth, height: windowRect.height },
      { x: rightX, y: windowRect.y, width: rightWidth, height: windowRect.height }
    ].filter((region: RectVp) => region.width > 0)
  }
}

const regions = SafeRegionSplitter.split(
  { x: 0, y: 0, width: 860, height: 720 },
  { x: 421, y: 0, width: 18, height: 720 }
)

输入数据来自窗口几何提供器，本文把设备差异封装在 FoldGeometryProvider 中，页面只接收 vp 坐标。输出是 [0..421) 与 [439..860) 两个矩形，铰链宽度 18 vp 不再属于任一安全区域。这样写的好处是 Popover、拖拽提示线和触控校正共享同一事实来源；不会出现 UI 认定 18 vp、事件层却按 16 vp 避让的情况。

这个方法在窗口信息或折叠姿态变化时执行，但不直接操作 UI。正式项目必须处理无铰链信息、横向铰链、窗口缩放和单位换算；设备不支持折叠能力时，provider 应退化成单一窗口矩形，而不是让业务捕获“不支持”异常。监听器由页面级控制器注册，在 aboutToDisappear() 解除，避免退出页面后仍触发重排。

三、锚点重算不能只选“最近的位置”

当前要解决的问题，是给 product_p12 的 Popover 选择一个既不越窗、也不穿越铰链的落点。单纯取距离最近的候选，会让菜单紧贴铰链，箭头也可能指向错误方向。我给四个候选位置评分：越过安全区直接淘汰，遮挡锚点重罚，移动距离和边缘余量参与排序。

export interface Placement {
  rect: RectVp
  side: 'left' | 'right' | 'top' | 'bottom'
  score: number
}

export class PopoverPlacementEngine {
  static place(anchor: RectVp, popup: RectVp, regions: RectVp[]): Placement {
    const candidates = this.buildCandidates(anchor, popup)
    const valid = candidates.filter((item: Placement) =>
      regions.some((safe: RectVp) => this.contains(safe, item.rect)))
    if (valid.length === 0) throw new Error('no safe placement')
    return valid.sort((a: Placement, b: Placement) => b.score - a.score)[0]
  }

  private static contains(outer: RectVp, inner: RectVp): boolean {
    return inner.x >= outer.x && inner.y >= outer.y &&
      inner.x + inner.width <= outer.x + outer.width &&
      inner.y + inner.height <= outer.y + outer.height
  }
}

place() 在 ArkUI 完成本轮布局并返回新锚点后执行。状态先进入 RELOCATING，拿到结果后再更新 Popover 的偏移量与箭头方向，最后进入 LAYOUT_STABLE。如果四个候选都放不下，Demo 不做危险的强行裁剪，而是关闭气泡并改用当前安全区域内的底部操作条；这条降级路径比显示一个无法完整点击的菜单更可靠。

实际项目里 buildCandidates() 还要考虑文本放大、RTL、系统栏和圆角避让。候选评分必须是纯函数，不能一边打分一边改 UI，否则同一帧的多次测量会造成抖动。本文的浮层尺寸在打开时固定，内容异步变化后会主动发起新 generation；禁止复用旧尺寸，可以避免菜单加载第二行文字后再次压到铰链。

四、误触的根源是热区仍活在上一代坐标里

当前要解决的问题，是视觉浮层移动以后，让事件命中区域与最新布局同步。这里没有在事件回调里临时加减 18 vp，因为锚点可能在任一安全区，而且窗口还可能缩放。热区发布时就带上 generation，事件只认当前版本。

export interface HitTarget {
  id: string
  rect: RectVp
  generation: number
}

export class HitTargetRegistry {
  private targets: HitTarget[] = []
  private generation: number = 0

  publish(generation: number, targets: HitTarget[]): void {
    if (generation < this.generation) return
    this.generation = generation
    this.targets = targets.filter((item: HitTarget) => item.generation === generation)
  }

  hit(x: number, y: number): HitTarget | undefined {
    return this.targets.find((item: HitTarget) =>
      x >= item.rect.x && x <= item.rect.x + item.rect.width &&
      y >= item.rect.y && y <= item.rect.y + item.rect.height)
  }

  clear(): void { this.targets = [] }
}

当 Popover 新位置确认后，菜单项矩形统一换算成窗口 vp 坐标，再由 publish() 一次替换。迟到的上一代测量即使完成，也因为 generation 较小而被忽略。触控事件只做查询，不再猜测偏移量。7 次误触正是这样降到 0：修复前点击视觉上的“置顶”会命中旧位置的 product_p11；修复后命中的是当前 generation 下的 pin_product_p12。

clear() 在浮层关闭和页面消失时执行，防止透明区域继续吃事件。这里还要防重复注册：打开同一个 Popover 不新增第二组监听，而是更新现有 registry。正式产品若使用系统浮层或独立子窗口，应由对应窗口坐标系做转换；本文 Demo 的 registry 属于主窗口，不能直接拿去处理跨窗口触控。

五、DevEco Studio 里真正有用的是四行日志

调试早期我打印了每次 pointer move，HiLog 一秒滚几百行，反而看不到姿态切换的边界。最后只保留每一代布局的审计摘要：窗口宽度、铰链范围、锚点 ID、重算次数、越界与误触计数、P95 和终态。

task=hinge_20261001_20 width=860vp hinge=421..439vp
anchor=product_p12 relocations=18
offscreen=9->0 misTaps=7->0 p95=7.8ms
state=LAYOUT_STABLE

截图里左侧工程目录特意把 geometry、overlay 和 input 分开。它们共享 RectVp，却不共享可变状态；状态收敛由 HingeLayoutCoordinator 完成。这样排查时能判断问题发生在几何来源、候选放置还是事件发布，而不是在页面组件里搜索几十处 offset。

18 次重算来自固定回放脚本，不是用户一次折叠触发 18 次。脚本包含展开、半折、窗口缩放、字体放大和连续快速切换。P95 7.8 ms 测的是从接收新几何到发布新热区，不包含系统完成物理姿态切换的时间。这个口径必须写清，否则“适配耗时”很容易被误读成设备动画性能。

六、运行页要把铰链画成不能忽略的边界

最终运行页是商品看板，不是专门做出来的参数面板。左侧列表与右侧详情之间保留 18 vp 的铰链避让带，product_p12 的 Popover 完整落在右侧安全区；页面底部再显示本次回放的关键结果。状态栏时间为 20:47，5G、Wi-Fi、信号和 76% 电量均完整保留，画面本身就是 9:16 屏幕内容，没有手机外壳。

红色细箭头只标出“新锚点”与 18 vp 铰链区，帮助读者理解菜单为什么没有贴着原按钮机械移动。正文与图里都使用 product_p12、421..439 vp、18 次重算和 LAYOUT_STABLE，避免演示图变成另一个虚构 Demo。

还有一个产品判断值得保留：半折叠时不是所有浮层都应该跨区迁移。与锚点强关联、内容很短的 Popover 应优先留在锚点所在安全区；承载多项设置的长菜单如果放不下，降级成区域内底部操作条；需要跨两区阅读的内容则不适合继续使用 Popover。组件选择本身也是避让策略的一部分。

我随后把字体缩放调到 1.3 倍，又开启读屏复查了一遍。字体变大后，菜单高度会变化，必须触发新的 generation；如果只改视觉尺寸、不重新发布热区，最后一项会出现“看得到、点不到”。读屏焦点则不应因为重新定位而回到页面顶部。HingeLayoutCoordinator 因此保留当前 actionId，等 LAYOUT_STABLE 后把焦点恢复到同一个语义节点，而不是记住旧坐标。坐标会变，语义身份不应该跟着变。

这一步也暴露了 vp 与像素混用的问题。窗口几何、锚点测量和热区计算在算法层统一使用 vp，只有接收底层原始事件时做一次像素到 vp 的转换；转换所需的密度值跟随当前窗口快照进入 generation。若在不同类里各自换算，窗口跨屏或显示密度变化后就可能出现一两个像素的缝隙，视觉上看不见，边缘点击却会漏掉。

生命周期测试采用了比人工折叠更苛刻的顺序：打开 Popover，立刻切半折叠，在 RELOCATING 阶段把应用切到后台，再从最近任务返回。页面不可见时只更新最新几何快照，不发布 UI；恢复后重新测量锚点并生成新一代热区。旧回调即使随后到达，也因 generation 过期被丢弃。这样不会在后台偷偷创建浮层，也不会把返回后的新页面状态覆盖掉。

资源释放同样需要可观测。我给 coordinator 增加活跃监听计数，页面进入时应为 1，重复显示不能涨到 2，离开后必须回到 0。Popover 关闭后 registry 的 target 数也必须是 0。很多“折叠几次才出现”的问题并非算法算错，而是旧监听仍在用过期几何发布结果；把监听数量放进调试断言，比在屏幕上盯着偶发抖动更容易定位。

这些补充没有改变 offscreen=9->0 和 misTaps=7->0 的最终数字，却让它们能覆盖字体、读屏、前后台和密度变化，而不是只对某一台设备的某一次姿态有效。工程适配的价值就在这里：把一次看似偶然的菜单错位，收敛为可重放的输入、可比较的状态和可释放的资源。

七、适配结束的标准不是“看起来没压住”

这次修复后，我把验收条件定成五条：任意浮层矩形不得与铰链相交；视觉菜单项与命中热区必须属于同一 generation；快速折叠时迟到结果不能覆盖新布局；页面退出后监听和热区都释放；没有折叠能力的设备稳定退化成单区域算法。

它和常见的单双栏适配不是同一件事。单双栏解决内容如何重排，这篇处理的是不连续可交互空间里，临时浮层如何跟住锚点、事件如何跟住浮层。窗口宽度只回答“有多大”，铰链排除区才回答“哪里真的能用”。当几何、浮层和触控都共享同一代数据，LAYOUT_STABLE 才不只是一个 UI 状态，而是能够被日志、回放和用户点击共同验证的工程终态。

在后续迭代里，这组回放用例也会作为组件升级前的固定门槛，防止一次样式调整悄悄破坏命中区域。

参考资料：

• HarmonyOS 多设备自适应应用
• 折叠屏体验设计原则
• HarmonyOS 子窗口开发指导