HarmonyOS 7.0 API 26 鸿蒙电脑跨屏拖窗坐标错乱：windowRectChange 与 globalDisplayRect 实战

窗口从笔记本内屏拖到外接显示器后，最容易出现两种问题：菜单仍弹在原来的屏幕上，或者应用重启后窗口只剩一条边露在屏幕外。它们看起来像弹窗组件或持久化出了问题，实际根因通常是同一段代码混用了三套坐标：窗口内坐标、当前显示器坐标和以主屏左上角为原点的全局显示坐标。

这次不做泛泛的能力判断，而是把问题完整跑一遍：怎样复现，应该监听哪个事件，为什么事件顺序不能当成固定顺序，怎样把窗口位置保存为稳定数据，以及断开外接屏后如何保证窗口还能被找回来。

版本和官方能力边界

本文按 HarmonyOS 7.0、API 26 工程环境编写。需要先说明：`rectChangeInGlobalDisplay`、`clientToGlobalDisplay` 和 `globalDisplayToClient` 并不是到 API 26 才出现，它们的接口声明从 API 20 起提供；这里讨论的是这些能力在 API 26 鸿蒙电脑多显示器场景里的组合用法。

华为开发者文档在 2026-09-09 更新的[窗口布局](https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/window-layout)说明了三个关键事实：

• `windowRect` 的位置相对于当前屏幕，单位为 px；
• `globalDisplayRect` 相对于全局显示坐标系，单位同样为 px；
• `rectChangeInGlobalDisplay` 会返回全局坐标下的窗口矩形和变化原因。

[窗口模式](https://developer.huawei.com/consumer/cn/doc/doccenter-multi-device/bpta-multi-device-window-mode)还给出一个很重要的工程建议：尺寸、位置、避让区和屏幕切换应该分别监听，各回调只处理自己拿到的数据；布局相关回调里不要做文件写入、网络请求等耗时操作。

先把三套坐标分清

坐标或属性	原点	适合做什么	常见误用
组件/窗口内坐标	当前窗口内容区左上角	点击位置、组件锚点、窗口内布局	直接拿去定位另一块屏幕上的窗口
`windowRect`	当前显示器左上角	当前屏内的位置与大小判断	跨屏后继续当成全局坐标保存
`globalDisplayRect`	主显示器左上角形成的全局坐标系	跨屏拖拽、位置持久化、恢复窗口	未判断可选值就直接使用
`drawableRect`	窗口左上角	内容可绘制区域	当成整个窗口的外框尺寸

最危险的代码不是明显报错，而是下面这种“看起来能用”：

const rect = mainWindow.getWindowProperties().windowRect
saveLastPosition(rect.left, rect.top)

窗口一直在主屏时它通常没问题。一旦窗口进入副屏，`left/top` 的参照系发生变化，保存的数据却没有标记参照系。下次恢复时再把它交给全局移动接口，窗口就会偏移一个显示器的宽度。

案例一：跨屏拖动后，弹窗为什么留在旧屏

复现步骤

1. 主屏分辨率设为 2560×1440，右侧外接屏设为 3840×2160。

2. 应用窗口先放在主屏，点击工具栏按钮，确认弹窗锚点正常。

3. 把窗口拖到外接屏，不关闭页面，再次点击同一个按钮。

4. 如果弹窗仍按旧的 `windowRect.left + buttonX` 计算，它可能出现在主屏右边缘，甚至完全不可见。

问题不是按钮坐标错了，而是“窗口内坐标 + 当前屏坐标”不能稳定表示跨屏位置。API 20 及以上可以直接使用窗口对象提供的坐标转换，不需要自己猜显示器偏移量。

import { window } from '@kit.ArkUI'
import { BusinessError } from '@kit.BasicServicesKit'

interface PointPx {
  x: number
  y: number
}

export function anchorToGlobal(
  mainWindow: window.Window,
  localX: number,
  localY: number
): PointPx {
  try {
    const point = mainWindow.clientToGlobalDisplay(
      Math.floor(localX),
      Math.floor(localY)
    )
    return { x: point.x, y: point.y }
  } catch (error) {
    const err = error as BusinessError
    console.error(`[window-anchor] code=${err.code}, message=${err.message}`)
    throw error
  }
}

export function globalToWindow(
  mainWindow: window.Window,
  globalX: number,
  globalY: number
): PointPx {
  const point = mainWindow.globalDisplayToClient(
    Math.floor(globalX),
    Math.floor(globalY)
  )
  return { x: point.x, y: point.y }
}

这里有两个细节：第一，接口使用 px，不要在调用前偷偷把值转成 vp；第二，文档说明浮点输入会向下取整，所以示例明确做了 `Math.floor`，避免不同调用点出现不同的舍入结果。

如果弹窗 API 接收窗口内坐标，就在最后一步调用 `globalDisplayToClient`；如果子窗口需要按全局位置移动，则保留全局坐标。坐标只转换一次，转换发生在哪一层必须写清楚。

为什么不建议自己累加屏幕宽度

手工写 `globalX = displayWidth + localX` 只在“副屏永远位于主屏右侧、两块屏 DPI 和排列不变”时成立。用户把副屏移到主屏左边、上方，或者拔掉再插入后，偏移可能是负数，也可能完全不同。系统转换接口知道当前显示拓扑，维护成本更低。

案例二：重启恢复窗口，为什么会只剩一条边

第二个问题更隐蔽。应用把最后一次窗口位置保存下来，外接屏拔掉后再次启动，原来的全局坐标仍指向已经不存在的区域。恢复前必须先做可见性修正。

interface RectPx {
  x: number
  y: number
  width: number
  height: number
}

export function keepRectVisible(
  rect: RectPx,
  workArea: RectPx,
  minimumVisible: number = 96
): RectPx {
  const width = Math.min(rect.width, workArea.width)
  const height = Math.min(rect.height, workArea.height)
  const minLeft = workArea.x - width + minimumVisible
  const maxLeft = workArea.x + workArea.width - minimumVisible
  const minTop = workArea.y
  const maxTop = workArea.y + workArea.height - minimumVisible

  return {
    x: Math.min(Math.max(rect.x, minLeft), maxLeft),
    y: Math.min(Math.max(rect.y, minTop), maxTop),
    width,
    height
  }
}

`minimumVisible=96` 不是系统强制值，而是本文 Demo 的产品策略：即使恢复数据已经过期，也至少留出一块能让用户拖回窗口的区域。实际项目可以按标题栏高度和最小可拖拽区域调整。

拿到目标矩形后，只有在自由窗口状态下才执行移动：

async function restoreWindow(
  mainWindow: window.Window,
  saved: RectPx,
  fallbackWorkArea: RectPx
): Promise<void> {
  const safeRect = keepRectVisible(saved, fallbackWorkArea)
  const status = mainWindow.getWindowStatus()
  if (status !== window.WindowStatusType.FLOATING) {
    console.info(`[window-restore] skip, status=${status}`)
    return
  }
  await mainWindow.resizeAsync(safeRect.width, safeRect.height)
  await mainWindow.moveWindowToGlobalDisplay(safeRect.x, safeRect.y)
  console.info(`[window-restore] x=${safeRect.x}, y=${safeRect.y}, ` +
    `width=${safeRect.width}, height=${safeRect.height}`)
}

这里选择异步版本不是为了代码好看。官方文档明确区分：`resize()` 返回后不能立即取得最终生效结果，而 `resizeAsync()` 在调用生效后才返回。恢复窗口需要“先确定尺寸，再确定位置”，使用异步版本更容易保证顺序。

监听器怎样封装才不会乱序

窗口从一块屏拖到另一块屏时，位置、尺寸和 `displayId` 都可能变化，但不要假设三个回调永远按固定顺序到达。正确做法是分别接收信号，把最新快照合并后再处理。

import { window } from '@kit.ArkUI'

interface GeometrySnapshot {
  displayId: number
  globalRect?: window.Rect
  size?: window.Size
  reason?: window.RectChangeReason
}

export class WindowGeometryTracker {
  private snapshot: GeometrySnapshot = { displayId: -1 }
  private flushTimer: number = -1

  constructor(private mainWindow: window.Window) {}

  private readonly onDisplayChanged = (displayId: number): void => {
    this.snapshot.displayId = displayId
    this.scheduleFlush('display')
  }

  private readonly onGlobalRectChanged = (event: window.RectChangeOptions): void => {
    this.snapshot.globalRect = event.rect
    this.snapshot.reason = event.reason
    this.scheduleFlush('globalRect')
  }

  private readonly onSizeChanged = (size: window.Size): void => {
    this.snapshot.size = size
    this.scheduleFlush('size')
  }

  start(): void {
    this.mainWindow.on('displayIdChange', this.onDisplayChanged)
    this.mainWindow.on('rectChangeInGlobalDisplay', this.onGlobalRectChanged)
    this.mainWindow.on('windowSizeChange', this.onSizeChanged)
  }

  stop(): void {
    this.mainWindow.off('displayIdChange', this.onDisplayChanged)
    this.mainWindow.off('rectChangeInGlobalDisplay', this.onGlobalRectChanged)
    this.mainWindow.off('windowSizeChange', this.onSizeChanged)
    if (this.flushTimer >= 0) clearTimeout(this.flushTimer)
  }

  private scheduleFlush(source: string): void {
    if (this.flushTimer >= 0) clearTimeout(this.flushTimer)
    this.flushTimer = setTimeout(() => {
      const rect = this.snapshot.globalRect
      if (!rect) return
      console.info(`[window-geometry] source=${source}, displayId=${this.snapshot.displayId}, ` +
        `x=${rect.left}, y=${rect.top}, width=${rect.width}, height=${rect.height}, ` +
        `reason=${this.snapshot.reason}`)
      // 这里只发送轻量快照；持久化交给队列，不在窗口回调里做 IO。
    }, 120)
  }
}

`off` 必须传入注册时的同一个函数引用，所以回调被保存为类字段，不能在 `start()` 和 `stop()` 中各写一遍匿名函数。120ms 合并窗口也不是系统规定，而是为了避免拖拽过程每一帧都写数据库；最终值仍由松手后的回调刷新。

两种方案怎么选

方案	优点	问题	适用范围
只监听 `windowSizeChange`	简单，适合响应式布局	不包含全局位置，无法解决跨屏锚点和恢复	单屏分栏、尺寸断点
读取 `windowRect` 并自行累加屏幕偏移	旧代码改动少	显示器重排、负坐标和 DPI 变化时容易错	不推荐用于跨屏
`rectChangeInGlobalDisplay` + 系统坐标转换	参照系统一，跨屏更稳定	要处理 API 版本和异常状态	API 20+ 多显示器场景
每个回调立刻写 Preferences/RDB	数据看似实时	拖拽时产生高频 IO，事件乱序会覆盖新值	不推荐
回调合并后异步持久化	写入少，最终快照明确	需要维护取消和生命周期	推荐的工程方案

本文选择第三种坐标方案和最后一种持久化方案：系统负责坐标转换，应用只负责保存已稳定的全局快照。

我实际跑了哪些验证

纯坐标算法使用四组测试，不依赖页面状态：

case1_cross_display_global_rect: passed
case2_offscreen_restore_clamp: passed
case3_oversized_window_cap: passed
case4_drag_event_coalescing: passed

验证项	输入	预期结果
正常跨屏矩形	外接屏 `(2560,0,3840,2160)`，窗口 `(3000,520,1440,900)`	坐标保持不变
窗口掉出右侧	窗口 x=6500	修正为 x=6304，保留 96px 可拖区域
窗口大于工作区	5000×2600	限制为 3840×2160
拖拽事件过密	120ms 内连续变化	只提交稳定后的最终快照

真机或模拟器验证还要补四步：

1. 主屏和副屏采用不同分辨率，分别放在主屏右侧与左侧测试；

2. 拖动时观察 `displayIdChange`、`rectChangeInGlobalDisplay` 和 `windowSizeChange` 日志，不检查固定顺序；

3. 在副屏保存窗口位置后断开副屏，重新启动确认窗口仍可见；

4. 最大化、还原、自由窗口和分屏各跑一次，非自由窗口状态不得强行移动。

常见失败信号

日志或现象	最可能的原因	优先检查
全局 x 突然少一个主屏宽度	把 `windowRect.left` 当成全局坐标	是否读取 `globalDisplayRect` 或全局回调
弹窗出现在旧屏	锚点缓存没有随窗口迁移刷新	是否使用 `clientToGlobalDisplay`
拖动时明显卡顿	在尺寸/位置回调里写文件或数据库	回调是否只更新内存快照
重启后窗口不可见	恢复前没有检查当前显示拓扑	是否执行可见区域修正
`off` 后回调仍触发	注销时不是同一个函数引用	是否保存回调字段
只在某种窗口模式失败	自由窗口接口被用于非自由窗口	`getWindowStatus()` 是否先判断

可复用的落地结构

建议把代码拆成三个文件，而不是继续塞进页面：

window/WindowGeometryTracker.ets   // 只收集系统事件和内存快照
window/WindowCoordinate.ets       // 坐标转换、裁剪、可见性算法
window/WindowStateRepository.ets  // 节流后保存与恢复，不接触 UI

页面层只订阅“窗口宽度断点”和“锚点已更新”两类结果。这样新增右键菜单、悬浮工具条或多实例窗口时，都能复用同一套坐标模型，也能单独测试 `keepRectVisible`，不用启动完整页面才能验证。

最后归纳

鸿蒙电脑跨屏窗口错位并不是简单的 `left/top` 算错，而是坐标参照系、事件时序和窗口模式一起造成的。稳定处理需要做到四点：跨屏状态保存使用全局坐标；组件锚点通过系统接口转换；各窗口事件分别监听、合并处理；恢复窗口前先检查可见区域和自由窗口状态。

把这四个边界固定下来后，外接屏拖拽、弹窗定位和重启恢复就不再依赖某一种显示器排列。更重要的是，这套封装可以直接复用到鸿蒙电脑的多实例编辑器、浮动工具面板和跨屏拖放场景中。