📦 screen_retriever 用于读取桌面显示器的尺寸、工作区和光标坐标,但社区仓库 ohos/screen_retriever 分支刚同步上游 0.4.0(nativeapi),既无鸿蒙端实现也无法在 Dart 3.11.5 上解析依赖;我基于该分支恢复单包标准通道桥接,补齐逻辑像素折算、系统可用工作区读取、流订阅清理与窗口内鼠标采样。
完整代码已开源在 oh-flutter/screen_retriever,欢迎提交 Issue 或前往 鸿蒙系统Flutter开源库社区 交流。
前言
💻 我在 MateBook Pro 鸿蒙电脑模拟器上做了一个可以贴靠桌面右下角的工具面板,希望底部按钮始终停留在系统 Dock 上方。刚开始准备接入时,社区仓库 oh-flutter/screen_retriever 的 ohos/screen_retriever 分支只完成了上游 0.4.0 同步,里面改成了基于 nativeapi 的桌面实现,不仅缺鸿蒙端,还要求 Dart 3.14;如果换成仅调 @ohos.display 基础属性把物理屏幕尺寸与整屏宽高直接传给按逻辑像素布局的页面,点击贴边,窗口就会滑出屏幕,只剩一截标题栏。
🔍 顺着依赖报错与返回值偏差逐层核对后,我直接以 oh-flutter/screen_retriever 的 ohos/screen_retriever(0.4.0)单包结构为基线撤除了未适配的 nativeapi 依赖,恢复 MethodChannelScreenRetriever 标准通道桥接,并在鸿蒙原生侧补齐各屏幕独立缩放比折算、系统可用矩形读取、成员监听注销闭环与窗口内局部指针采样。同条件下重新跑通贴边演示,窗口底边从越界的 2872 像素回到 1932 像素,悬停在 Dock 顶边上方约 23 像素处,底部按钮恢复正常点击 🎉。

图1 工作区贴边
一、使用场景、开源仓库核查与核心问题
1.1 把工具窗贴在桌面右下角
手机上的全屏页面可以用 SafeArea 或 MediaQuery.padding 避开状态栏和底部导航条。鸿蒙电脑的自由窗口则可以在桌面上自由移动和缩放;要把整个窗口贴到屏幕边缘,还得先知道桌面上哪些区域真正可用。
我做了一个 760 × 520 虚拟像素的「快捷剪藏与桌面工作区贴边面板」。窗口从桌面左上方启动,点击「贴靠右下角工作区」后,应移到主屏右下角,与边缘保留 12 虚拟像素的间距,底部按钮也要留在 Dock 上方。页面里的归档按钮只增加计数,用来检查按钮能否点击;它没有采集剪贴板、持久化或真正归档资料。
这个桌面贴边操作需要四类屏幕信息:
- 统一的逻辑像素坐标系:Flutter 布局层以逻辑像素(在鸿蒙上对应虚拟像素 vp)定义窗口目标尺寸 760 × 520 vp,而鸿蒙原生
@ohos.window的moveWindowTo与resize接收的是物理像素(px)。插件需要像在 macOS、Windows、Linux 上一样,将屏幕尺寸与可用工作区统一折算为逻辑像素返回,并通过Display.scaleFactor给出该显示器的真实缩放比。 - 扣除系统常驻栏后的真实可用工作区:鸿蒙电脑桌面底部常驻系统任务栏 SCBSmartDock。如果
visibleSize返回全屏高度而不扣除任务栏高度,按右下角贴边公式算出的窗口底部就会钻进任务栏下方,挡住底部操作按钮。 - 动态工作区与多屏热插拔感知:当用户外接扩展显示器、调整系统显示缩放比,或者切换系统 Dock 栏自动隐藏与常驻状态时,应用需要收到变化通知再重新查询几何。插件提供
ScreenListener入口,但这一通知机制不等于已经完成多屏热插拔或 Dock 自动隐藏的真机验收。 - 窗口交互期的屏幕光标坐标:用户在工具窗内点击时,应用可以把当前鼠标事件换算到屏幕坐标,用于定位伴随菜单。窗口内采样只覆盖交互发生的瞬间,不承诺持续追踪整个桌面的光标。
1.2 上游与社区仓库核查:为何基于 0.4.0 单包恢复标准通道
动手修改前,我先后检查了 leanflutter 的上游源码仓库、pub.dev 包信息,以及 oh-flutter、CPF-Flutter 等开源组织下的既有移植。上游 leanflutter/screen_retriever 用于桌面显示器尺寸、工作区和光标查询,按 MIT 许可分发,仅覆盖 Linux、macOS 与 Windows 三端。

图2 上游仓库
同时我核查了社区仓库 oh-flutter/screen_retriever 的 ohos/screen_retriever 分支(图 3)以及 CPF-Flutter 组织的旧版移植。社区新仓库刚完成上游 0.4.0 同步,已经把 0.2.x 的多包联合架构收拢回单包,并把底层切到 nativeapi 0.6.0 与 DisplayManager 新接口,要求 Flutter 3.50 和 Dart 3.14;不仅没有鸿蒙实现,在当前 HarmonyOS Flutter 3.41.9+ohos-1.0.2(Dart 3.11.5)上连依赖解析都无法通过。而早先社区的 0.2.x 移植虽然通过方法通道接入了部分屏幕属性,但结构与社区新版主干分叉,且未读取系统可用工作区,贴边窗口依然会落入底部 Dock。

图3 鸿蒙适配仓
如果另起一个低版本仓库或硬退回旧的联合多包结构,后续就很难顺滑合回社区已经建好的 ohos/screen_retriever 分支;如果强行保留 nativeapi 依赖,在当前鸿蒙 Flutter 工具链上又编译不起来。因此我直接以 0.4.0 单包基线为起点,保留对外 screenRetriever、Display、ScreenListener 等既有 Dart 接口不变,在内部撤除未适配依赖、恢复标准通道 MethodChannelScreenRetriever 并补全 ArkTS 原生工作区实现(见表 1)。
| 核查来源 | 版本或分支 | 与本篇相关的核查结论 |
|---|---|---|
| leanflutter 主分支 | 0.4.0 | 迁移至 nativeapi C++ 核心,要求 Flutter 3.50 / Dart 3.14,无鸿蒙实现 |
| oh-flutter/screen_retriever | ohos/screen_retriever(基线 0.4.0) | 已由上游 0.4.0 单包导入建仓,尚未实现鸿蒙原生端与通道兼容 |
| 既有社区旧版移植参考 | 0.2.x 分支 | 方法通道契约可作参考,但未扣减系统可用工作区且与 0.4.0 单包目录分叉 |
| 本次单包适配分支 | feat/ohos_screen_retriever_0.4.0 | 移除 nativeapi 依赖限制,恢复通道并补全鸿蒙单包工作区避让与鼠标采样 |
表1 版本与范围
1.3 素朴直传基线与鸿蒙接入时的五处隐患
🐛 为什么不能只在鸿蒙端简单调一下 display.getDefaultDisplaySync() 把宽高塞进字典就交差?我结合对照基线、0.4.0 基线代码与 0.2.x 通道协议逐项排查,梳理出五处直接影响桌面贴边定位与运行稳定性的问题:
- 物理像素直传与缩放比失真。在上游桌面三端约定的契约中,
size、visiblePosition、visibleSize返回的全部是逻辑像素。如果鸿蒙端直接把物理宽高 3120 和 2080 原封不动写入字典且漏填scaleFactor,业务层回退读取当前视图缩放比 1.90 去把逻辑目标坐标换算成物理像素时,3120 会被当成逻辑宽度再乘一次 1.90,横向目标瞬间膨胀到 4461 像素。此外,多显示器场景下必须优先读取每块屏幕自身的densityPixels,不能拿主窗口像素比硬套外接副屏。 - 可用工作区按整屏硬编码,忽略鸿蒙电脑系统 Dock 避让区。如果构造工作区字段时把起点固定填为零点、把
visibleSize直接赋值为整块屏幕的宽高,就会漏掉桌面常驻栏。HarmonyOS SDK 从 API 12 起已在@ohos.display的Display接口上公开了无需额外权限的getAvailableArea()方法,专门返回扣除顶部状态栏与底部 Dock 任务栏后的可用物理像素矩形。在 MateBook Pro(3120 × 2080 像素)桌面上,底部系统任务栏占据高度 125 像素(65.8 vp),忽略这部分占用就会让贴边窗口底边伸入 Dock 下方。 - 单包平台入口注册与模块设备形态声明缺位。0.4.0 基线根 pubspec.yaml 的平台配置节点尚未接入鸿蒙插件类
ScreenRetrieverPlugin声明;若鸿蒙原生模块 ohos/src/main/module.json5 的deviceTypes未同时覆盖 default、tablet 与 2in1 三种形态,应用在鸿蒙电脑上还可能退回手机兼容窗口而非原生自由多窗口模式。 - 事件通道恢复后须守住流订阅取消闭环。上游 0.4.0 已在
ScreenRetriever内部通过_subscription?.cancel()修复了早先 0.2.x 时期removeListener在监听清空时错写成新建空订阅的流泄漏,但在将底层从nativeapi换回EventChannel时,原生侧也必须保存并注销成员回调引用,防止页面反复进出时叠加派发或残留原生监听器。 - 窗口交互期缺少光标屏幕坐标换算。鸿蒙普通三方应用无法在无权限后台全局监听桌面指针,但在鼠标进入当前 Flutter 自由窗口交互期间,完全可以结合宿主窗口矩形、标题栏渲染偏移和当前局部鼠标事件算出准确的屏幕逻辑坐标。它是受交互范围限制的补充能力,不能替代系统级全局指针钩子。
二、修复前后运行效果与 WMS 数据对比
2.1 测试环境与同条件复现口径
为了直观验证上述问题对桌面贴边窗口的实际影响,我准备了页面布局、贴边公式与交互逻辑完全同款的「快捷剪藏与桌面工作区贴边面板」对照工程:修复前基线包(com.example.pgc28base)模拟未做逻辑像素折算、未接入 getAvailableArea() 且光标固定返回零点的原始全屏直出实现;修复后包则接入本文适配后的 screen_retriever 0.4.0 单包与鸿蒙原生工作区避让实现。随后我在同一硬件规格的 MateBook Pro 鸿蒙电脑模拟器上使用 0.4.0 单包完成复测(因调试签名模板绑定包名,0.4.0 重测日志中的进程包名为 com.example.splashremovepatched,下文的界面录屏与定格图保留同条件对照包 com.example.pgc28fix 的同几何运行画面)。运行与测量环境如下:
- 跨端框架与构建工具链:Flutter 3.41.9+ohos-1.0.2(Dart 3.11.5),DevEco Studio 26.0.0.865,HarmonyOS SDK 26.0.0.105 / API 26。
- 运行目标设备:鸿蒙电脑模拟器 MateBook Pro(设备形态 2in1,镜像/系统版本 7.0.0.107(SP8DEVC00E47R1P3))。
- 系统显示与任务栏基准参数:主屏物理分辨率为 3120 × 2080 像素(60 赫兹),虚拟像素比
densityPixels为 1.90(对应完整屏幕逻辑尺寸 1642.1 × 1094.7 vp);底部系统任务栏窗口常驻占据物理矩形[0, 1955, 3120, 125]像素(顶边位于纵坐标 1955 像素,占用高度 125 像素即 65.8 vp)。
两包启动后,宿主 EntryAbility.ets 均将初始自由窗口定位在桌面左上基准矩形 [180, 140, 1444, 988] 像素(即逻辑宽高 760 × 520 vp),随后按一致的物理坐标序列执行三步点击操作:点击初始窗口底部操作栏 (575, 1061) 像素处的「读取光标坐标」按钮;点击 (340, 1061) 像素处的「贴靠右下角工作区」按钮(目标逻辑宽高 760 × 520 vp,右下安全边距 12 vp);最后在右下角预期贴边窗口的底部操作栏依次点击「读取光标坐标」与「确认归档剪藏」按钮。
2.2 修复前:窗口越过屏幕边缘
先在干净桌面拉起基线对照包并执行上述三步同条件操作,实际运行过程如图 4 所示:

图4 修复前操作
从图 4 的初始面板可以看到,未折算的接口把屏幕尺寸与可用工作区均返回为 3120.0 × 2080.0,缩放比为空,右侧几何投影画布已经预警画出了超出屏幕框右下角的红色目标框。第 1 步点击「读取光标坐标」后,面板读到的光标坐标恒为零点。
紧接着执行第 2 步点击「贴靠右下角工作区」,面板按照公式向原生窗口发起 [4461, 2941, 1444, 988] 像素的移动请求,最终定格画面如图 5 所示:

图5 修复前越界
观察图 5 右下角时间托盘正上方:因为请求的坐标超出了 3120 × 2080 像素的屏幕物理边界,鸿蒙电脑窗口管理服务触发了边缘保底钳制,将基线窗口限制在 [2783, 1884, 1444, 988] 像素(窗口底边达 2872 像素)。此时整个窗口只有左上角一小截标题栏露在右下角任务栏上方,页面内容和底部操作按钮落到屏幕右下方,受到屏幕边缘和 Dock 遮挡,第 3 步归档点击落空。即便只补上 1.90 缩放除算而仍按整屏高度 1094.7 vp 返回工作区,按公式推算出的窗口底边也会落在 2057 像素,依然伸入顶边位于 1955 像素的系统 Dock 栏下方 102 像素(53.7 vp)。
2.3 修复后:窗口停在 Dock 上方
停止基线包后,在同一桌面条件下拉起接入修复后单包的示例工程并执行相同的三次点击序列,实测过程如图 6 所示:

图6 修复后操作
修复包启动后,面板顶部状态显示绿色的「已识别 Dock 避让区」:size 折算为 1642.1 × 1094.7 vp,scaleFactor 返回原生 1.90,visibleSize 返回扣除底部 65.8 vp 系统任务栏后的 1642.1 × 1028.9 vp。第 1 步点击 (575, 1061) 像素处的「读取光标坐标」按钮时,面板立即刷新出 (302.6, 558.4) vp——用物理点击坐标除以 1.90 验算后与显示值一致。
第 2 步点击「贴靠右下角工作区」并完成第 3 步贴边后光标读取与剪藏归档的定格效果如图 7 所示:

图7 修复后贴边
在图 7 中,快捷剪藏面板停在桌面右下角,右侧和底部各留出 12 vp(约 23 像素)间距,底部操作栏完整显示在系统任务栏上方。随后在右下角新位置点击 (2048, 1865) 像素处的「读取光标坐标」,该次点击返回值为 (1077.9, 981.6) vp,点击「确认归档剪藏」后,演示计数变为 1。用 0.4.0 单包构建产物在干净 2in1 模拟器复测,同样实得主屏可用矩形 [0, 0, 3120, 1955] 像素、Dock 占位 [0, 1955, 3120, 125] 像素、窗口管理服务实测位置 [1653, 944, 1444, 988] 像素以及 (302.6, 558.4) 与两组复测光标坐标,验证结果完全一致。
两包在 MateBook Pro 上采集到的 HiLog 指标与窗口管理服务实测数据对照见表 2:
| 测量维度与核验项 | 修复前基线包 | 修复后单包工程 |
|---|---|---|
Display.size 返回值 | 3120.0 × 2080.0(物理像素误传) | 1642.1 × 1094.7 vp(逻辑像素) |
Display.scaleFactor 返回值 | 空值(字段缺失) | 1.90(目标屏幕真实缩放比) |
Display.visiblePosition | (0.0, 0.0)(硬编码) | (0.0, 0.0)(实测顶栏无占用) |
Display.visibleSize | 3120.0 × 2080.0(忽略底部 Dock) | 1642.1 × 1028.9 vp 🔴↓(扣除 65.8 vp Dock) |
| 左上初始位光标读取 | (0.0, 0.0) vp(硬编码零点) | (302.6, 558.4) vp(本次点击取一位小数) |
| 右下贴边请求物理矩形 | [4461, 2941, 1444, 988] px | [1653, 944, 1444, 988] px |
| 窗口管理服务实测物理矩形 | [2783, 1884, 1444, 988] px | [1653, 944, 1444, 988] px |
| 窗口底边相对 Dock 顶边(1955 px) | 2872 px(越界遮挡) | 1932 px 🔴↓(悬停于 Dock 上方 23 px) |
| 贴边后光标读取与归档结果 | 按钮越界不可达,归档 0 条 | 光标 (1077.9, 981.6) vp,演示计数 1 条 🟢↑ |
表2 实测指标对比
三、鸿蒙电脑屏幕工作区与单包插件实现解析
3.1 把查询、鼠标采样和屏幕事件拆成三条独立通路
在适配后的 screen_retriever 单包中,我按照 ScreenRetrieverPlatform 的抽象契约在 MethodChannelScreenRetriever 中把跨端通信重新拆回三条清晰链路:显示器查询走方法通道返回显示器模型,鼠标查询走同一方法通道返回屏幕坐标,屏幕与工作区动态变化则通过独立的事件通道 EventSink 推送给 ScreenListener。应用的窗口移动仍由示例工程自身的宿主通道负责,插件只专注提供准确的屏幕几何信息。

图8 跨端调用链
整个单包适配按以下顺序推进:
- 在根
pubspec.yaml中撤除尚未适配鸿蒙且依赖 Dart 3.14 的nativeapi/nativeapi_flutter,恢复sdk: ^3.4.0约束,并在flutter.plugin.platforms.ohos注册原生插件类ScreenRetrieverPlugin。 - 对外保留
lib/screen_retriever.dart转导出legacy.dart契约,在MethodChannelScreenRetriever恢复标准方法与事件通道并接入对display.getAvailableArea()与独立densityPixels的原生读取。 - 在
MethodChannelScreenRetriever层对原生返回的字典做_normalizeDisplayMap归一化,并在Display.fromJson兼容数值转浮点,消除 ArkTS 整数分流风险。 - 在
ScreenRetrieverPlugin.ets桥接显示器增删改与可用区变化事件、在引擎或订阅取消时按成员引用执行off注销,同时收紧MethodChannelScreenRetriever中窗口内鼠标采样的微任务作用域。
3.2 设备形态声明与可用工作区核心折算源码
在鸿蒙工程构建阶段,插件与宿主模块的 module.json5 需同时覆盖目标运行设备形态,否则包管理服务在鸿蒙电脑上可能以手机兼容窗口而非原生 2in1 自由多窗口模式拉起应用。我在插件根目录的 ohos/src/main/module.json5 的 deviceTypes 中声明了 "default"、"tablet" 与 "2in1",核心配置与主屏查询实现如图 9 所示:

图9 核心配置实现
在 ScreenRetrieverPlugin.ets 中,主屏查询处理默认显示器,显示器列表查询逐块遍历屏幕。两条路径都会先通过 displayItem.densityPixels 确定每块显示器各自的缩放比,再异步读取物理可用区,最后将结果换算为逻辑像素字典;扩展屏还会叠加显示器自身的全局坐标起点。下面是读取可用区的完整函数:
// 优先调用系统异步可用矩形接口,失败或返回空值时按三级兜底策略回退。
private async resolveAvailableAreaPx(displayItem: display.Display): Promise<AvailableAreaResult> {
try {
const rect: display.Rect = await displayItem.getAvailableArea();
if (rect != null && rect.width > 0 && rect.height > 0) {
return {
left: Number(rect.left ?? 0),
top: Number(rect.top ?? 0),
width: Number(rect.width),
height: Number(rect.height),
source: 'display.getAvailableArea',
};
}
} catch (err) {
hilog.warn(
LOG_DOMAIN,
TAG,
'display(id=%{public}d).getAvailableArea 降级: %{public}s',
displayItem.id,
String(err)
);
}
const availWidth: number = Number(displayItem.availableWidth ?? 0);
const availHeight: number = Number(displayItem.availableHeight ?? 0);
if (availWidth > 0 && availHeight > 0 &&
(availWidth < displayItem.width || availHeight < displayItem.height)) {
return {
left: 0,
top: 0,
width: availWidth,
height: availHeight,
source: 'display.availableWidthHeight',
};
}
const avoidFallback: AvailableAreaResult | null = this.resolveWindowAvoidFallbackPx(displayItem);
if (avoidFallback != null) {
return avoidFallback;
}
if (availWidth > 0 && availHeight > 0) {
return {
left: 0,
top: 0,
width: availWidth,
height: availHeight,
source: 'display.availableWidthHeightFull',
};
}
return {
left: 0,
top: 0,
width: displayItem.width,
height: displayItem.height,
source: 'display.fullSizeFallback',
};
}
这里之所以把 getAvailableArea() 放在第一优先级,是因为它返回包含左上角起点与宽高的完整矩形。同步宽高属性只有两个标量,一旦遇到顶部状态栏或左侧停靠栏占用,就无法表达可用区的起点偏移。本次在 MateBook Pro 上实测命中的是主屏原点为零、底部 Dock 常驻 125 像素的路径;顶部或侧边停靠栏形态仍需在对应桌面布局下单独核验。
3.3 标题栏偏移换算、事件通道与流订阅注销修复
窗口内光标换算有一个容易忽略的原点差异:鸿蒙自由窗口的 windowRect 包含系统标题栏,而 Flutter 指针事件的局部坐标从内容渲染区左上角算起。实测 MateBook Pro 标准自由窗口标题栏高度约为 36.84 vp(70 像素),漏加这层偏移会让算出的屏幕纵坐标整体偏小。
插件通过 AbilityAware 取得宿主主窗口,再从当前 Flutter 渲染节点读取 getPositionToWindow() 偏移。单屏条件下,屏幕逻辑坐标等于窗口物理起点除以显示器缩放比,加上渲染区域相对窗口的偏移,再加当前鼠标事件的局部坐标。以初始窗口点击为例,窗口物理起点是 [180, 140] 像素,局部鼠标坐标为 [207.9, 447.9] vp,标题栏渲染偏移为 [0.0, 36.8] vp,换算后得到 [302.6, 558.4] vp,与物理点击坐标除以 1.90 的结果吻合。
屏幕动态变化走独立的 dev.leanflutter.plugins/screen_retriever_event 事件通道。原生侧在订阅建立时注册显示服务的增删改回调与默认显示器的可用区变化回调,将事件统一转换为标准名称并通过 EventSink 发送;在取消订阅或引擎分离时传入保存的同一个成员函数引用执行 off 解绑。与此同时,我在 ScreenRetriever 单例里沿用了先判断监听器为空、再调用 _subscription?.cancel() 并置空订阅句柄的收尾方式,确保反复进出页面重新注册监听时不会残留旧流订阅。
3.4 鼠标位置采样只在当前事件微任务内有效
在 MethodChannelScreenRetriever 中,我还收紧了窗口局部鼠标位置的缓存生命周期。如果无限期保留“最后一次鼠标局部坐标”,当鼠标已经移出窗口或窗口被代码移到了右下角之后,业务再去调用查询,就会把过期的旧局部坐标与新窗口起点强行相加,拼出一个看似合法、实则从未发生过点击的虚假坐标;触摸屏点按事件同样不能混作桌面鼠标位置。
下面是 MethodChannelScreenRetriever 中的完整指针路由采样函数。它仅接收鼠标设备的悬停、移动、按下和松开四类事件,并在当前事件循环的微任务尾部自动清空;鼠标移出、取消或触摸输入会立即清空采样。保留松开事件,是因为按钮的 onPressed 点击回调恰好在松开阶段同步触发。
void _handlePointerEvent(PointerEvent event) {
// 每次收到新指针事件先清空旧值,避免跨事件残留过期局部坐标。
_cursorEvent = null;
_lastLocalCursorPoint = null;
if (event.kind != PointerDeviceKind.mouse) {
return;
}
if (event is PointerHoverEvent ||
event is PointerMoveEvent ||
event is PointerDownEvent ||
event is PointerUpEvent) {
_cursorEvent = event;
_lastLocalCursorPoint = event.position;
scheduleMicrotask(() {
// 仅清理当前同一事件对象,防止提前误删后续新事件写入的采样。
if (identical(_cursorEvent, event)) {
_cursorEvent = null;
_lastLocalCursorPoint = null;
}
});
}
}
_cursorEvent 与 _lastLocalCursorPoint 均为 MethodChannelScreenRetriever 的可空私有成员。考虑到组件树手势回调可能早于全局指针路由执行,getCursorScreenPoint 在尚未拿到采样时会先等待一次微任务让同次输入完成路由派发,随后立即将局部坐标连同安全读取的视图像素比传给原生通道;一旦业务先等待网络请求或窗口移动动画结束再去查询,微任务早已将采样清零,不会误用旧坐标。

图10 运行日志
图 10 右侧展示了 0.4.0 单包方案在 MateBook Pro 干净模拟器上真实采集的原生与界面日志(调试签名模板为该测试安装包装配的包名为 com.example.splashremovepatched,日志显示前缀为 om.example.splashremovepatched):ScreenRetrieverPlugin 通过 display.getAvailableArea 读出物理可用区 [0, 0, 3120, 1955] 像素并折算为 1642.1 × 1028.9 vp,窗口贴靠至 [1653, 944, 1444, 988] 像素后,底边实测落点为 1932 px,第二次点击准确换算出 (1077.9, 981.6) vp。
四、工程踩坑与多设备边界条件
除了核心工作区折算,这次将 0.4.0 单包在鸿蒙工具链上改为标准通道实现时,还有几处容易踩坑的跨端细节与硬件边界需要一起说明。
4.1 消除 ArkTS 整数分流引发的反序列化异常
对接通道数据时有一个隐蔽的类型陷阱:在早先桌面端或严格按浮点强转的 Display.fromJson 写法中,坐标与尺寸转换器常常直接写 Offset(map['dx'] as double, map['dy'] as double)。而在 ArkTS 中所有数字都是数值类型,鸿蒙原生层的标准消息编解码器在序列化时,只要数值恰好没有小数位(例如工作区起点 0 除以 1.9 仍为 0,或在 2.0 缩放比屏幕上 3120 除以 2.0 等于 1560),就会按 32 位整数 INT32 写入字节流,到达 Dart 侧变成整型,一旦遇到 as double 强转就会触发 type 'int' is not a subtype of type 'double' 崩溃。
为此我在单包内同时做了两道防护:一方面在 MethodChannelScreenRetriever 收到原生通道字典后先经过 _normalizeDisplayMap 统一清洗,把尺寸、可用区起点、可用区宽高与缩放比里的数值转为 double,把显示器编号转为字符串;另一方面在 Display.fromJson 的内部几何解析函数中也把整型与浮点兼容读取写成 (map['width'] as num).toDouble(),即使外部测试或调用方直接传入整型 JSON 映射也不会失手崩溃。
4.2 多视图像素比安全读取与单包插件注册配置
旧实现里在读取当前视图像素比时习惯直接调用 PlatformDispatcher.instance.views.single.devicePixelRatio。在桌面多窗口或无界面单测环境下,视图集合可能为空或不止一个视图,直接读取单元素属性会抛出 StateError。MethodChannelScreenRetriever 改为优先读取 implicitView,为空时再回退取首个可用视图,无视图时安全回退为 1.0。
此外,既然适配以单包形态直接合入社区仓库,构建配置和版本号也要对应对齐:我在根 pubspec.yaml 的环境字段中放宽为兼容 Dart 3.4.0 与 Flutter 3.22.0 及以上,将包版本从 0.4.0 提升至 0.5.0-ohos.1 并在 CHANGELOG.md 顶部明确标注破坏性变更,同时在鸿蒙平台配置块下声明 pluginClass: ScreenRetrieverPlugin,把尚未在本分支提供原生实现的 linux、macos 与 windows 平台声明从 pubspec.yaml 中移除,使包元数据与真实支持范围保持一致。这样接入工程只需像引用常规单包那样依赖主仓即可完成原生注册,不再需要拆出单独的鸿蒙子包,也无需配置任何 dependency_overrides。另外要老实说明的是,因为这次撤除了 nativeapi 依赖,而当前适配器只补齐了鸿蒙通道与端侧代码,原本依托原生 C++ 库的 Linux、macOS 和 Windows 桌面端实现并不在本篇验证与回归范围内。
4.3 降级结果不等于精确工作区
getAvailableArea() 返回完整矩形,是本次模拟器成功扣除 Dock 高度的唯一精确来源。同步宽高属性只有两个标量,无法表达顶部或左侧的占用偏移;宿主窗口自身的规避区又属于当前窗口局部属性,尤其不能在副屏查询时拿主窗口规避区冒充副屏工作区。
因此我把降级分支仅作为低版本或接口异常时的兼容性兜底,并在 HiLog 中打印命中来源字段。如果降级分支最终返回了整块屏幕尺寸,只能说明拿到了显示器分辨率,不能代表系统任务栏已被扣除;业务层发现工作区与整屏相等时应保留用户手动拖动窗口的能力。可用区变化通知按矩形签名做了去重,但尚未采集 Dock 动态伸缩动画或真机热切换过程,不对这两种动态场景做成功率承诺。
4.4 分清本地单测与单屏模拟器实测范围
仓库内共配备了 21 项自动化测试:其中包根目录 test 下的 12 项测试分两组——legacy_api_test.dart 中的 4 项验证模型 JSON 往返、整型坐标反序列化、平台委托以及 removeListener 取消流订阅;screen_retriever_ohos_test.dart 中的 8 项验证默认通道实例注册、方法通道调用、32 位整数与浮点混合字典归一化、事件通道派发以及鼠标采样微任务过期清理;示例工程测试目录下的 9 项测试验证贴边几何公式边界、窄工作区跳过贴边与尺寸钳制、窗口复位异常状态回滚与界面按钮交互。需要说明的是,单测中的多屏参数属于预设模拟输入,只证明 Dart 层协议解析正确,并未执行原生 ArkTS 侧的多屏硬件枚举。
实际运行证据限定在 MateBook Pro(HarmonyOS 7.0.0.107 / API 26)单屏模拟器。异构缩放双屏真机、负坐标扩展屏原点、物理显示器热插拔,以及 Linux、macOS、Windows 三端基于原桌面的回归运行均不在本次实测范围内。此外,当没有有效窗口内鼠标事件时,getCursorScreenPoint 会显式抛出 StateError(原生侧返回 CURSOR_UNAVAILABLE),不再默默返回容易与原点混淆的 (0, 0) 零点,业务代码应当捕获该异常提示用户当前无窗口内光标采样。
五、结论与可直接复用的建议
5.1 厘清插件与宿主应用的职责边界
本篇基于 oh-flutter/screen_retriever 的 ohos/screen_retriever(0.4.0)单包基线完成了鸿蒙电脑适配,解决了依赖 nativeapi 导致在 Dart 3.11.5 下无法解析、以及单屏自由窗口右下角贴边越界和底部 Dock 遮挡问题:插件负责将屏幕尺寸、可用工作区与窗口交互期光标坐标统一折算为逻辑像素返回,并在屏幕或可用区变化时发出重新查询通知;窗口的目标宽高、安全边距、移动时机与异常提示则由业务应用自行控制。
5.2 在自己的项目中使用
💡 在业务工程的 pubspec.yaml 中可直接引入社区仓库与 ohos/screen_retriever 目标分支(单包结构下无需再填 path 子路径,也无需配置 dependency_overrides):
dependencies:
screen_retriever:
git:
url: https://atomgit.com/oh-flutter/screen_retriever.git
ref: ohos/screen_retriever
如果读者在社区目标分支尚未同步全部提交时希望提前拉取包含完整剪藏贴边示例在内的同步版本,可先将 url 指向 Fork 复现仓 https://atomgit.com/abaoge/screen_retriever.git,并将 ref 设为 feat/ohos_screen_retriever_0.4.0。
打开鸿蒙宿主工程 ohos/entry/src/main/module.json5,确认 deviceTypes 中包含 "2in1"(支持以鸿蒙电脑原生自由多窗口形态运行,同时兼顾手机与平板可保留 "default"、"tablet"):
"deviceTypes": [
"default",
"tablet",
"2in1"
]
在业务代码中导入标准入口 package:screen_retriever/screen_retriever.dart,即可直接沿用 Display、ScreenListener 与 screenRetriever 查询主屏工作区并换算目标窗口物理矩形:
import 'dart:ui';
import 'package:screen_retriever/screen_retriever.dart';
/// 计算主屏右下角贴边窗口的物理像素矩形。
Future<Rect> bottomRightWindowRectPx({
Size panelVp = const Size(760, 520),
double marginVp = 12,
}) async {
if (!panelVp.width.isFinite ||
!panelVp.height.isFinite ||
panelVp.width <= 0 ||
panelVp.height <= 0 ||
!marginVp.isFinite ||
marginVp < 0) {
throw ArgumentError('Window size and margin must be finite and valid.');
}
final Display primary = await screenRetriever.getPrimaryDisplay();
final double? scale = primary.scaleFactor?.toDouble();
final Offset? origin = primary.visiblePosition;
final Size? work = primary.visibleSize;
// 缺少工作区或缩放比时明确失败,避免把未经校验的整屏当作安全区。
if (scale == null ||
!scale.isFinite ||
scale <= 0 ||
origin == null ||
!origin.dx.isFinite ||
!origin.dy.isFinite ||
work == null ||
!work.width.isFinite ||
!work.height.isFinite ||
work.width <= 0 ||
work.height <= 0) {
throw StateError('The display has no valid work area or scale factor.');
}
if (panelVp.width + 2 * marginVp > work.width ||
panelVp.height + 2 * marginVp > work.height) {
throw StateError('The panel does not fit in the work area.');
}
// 只在交给鸿蒙窗口接口之前换算一次;返回值全部是物理像素。
return Rect.fromLTWH(
((origin.dx + work.width - panelVp.width - marginVp) * scale)
.roundToDouble(),
((origin.dy + work.height - panelVp.height - marginVp) * scale)
.roundToDouble(),
(panelVp.width * scale).roundToDouble(),
(panelVp.height * scale).roundToDouble(),
);
}
该函数只计算并返回物理像素矩形,异常会向上抛出供页面捕获提示。已有鸿蒙窗口管理通道的应用,把返回矩形的左上角传给 moveWindowTo、宽高传给 resize 即可,切勿再重复乘一次缩放比。需要参考原生窗口移动写法的读者,可以查看适配分支仓库内的 示例宿主实现 与 完整同款 Example。若业务需要跟随分辨率或工作区变化自动重算贴边位置,在页面初始化时调用 screenRetriever.addListener(this),并在 dispose 中成对调用 screenRetriever.removeListener(this)。
5.3 使用时保留这几个判断
- 布局计算与原生窗口移动分清单位。
screen_retriever返回的尺寸、工作区和光标坐标均为逻辑像素(vp),而鸿蒙@ohos.window的moveWindowTo与resize接收物理像素(px),业务侧只在最终下发窗口位置前乘一次对应显示器的scaleFactor。 - 在当前鼠标事件的同步阶段或首个异步点前读取光标坐标。
getCursorScreenPoint采样仅在当前窗口鼠标事件的微任务周期内有效,先等待异步任务或窗口移动后再调用会触发StateError异常,且不支持后台全局桌面光标监听。 - 区分已验证与未验证的硬件环境。本次适配在 MateBook Pro(HarmonyOS 7.0.0.107 / API 26)单屏模拟器完成验证;连接异构外接显示器的双屏真机与桌面其他平台建议在实际硬件上进一步核对。
小结
把屏幕尺寸统一折算为逻辑像素并接入系统可用工作区后,演示工具窗终于稳稳停在系统 Dock 正上方,底部归档按钮也恢复了正常点击。排查这类桌面窗口错位问题时,与其在业务布局里硬凑偏移常数,不如顺着插件返回值、缩放比和窗口管理服务的实际落点逐层核对,把跨端单位契约和监听生命周期一次理顺。
5



被折叠的 条评论
为什么被折叠?



