企业官网建设流程全解析

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)还给出一个很重要的工程建议：尺寸、位置、避让区和屏幕切换应该分别监听，各回调只处理自己拿到的数据；布局相关回调里不要做文件写入、网络请求等耗时操作。

先把三套坐标分清

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

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 合并窗口也不是系统规定，而是为了避免拖拽过程每一帧都写数据库；最终值仍由松手后的回调刷新。

两种方案怎么选

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

我实际跑了哪些验证

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

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

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

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

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

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

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

常见失败信号

可复用的落地结构

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

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

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

最后归纳

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

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