鸿蒙PC 窗口与桌面基础交互实战:用 ArkUI 把「窗口泊入 / 还原」做成一套程序坞工作台

欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/

欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper


前言:在手机上,「窗口」是一个几乎不存在的概念——应用就是全屏,用户只有一个注意力焦点;到了鸿蒙PC,窗口变成一条可以拖动、可以缩放、可以被最小化成图标、可以在程序坞里排队的一等公民。于是每一个桌面应用都要额外回答四个问题:我现在有几个窗口?谁拿着焦点?被收起的那一个去了哪里?用户再点一次图标,应该发生什么?

本文不写「桌面适配鸡汤」,而是把一个真实跑在鸿蒙PC 上的小工程「泊坞 · BERTHSIDE」拆开:它把任务栏程序坞(Dock)做成一个窗口收纳工作台,用「泊入 / 离泊 / 固定 / 临时泊位 / 汽水珠」这一套隐喻,把窗口的生命周期完整地摆到台面上。技术栈只有一个:ArkUI 声明式 UI 框架 + ArkTS 语言,零三方依赖,13 个手写 .ets 文件、约 37 KB。文中所有代码都逐行核对自配套工程 Berthside_ohos,五张配图是鸿蒙PC 真机的整屏截图(顶部系统状态栏、底部系统 Dock 与托盘同时入镜,一眼可辨是 PC 而不是手机)。

需要提前说明一句,因为「跨平台框架」这个词在鸿蒙语境里被用得很乱:本文用的是 ArkUI——鸿蒙原生的声明式 UI 框架,一次开发可部署到手机 / 平板 / PC / 车机等多种设备形态;而 ArkUI-X 是在 ArkUI 之上做的跨平台扩展层,用来把同一套声明式 UI 跑到 Android / iOS 上。本文没有一行 ArkUI-X 代码,也没有跨端壳工程。文中出现的「跨平台框架」一律指 ArkUI 这套声明式框架的能力边界:哪些契约是框架给的、可以跨设备带走,哪些是 2in1 设备形态给的、必须按平台写。

关键词:鸿蒙PC、鸿蒙 PC、开源鸿蒙PC、窗口与桌面基础交互、ArkUI、ArkTS、声明式 UI 框架、跨平台框架能力边界、程序坞 Dock、窗口收纳、最小化还原、2in1 自由窗口、ForEach 键生成器、状态不变式、AtomGit。


一、边界先行:五张整屏截图、一个 13 文件工程、一份内存数据

写桌面交互,最容易犯的错是「把设计稿当实机、把占位图当窗口能力、把一次点击当交互闭环」。所以先把边界摊开。

第一,五张图都是鸿蒙PC 的完整桌面,不是应用窗口的裁剪图。 每张图顶部都有鸿蒙PC 的系统状态栏(左侧「11月16日 上午11:42」,右侧一排系统托盘图标),底部是系统 Dock(搜索、文件、图库、应用市场、音乐、浏览器、微信等),中间偏左才是运行中的「泊坞」。这种取景是刻意的:只要系统状态栏与系统 Dock 同时入镜,读者不需要相信作者任何一句话,就能确认这是鸿蒙PC。后台还开着 DevEco Studio,工程树里能看到 Berthside_ohos、AppScope、entry、hvigor、oh-package.json5——写代码的 IDE 和跑起来的应用同框,这是鸿蒙PC 上最典型的开发姿态。

第二,工程事实。 目录 项目源码/Berthside_ohos;AppScope/app.json5 里 bundleName 是 com.berthside.dock,vendor Berthside Lab,versionCode 1000000,versionName 1.0.0,应用标签「泊坞 · Berthside」;entry/src/main/module.json5 只声明 deviceTypes: ['2in1'],mainElement: EntryAbility,并且挂了 entity.system.home + action.system.home(可被设为桌面启动器);build-profile.json5 的 compatibleSdkVersion 与 targetSdkVersion 都是 26.0.0(HarmonyOS,API 26)。手写代码 13 个 .ets:pages/Index.ets(271 行,唯一的状态容器与全部事件处理)、common/Models.ets(5 个数据类 + 一份演示数据)、common/Theme.ets(色板、字号阶梯、尺寸与五个视图键)、components/ 下 9 个组件(顶栏、舞台、程序坞、泊位台账、托盘泡区、偏好面板、日志、图标、吐司)、entryability/EntryAbility.ets(24 行入口)。oh-package.json5 里没有任何三方依赖。

第三,这是一个「桌面沙盒」,不是系统级窗口管理器。 界面里那些「窗口」是内存里的 WinPane 数据对象,被收起后并没有真的调用 window 模块去最小化;它演示的是窗口收纳的交互契约:三态、焦点、泊位、还原路径。真正的系统窗口控制是第八章那五十来行增量代码,本文会明确标注「增量、未进入当前构建」,不把演示原型吹成系统能力。

第四,三处已知缺陷,先承认再修。(1)EntryAbility.ets 全文 24 行,只做了 windowStage.loadContent('pages/Index', ...),没有调用任何窗口属性 API——截图里那个可最大化、可悬浮在 IDE 之上的窗口,完全来自 2in1 设备形态与系统默认窗口装饰;(2)「汽水偏好」页五个开关里,前三个(汽水珠、汽泡预览、果肉环)在视觉上已经实现,后两个(新窗口自动占位、双击图标聚焦)只是把状态翻了个面 + 弹一个吐司,没有接线到行为,所以图 4 里它们是灰的;(3)launch() 用 n${this.wins.length + 1}-${a.id} 生成窗口 id,关掉几个窗口后再开新窗口,id 会与历史 id 撞车。三处修法分别放在第六章(id 单调源)、第八章(偏好接线)与第九章(窗口能力)。

边界讲完,问题反而更聚焦:当窗口数量是变量、焦点是唯一资源、用户每一步操作都可能让某个窗口「消失」时,一个鸿蒙PC 应用靠什么保证「收起可找回、点击有着落、界面不撒谎」?

二、逐张读图:鸿蒙PC 桌面上的五个标签页

五张图对应五个标签页,刚好是这套工作台的五个视角:舞台(有哪些窗口)、台账(每个应用的泊位编排)、泡区(Dock 右端的气泡状态)、偏好(Dock 行为开关)、日志(操作轨迹)。

图 1:桌面舞台——五个窗口、两个已泊入

鸿蒙PC 真机完整桌面:泊坞桌面舞台,五个窗口卡片与底部程序坞

图 1 鸿蒙PC 真机完整桌面:顶部系统状态栏,底部系统 Dock;前台「泊坞 · BERTHSIDE」自上而下是品牌顶栏(右侧两枚读数「桌面窗口 5」「已泊入 2」)、五标签导航、桌面舞台(五张窗口卡片)、底部程序坞

图 1 是信息密度最高的一帧。结构自外向内四层。

第一层是系统给的窗口装饰:左上角标题「泊坞」与图标,右上角最小化、最大化、关闭三枚按钮。应用没有自绘标题栏——拖拽移动、双击最大化、边缘缩放、拖到屏幕边缘分屏,全部交给鸿蒙PC 的窗口管理器。这是 2in1 上最省力也最不容易和系统手势打架的选择。很多桌面应用喜欢自绘标题栏,结果双击标题栏不最大化、拖到边缘不触发分屏,用户第一分钟就会判定「这不是个正经桌面软件」。

第二层是品牌顶栏:左侧「泊」字圆形徽标加「泊坞 · BERTHSIDE」标题与副标题「任务栏程序坞与窗口收纳工作台」;右侧两枚胶囊读数——青色「桌面窗口 5」、莓红「已泊入 2」。这两个数字是整篇文章的核心口径:5 + 2 = 7 个窗口 = 演示数据里的 7 条 WinPane。把「桌面上还有几个、Dock 里藏了几个」做成常驻读数,是桌面工作台跟手机应用最直观的差别:手机一屏只干一件事,桌面一屏要同时回答「我在哪、还有多少没收」。

第三层是五标签导航:桌面舞台、泊位管理、托盘泡区、汽水偏好、开瓶志,选中项用青色底加墨色 2 vp 描边,未选中项只有一个灰点。这排标签本质上是一个 SodaView 联合类型的状态机——'stage' | 'berth' | 'tray' | 'prefs' | 'log',Index.ets 里用 if / else if 链把五个视图挂到同一个内容区上。

第四层是桌面舞台本体:Flex 换行铺开的五张窗口卡片,每张 250 vp 宽、16 vp 圆角、16 vp 内边距,卡片顶部是三个彩色小圆点(莓红、焦糖、青柠,模拟窗口红绿灯)、右上角是该应用的字形,中间是标题(如「长文草稿 · 第五章」)与副标题(「文稿 · 聚焦中」),底部一排三个操作:「泊入」胶囊、「聚焦」胶囊、右上角「✕」。

当前有焦点的「长文草稿 · 第五章」用2.5 vp 莓红描边 + 14 半径阴影 + 更亮的底色标出,其余四张是 1 vp 浅线描边 + 6 半径阴影。这一套「描边粗细 + 阴影半径 + 底色亮度」三重叠加的聚焦态,比单纯改一个背景色更容易在满是奶油色的界面上被一眼识别——桌面屏幕上窗口多、颜色近,聚焦态必须同时改变结构(边框)与深度(阴影),只改色是辨认不出来的。

底部程序坞分四段:左边四个固定泊位(文稿、图库、画坊、消息,其中「消息」右上角挂着红色数字 1,表示该应用有一个窗口泊在 Dock 里);一条 64 高竖分隔线;右边临时泊位(终端);Blank() 撑开剩余空间;最右端四个托盘汽泡(电量、收件、同步、护眼),带角标的那些就是「可清泡」的。

这一帧最值得抄走的不是配色,而是把「窗口」和「应用」拆成两层模型:DockApp 描述泊位(是否固定、是否运行),WinPane 描述窗口(属于哪个应用、是否泊入、是否有焦点)。一个应用可以有多个窗口、可以有窗口泊入但桌面无窗口、也可以完全退出。混成一个扁平列表,是桌面交互最早崩掉的地方。

图 2:泊位管理——固定泊位与临时泊位是两种契约

鸿蒙PC 真机完整桌面:泊位管理台账,六个应用的固定与临时泊位

图 2 鸿蒙PC 真机完整桌面:泊位管理页六行台账,前四行「固定泊位」(文稿、图库、画坊、消息),后两行「临时泊位」(终端、音乐);固定行右侧按钮是「解固定」,临时行是「钉入固定」

图 2 把 Dock 的「分组规则」实体化成了可读文字。每行左侧是应用字形圆(运行中的填色 + 焦糖环,未运行的是浅色底 + 细线),中间两行文字:应用名 + 一行状态明细,右侧一枚按钮。

状态明细是这套模型最好的自证材料:

  • 「文稿」:固定泊位 · 窗口 1 · 运行中
  • 「图库」:固定泊位 · 窗口 1(没有「运行中」——它的窗口还开着,但代码里 a.running 为 false 的演示数据恰好如此,说明泊位状态与运行状态是两个独立字段)
  • 「消息」:固定泊位 · 窗口 1(1 泊入)· 运行中——括号里那个 1 就是图 1 顶栏「已泊入 2」的其中一项
  • 「终端」:临时泊位 · 窗口 1(1 泊入)· 运行中——这是图 1 里被分隔线隔到右边的那一个
  • 「音乐」:临时泊位 · 窗口 1——pinned: false、running: false,所以它在 Dock 上根本不出现,只在台账里留了一条「有过窗口」的记录

这张图解释了一个很容易被忽略的设计决策:固定泊位与临时泊位不是视觉分组,而是两种生命周期契约。固定泊位应用即使一个窗口都没有,图标也常驻 Dock(用户随时能点开);临时泊位应用只在「有窗口在跑」时出现,最后一个窗口关闭就自动消失。这份差别就写在 closeWin() 里那四行:如果是该应用的最后一个窗口,且应用没被固定,就把 running 置回 false,图标从 Dock 上退场。

图 3:托盘泡区——Dock 右端的气泡也要有归宿

鸿蒙PC 真机完整桌面:托盘泡区四行气泡状态与清泡按钮

图 3 鸿蒙PC 真机完整桌面:托盘泡区四行——汽水情绪·电量(平静)、收件气泡(3 封未读,清泡)、同步汽泡(1 项同步,清泡)、夜航护眼(21:30 自动开启,平静)

图 3 是「小信息」的归宿。桌面右下角一排小圆图标是系统托盘,应用也可以有自己的托盘区。这套工程把它做成 TrayPop:name / glyph / badge / detail 四个字段,badge > 0 时行尾出现「清泡」按钮,badge === 0 时显示绿色「平静」二字。

这个页面的价值不在于好看,而在于它揭示了角标是一份需要被回收的状态:Dock 上的红点、托盘里的未读数,如果不提供「清零」入口,就会变成永远消不掉的红点焦虑。clearPop() 做的就是把 badge 置 0、detail 改写成「已清泡,暂无新消息」,然后 this.pops = this.pops.slice() 换引用触发刷新。

图 4:汽水偏好——开关必须先声明「它管什么」

鸿蒙PC 真机完整桌面:汽水偏好五项开关,前三项开启,后两项关闭

图 4 鸿蒙PC 真机完整桌面:汽水偏好五项——泊入时缩成汽水珠(开)、悬停泛起汽泡预览(开)、运行中显示果肉环(开)、新窗口自动占位(关)、双击图标起泡聚焦(关)

五个开关是本工程最诚实的部分,也是最不诚实的地方。

诚实的是文案:每一项都用一句话说清楚「开了会发生什么」——「窗口最小化后缩为 Dock 上的彩色气泡」「光标停在图标上 300ms 弹出窗口缩略」「运行中的应用图标外圈加果肉色环」「首次打开未固定的应用自动挤入泊位」「双击 Dock 图标将其全部窗口前置聚焦」。桌面应用的行为开关最怕「开了没感觉」,所以每句都带了一个可观测的结果。

不诚实的地方是接线:togglePref() 只做了三件事——翻转 p.on、this.prefs = this.prefs.slice()、弹一个「已启用 / 已停用」吐司。前三个开关对应的视觉在别处被硬编码实现了(果肉环就是 DockBar 里那句无条件的 strokeWidth(3)),后两个干脆没有任何消费方。这就是图 4 里后两项是灰色(演示数据初始 false)却「拨了也没反应」的原因。第八章会把它们逐个接上。

图 5:开瓶志——把「窗口去哪了」写成时间线

鸿蒙PC 真机完整桌面:开瓶志四条操作轨迹,最新在最前

图 5 鸿蒙PC 真机完整桌面:开瓶志四条——21:48 泊入「团队频道」缩成汽水珠泊入 Dock、21:40 开瓶「长文草稿·第五章」起泡聚焦、21:32 固定「终端」钉入固定泊位、21:21 离泊「播放列表·冰镇」从 Dock 还原

图 5 是整套模型的收口。每行四段:时间、动作徽章(泊入 / 开瓶 / 固定 / 离泊,四种颜色)、描述文字。最新的那行底色加深、描边加粗。

它同时解决了桌面交互里最难回答的问题:「我的窗口刚才去哪了?」 用户点了「泊入」,卡片从舞台上消失了;如果没有一条「「团队频道」缩成汽水珠泊入 Dock」的记录,用户只会觉得「窗口被删了」。Index.ets 里的 log() 只有一行代码,却把每一次状态变更都变成可回看的证据:

private log(action: string, text: string): void {
  this.logs = [new LogFizz(this.now(), action, text)].concat(this.logs).slice(0, 40);
}

注意这里用的是 concat 而不是数组展开 [...this.logs],并且用 slice(0, 40) 做了长度上限——这两点都不是风格偏好,而是 ArkTS 的硬约束与内存纪律,第十一章会讲。

把五张图连起来,一条桌面交互的因果链就出来了:窗口数量(图 1)决定舞台密度 → 泊位契约(图 2)决定图标何时出现 → 角标(图 3)决定用户要不要回来 → 行为开关(图 4)决定下一次点击的语义 → 日志(图 5)决定用户还信不信这个应用。 后面六章就按这条链逐段拆。

三、窗口三态与四条不变式

先看数据模型。Models.ets 里两个类,恰好对应「泊位」与「窗口」两层:

/** 停靠应用(Dock 泊位) */
export class DockApp {
  id: string;
  name: string;
  glyph: string;
  hue: string;
  pinned: boolean;     // 固定泊位 / 临时泊位
  running: boolean;    // 是否有窗口在跑
  // ... constructor 略
}

/** 桌面上的窗口 */
export class WinPane {
  id: string;
  title: string;
  appId: string;
  appName: string;
  glyph: string;
  hue: string;
  berthed: boolean;    // 是否泊入 Dock
  focused: boolean;    // 是否有焦点
  // ... constructor 略
}

两个字段就是窗口的三态判据:(berthed, focused) 组合出三种合法状态——桌面上有焦点、桌面上无焦点、泊入 Dock;第四种组合 berthed === true && focused === true 必须被禁止(一个被收进 Dock 的窗口不可能拿着键盘焦点)。这就是第一条不变式。

DockApp 那边还有一条:pinned 与 running 相互独立,固定泊位可以没在跑,临时泊位必须在跑。这解释了图 2 里「图库」有窗口但没写「运行中」的矛盾观感——那份演示数据本身就是一组刻意的反例。

第三条不变式是焦点唯一性:全场最多一个 focused === true。第四条是口径一致:桌面窗口 N + 已泊入 M 必须恒等于 wins.length。第四条写起来只有一行,但它是最容易被自己骗的地方——图 1 里 5 + 2 = 7,与 SodaData.wins() 的 7 条数据严丝合缝,这不是巧合,而是顶栏读数的实现方式决定的:

SodaBar({
  active: this.view,
  onPick: (v: SodaView) => {
    this.view = v;
  },
  openWins: this.wins.length - this.berthedCount(),
  berthed: this.berthedCount()
})

两个读数都从同一个数组派生,所以不可能对不上。「不要为可派生的事实存状态」,这条比任何布局技巧都值钱。

再看三个事件的实现。这是 Index.ets 里「泊入」的原文:

private berth(winId: string): void {
  const w = this.winOf(winId);
  if (w === null || w.berthed) {
    return;
  }
  w.berthed = true;
  w.focused = false;
  this.wins = this.wins.slice();
  this.log('泊入', `「${w.title}」缩成汽水珠泊入 Dock`);
  this.toast(`「${w.title}」已泊入 Dock`);
}

「还原」则是先把 berthed 清零,再把全场 focused 按 id 全量重写,最后用 wasBerthed 区分两种文案(从 Dock 回来叫「离泊」,本来就在桌面上叫「开瓶聚焦」):

private restore(winId: string): void {
  const w = this.winOf(winId);
  if (w === null) {
    return;
  }
  const wasBerthed = w.berthed;
  w.berthed = false;
  for (const x of this.wins) {
    x.focused = x.id === winId;
  }
  this.wins = this.wins.slice();
  if (wasBerthed) {
    this.log('离泊', `「${w.title}」从 Dock 还原并聚焦`);
    this.toast(`「${w.title}」已还原`);
  } else {
    this.log('开瓶', `「${w.title}」聚焦`);
  }
}

这里有一个可以抄走的技巧:焦点用「全量置位」而不是「增量清除」。常见写法是「先把上一个聚焦的窗口 focused = false,再把新的置 true」,看起来省一次遍历,但只要有一处忘了清,就会出现两个窗口同时描红。全量重写把「焦点唯一」从调用者的自觉变成了代码的结构——不管之前有多少个 true,走完这个循环只剩一个。launch() 里也是同样的写法(先全清,再给新窗口置 true)。

但「泊入」破坏了第三条不变式的一半:它把 focused 置 false,却没有把焦点交给别人。于是泊入之后会出现「桌面上一个聚焦窗口都没有」的状态——视觉上所有卡片都是浅线描边,用户不知道键盘焦点在哪。修法是把「交棒」抽成一个私有方法:

/** 焦点不变式:把焦点交给桌面上第一个窗口(排除 exceptId),其余置 false */
private handOverFocus(exceptId: string): void {
  let picked: string = '';
  for (const w of this.wins) {
    if (!w.berthed && w.id !== exceptId) {
      picked = w.id;
      break;
    }
  }
  for (const w of this.wins) {
    w.focused = picked !== '' && w.id === picked;
  }
}

private berth(winId: string): void {
  const w = this.winOf(winId);
  if (w === null || w.berthed) {
    return;
  }
  w.berthed = true;
  this.handOverFocus(winId);
  this.wins = this.wins.slice();
  this.log('泊入', `「${w.title}」缩成汽水珠泊入 Dock`);
  this.toast(`「${w.title}」已泊入 Dock`);
}

注意 handOverFocus 里 picked 初始为 '',意味着「全桌都泊入」时允许 0 个焦点——这正好对应舞台的空态(「桌面空了——所有窗口都泊在 Dock 里」)。所以不变式应该写成**「0 或 1」**,而不是「恰好 1」。设计不变式的时候,把空态写进去,比事后补一个 if 要好。

四、程序坞:四段结构、一条分隔线、一份宽度预算

桌面交互的骨架其实是「几段横向空间怎么分」。DockBar 的根节点是一个 Row,里面只有五样东西:

Row({ space: 10 }) {
  Row({ space: 2 }) {
    ForEach(this.apps.filter((a: DockApp) => a.pinned), (a: DockApp) => {
      this.appSlot(a)
    }, (a: DockApp) => `${a.id}-${a.running}-${this.berthedWins(a.id).length}-${this.hoverAppId}`)
  }

  Divider().vertical(true).height(64).color(SodaColors.line)

  Row({ space: 2 }) {
    ForEach(this.apps.filter((a: DockApp) => !a.pinned && a.running), (a: DockApp) => {
      this.appSlot(a)
    }, (a: DockApp) => `${a.id}-run-${this.berthedWins(a.id).length}-${this.hoverAppId}`)
    if (this.apps.filter((a: DockApp) => !a.pinned && a.running).length === 0) {
      Text('临时泊位空')
        .fontSize(12)
        .fontColor(SodaColors.inkFaint)
        .padding({ left: 10, right: 10 })
    }
  }

  Blank()

  Row({ space: 10 }) {
    ForEach(this.pops, (p: TrayPop) => {
      // 38 vp 圆 + 右上角角标
    }, (p: TrayPop) => `${p.id}-${p.badge}`)
  }
}
.width('100%')
.height(SodaMetrics.dockHeight)   // 112
.padding({ left: 18, right: 18 })
.backgroundColor(SodaColors.card)
.border({ width: { top: 3 }, color: SodaColors.ink })
.shadow({ radius: 12, color: 'rgba(58,46,42,0.18)', offsetY: -4 })

四段的分工值得逐条对照:固定泊位(pinned)→ 分隔线 → 临时泊位(!pinned && running)→ 弹性空白 → 托盘泡区。中间的 Blank() 是唯一带弹性的节点,它把所有「弹性」集中在一个位置,其余三段都是内容驱动宽度。这是桌面工具栏最稳的分配方式:内容多的时候挤压的是空白,而不是把图标挤成一条缝。

Space 也有讲究:外层 space: 10 是段间距,段内 space: 2 是图标间距。图标本身 52 vp 圆 + 6 vp 左右内边距,所以一个泊位的实际横向占用是 52 + 12 + 2 = 66 vp。8 个应用全在跑、全展示的情况下,左两段需要 8 × 66 = 528 vp;右侧四个托盘泡 4 × (38 + 10) = 192 vp;再加左右 18 vp 内边距和一条分隔线,Dock 的横向下限约 760 vp。这个数字很重要:一旦窗口被拖窄到 760 vp 以下,Row 不会自动换行,它会把固定宽度的子节点按原尺寸摆完、再把剩余空间压到 0,最右端的托盘泡就会被裁掉。

同理,桌面舞台那边的换行预算是另一组数字:卡片固定 250 vp,加右侧 12 vp 外边距,单张的横向步距是 262 vp;页面内边距 22 × 2 = 44 vp。要一行放下 N 张卡,需要窗口内容宽 ≥ 262N + 32 vp(最后一张不要外边距)。于是:

一行几张需要的内容宽度
3 张818 vp
4 张1080 vp
5 张(图 1 的实际状态)1342 vp
6 张1604 vp

图 1 里五张卡正好一行,说明当时的窗口内容宽 ≥ 1342 vp——在 2in1 全屏、系统缩放 150% 的机器上,这是一个很常见的逻辑宽度。反过来说,如果用户把窗口拖到 1080 vp,第五张卡会掉到第二行,舞台立刻从「一排」变成「四加一」,视觉秩序崩掉。这不是 bug,而是固定宽卡片 + FlexWrap 的必然结果。

所以「窗口与桌面基础交互」的第一个工程决策不是动效,而是最小可用窗口宽度:先把两条横向下限算出来(Dock 约 760 vp、舞台五列约 1342 vp),取大者作为 setWindowLimits 的 minWidth,再决定窄窗口下折叠谁。第九章给出的增量代码就把最小值钉在 1080 × 700 vp,理由是「四列仍可读,五列不强求」。

五、ForEach 键生成器:为什么 w.id 不够用

上一章的代码里有一处很扎眼的写法——三个 ForEach 的键生成器都塞了一堆状态位:

}, (a: DockApp) => `${a.id}-${a.running}-${this.berthedWins(a.id).length}-${this.hoverAppId}`)

键里出现了 running、泊入窗口数、甚至悬停的 hoverAppId。这不是作者在乱写,而是被 ArkUI 的 diff 机制逼出来的。

ArkUI 的 ForEach 用键来做列表复用:键不变,节点就不重建,只把数据对象换进去(走的是「更新」而不是「重建」)。而这里的 DockApp / WinPane 是类实例,this.wins = this.wins.slice() 换的只是数组引用,数组里的元素还是同一批对象引用。于是出现一个经典陷阱:

  1. 用户点「聚焦」,restore() 原地修改了 w.focused = true;
  2. slice() 换数组引用,触发 Index 重新 build();
  3. ForEach 拿到新数组,逐项比对键:w1-false-false → 现在还是 w1-false-false(键只由 id 和静态字段拼成);
  4. 键没变 → 该卡片不重建 → 描边和「· 聚焦中」文字不更新。

把状态位编进键,等于告诉框架「这个条目换了身份,请重建」。代价是真实的:每次焦点变化,两张卡被销毁重建;每次悬停,整个 Dock 的键生成器结果都变(因为键里带了 hoverAppId),八个图标全部重建。功能正确,但动画会断、滚动位置会丢、重建开销随图标数线性增长。

更彻底的修法是把「键」还原成只依赖身份(a.id),把「变化」交给子组件的属性观察。做法是把卡片拆成独立组件,用 @Prop 接收值语义的原始类型:

@Component
export struct PaneCard {
  @Prop title: string;
  @Prop appName: string;
  @Prop glyph: string;
  @Prop hue: string;
  @Prop focused: boolean;
  onBerth: () => void = () => {};
  doFocus: () => void = () => {};
  onClose: () => void = () => {};

  build() {
    Column({ space: 10 }) {
      // 三个红绿灯圆点 + 右上角字形
      Text(this.title)
        .fontSize(SodaText.sub)
        .fontWeight(FontWeight.Bold)
        .fontColor(SodaColors.ink)
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
      Text(this.appName + (this.focused ? ' · 聚焦中' : ''))
        .fontSize(SodaText.caption)
        .fontColor(this.focused ? SodaColors.berry : SodaColors.inkFaint)
      // 泊入 / 聚焦 / 关闭 三个操作
    }
    .width(250)
    .padding(16)
    .borderRadius(SodaMetrics.cardRadius)
    .backgroundColor(this.focused ? SodaColors.card : SodaColors.creamDeep)
    .border({ width: this.focused ? 2.5 : 1, color: this.focused ? SodaColors.berry : SodaColors.line })
    .shadow({ radius: this.focused ? 14 : 6, color: 'rgba(58,46,42,0.16)', offsetY: 4 })
  }
}

父组件只传值,键只写身份:

ForEach(this.openWins(), (w: WinPane) => {
  PaneCard({
    title: w.title,
    appName: w.appName,
    glyph: w.glyph,
    hue: w.hue,
    focused: w.focused,
    onBerth: () => this.onBerth(w.id),
    doFocus: () => this.doFocus(w.id),
    onClose: () => this.onClose(w.id)
  })
  .margin({ right: 12, bottom: 12 })
}, (w: WinPane) => w.id)

@Prop 是单向同步的深拷贝语义,父组件重渲染时按值比较更新子组件——这样「焦点从 A 换到 B」只触发两张卡片的属性刷新,而不是销毁重建,键也因此可以回到最朴素的 w.id。这就是 ArkUI 里「键管身份、属性管状态」的分工,跨平台框架层面它是通用的:任何声明式框架的列表复用,都把「身份」和「内容」分开了,混用就一定会在某处翻车。

六、点击语义:单击图标到底该发生什么

DockBar 里点击一个泊位的原文只有六行:

.onClick(() => {
  const bw = this.berthedWins(a.id);
  if (bw.length > 0) {
    this.onRestore(bw[0].id);
  } else {
    this.onLaunch(a.id);
  }
})

这段代码在演示里跑得通,但它把三件事糅成了一件:有泊入窗口就还原、否则就新开窗口。问题在于它完全忽略了「桌面已经有窗口」这种最常见的情况——如果一个应用在桌面上开着一个窗口、又泊入了一个窗口,用户单击图标,期望是「把桌面上那个顶上来」,实际却会从 Dock 里拉出一个另一个窗口。用户的感受是「我点了一下,结果多了一个窗口还换了内容」。

正确的语义应该按桌面惯例分三档,并且优先级固定:桌面已有窗口 → 聚焦它(不动 Dock 里的);桌面没有但有泊入 → 还原最近泊入的那个;一个都没有 → 启动新窗口。把它抽成一个纯函数,返回意图而不是直接改状态,是最容易测试的写法:

type DockIntent = 'focus' | 'restore' | 'launch';

private resolveDockClick(appId: string): DockIntent {
  let hasOpen: boolean = false;
  let berthedId: string = '';
  for (const w of this.wins) {
    if (w.appId !== appId) {
      continue;
    }
    if (w.berthed) {
      if (berthedId === '') {
        berthedId = w.id;      // 只记第一个,Dock 单击一次只还原一个
      }
    } else {
      hasOpen = true;
    }
  }
  if (hasOpen) {
    return 'focus';
  }
  if (berthedId !== '') {
    return 'restore';
  }
  return 'launch';
}

调用侧据此分发,并对「聚焦」补一个「把该应用最上层窗口顶上来」的处理。这里没有真正的 z-order,用一个约定代替:数组里最后出现的那个窗口就是最近激活的,因为 launch() 总是 concat 到末尾、restore() 不移动元素。于是聚焦可以写成:

private focusApp(appId: string): void {
  let picked: string = '';
  for (const w of this.wins) {
    if (w.appId === appId && !w.berthed) {
      picked = w.id;     // 最后一个即最近激活
    }
  }
  if (picked !== '') {
    this.restore(picked);
  }
}

顺带补上第三章那个 id 撞车的坑。launch() 现在写的是:

const id = `n${this.wins.length + 1}-${a.id}`;

窗口 7 个时关掉两个,wins.length 变成 5,再开新窗口得到 n6-...,而历史里可能已经有一个 n6-... 被关掉了——只要它还在某个 ForEach 的 diff 缓存里,就会出现「两个条目同一个键」。正确写法是一个单调递增的序号,且只增不减:

private seq: number = 0;

private nextWinId(appId: string): string {
  this.seq += 1;
  return `n${this.seq}-${appId}`;
}

这类「用长度当 id」的写法在列表类需求里极其常见,它的错误还要等用户反复开关窗口之后才会显形——上线前几乎测不出来。凡是 id,就必须是单调源,而不是集合的尺寸。

七、悬停与双击:桌面 affordance 该放在哪一层状态里

鼠标是鸿蒙PC 与手机最大的输入差异:手指没有「悬停」,鼠标有。DockBar 用 onHover 做了最轻的一种反馈——悬停时把该泊位的文字从灰色改成墨色、字重从常规改粗:

Text(a.name)
  .fontSize(12)
  .fontColor(this.hoverAppId === a.id ? SodaColors.ink : SodaColors.inkFaint)
  .fontWeight(this.hoverAppId === a.id ? FontWeight.Bold : FontWeight.Normal)

但 hoverAppId 现在挂在 Index 的 @State 上,由 DockBar 通过回调 doHover 往上传:

@State hoverAppId: string = '';
// ...
doHover: (appId: string) => {
  this.hoverAppId = appId;
}

这是一个状态放错层的典型例子。鼠标每滑过一个图标,父组件就改一次 @State,Index.build() 整棵树重跑一遍:顶栏两个读数重新计算、五张窗口卡片全部重新 diff、程序坞八个图标加四个托盘泡全部重新生成键。一次悬停 → 十几次键生成器调用。悬停是高频事件(滑过五个图标就是五次),这条路径会成为桌面交互里最先发热的地方。

修法是把悬停状态下沉到真正需要它的组件里,父组件不再参与:

@Component
export struct DockBar {
  @State private hoverAppId: string = '';
  @State private peekAppId: string = '';
  private peekTimer: number = -1;

  build() {
    // ... appSlot 里直接改自己的状态
  }

  aboutToDisappear(): void {
    if (this.peekTimer >= 0) {
      clearTimeout(this.peekTimer);
      this.peekTimer = -1;
    }
  }
}

「状态放在使用它的最小公共祖先」 这句话在声明式 UI 里不是口号,而是性能曲线:状态每上移一层,重渲染的面积就扩大一圈。判断标准很简单——如果这个状态只有一个组件读,就不该放在父组件的 @State 里。

下沉之后,「悬停泛起汽泡预览」这个偏好(图 4 的第二项)才有地方落脚。300ms 的延迟预览需要定时器,且必须在离开时取消:

.onHover((h: boolean) => {
  this.hoverAppId = h ? a.id : '';
  if (this.peekTimer >= 0) {
    clearTimeout(this.peekTimer);
    this.peekTimer = -1;
  }
  if (h) {
    this.peekTimer = setTimeout(() => {
      this.peekAppId = a.id;
    }, 300);
  } else {
    this.peekAppId = '';
  }
})

这段代码有一个容易被忽略的细节:先清定时器,再判断是否启动新的。如果反过来写,快速滑过五个图标会留下五个待触发的定时器,300ms 后同时把 peekAppId 写成五个不同的值,最后弹出的是哪个纯看执行顺序。Index.ets 里的吐司已经用了同一套模式(toastTimer 先 clearTimeout 再 setTimeout),这是可以复用的最小纪律。

双击则是另一个层级的语义。桌面惯例里,单击 = 打开/聚焦,双击 = 对「该应用的全部窗口」做一次操作(这里是「全部前置聚焦」)。ArkUI 里不要用 onClick + TapGesture({ count: 2 }) 混搭,两者会互相抢事件;正确做法是用 GestureGroup 的互斥模式,并把双击排在前面:

.gesture(
  GestureGroup(GestureMode.Exclusive,
    TapGesture({ count: 2 })
      .onAction(() => {
        if (this.dblFocus) {
          this.onFocusAll(a.id);
        }
      }),
    TapGesture({ count: 1 })
      .onAction(() => {
        this.onSlotClick(a.id);
      })
  )
)

必须诚实说明代价:互斥组里等双击,会让每一次单击都延迟到双击判定超时(约 300ms)。在 Dock 这种「点了就要有反应」的位置上,300ms 的迟滞是很明显的。所以在演示工程里它是个默认关闭的偏好开关(图 4 第五项,灰的);如果要默认开启,更稳的做法是保留单击的 onClick 走「聚焦/还原」,把「全部前置」挂到右键菜单(bindMenu)或 Ctrl + 单击 上,让高频路径不背延迟。

八、把偏好开关从装饰变成契约

图 4 那五个开关,只有真正被某个渲染分支消费,才算「契约」。给 Index.ets 加一个查询方法,把「开关 id」翻译成布尔值:

private prefOn(id: string): boolean {
  for (const p of this.prefs) {
    if (p.id === id) {
      return p.on;
    }
  }
  return false;
}

然后把它作为属性传给子组件,让子组件在自己的渲染里判断,而不是把 prefs 整份数组传下去:

DockBar({
  apps: this.apps,
  wins: this.wins,
  pops: this.pops,
  showRing: this.prefOn('p3'),      // 运行中显示果肉环
  popOnBerth: this.prefOn('p1'),    // 泊入时缩成汽水珠
  hoverPeek: this.prefOn('p2'),     // 悬停泛起汽泡预览
  dblFocus: this.prefOn('p5'),      // 双击图标起泡聚焦
  onLaunch: (appId: string) => {
    this.launch(appId);
  },
  // ... 其余回调
})

对应的渲染分支改两处。果肉环(p3)现在是硬编码的:

Circle({ width: 52, height: 52 })
  .fill(a.running ? a.hue : SodaColors.creamDeep)
  .stroke(a.running && this.showRing ? SodaColors.caramel : SodaColors.line)
  .strokeWidth(a.running && this.showRing ? 3 : 1)

汽水珠(p1)则决定「泊入窗口数」这个小角标长什么样:开的时候是一枚莓红实心珠 + 白色数字,关的时候退化成一个小墨点,避免用户一眼看到一堆红点:

if (this.berthedWins(a.id).length > 0) {
  if (this.popOnBerth) {
    Circle({ width: 16, height: 16 }).fill(SodaColors.berry)
      .position({ x: 36, y: -2 })
    Text(`${this.berthedWins(a.id).length}`)
      .fontSize(10)
      .fontColor(SodaColors.cream)
      .fontWeight(FontWeight.Bold)
      .position({ x: 36, y: -2 })
      .width(16)
      .height(16)
      .textAlign(TextAlign.Center)
  } else {
    Circle({ width: 8, height: 8 }).fill(SodaColors.inkDim)
      .position({ x: 42, y: 2 })
  }
}

「新窗口自动占位」(p4)是唯一一个改数据而不是改样式的开关,它要写在 launch() 里:

private launch(appId: string): void {
  const a = this.appOf(appId);
  if (a === null) {
    return;
  }
  const id = this.nextWinId(a.id);
  const win = new WinPane(id, `${a.name} · 新窗口`, a.id, a.name, a.glyph, a.hue, false, false);
  for (const x of this.wins) {
    x.focused = false;
  }
  win.focused = true;
  this.wins = this.wins.concat([win]).slice();
  if (!a.running) {
    a.running = true;
  }
  if (!a.pinned && this.prefOn('p4')) {
    a.pinned = true;                                     // 首次打开即挤入固定泊位
  }
  this.apps = this.apps.slice();
  this.log('开瓶', `「${a.name}」打开新窗口`);
  this.toast(`「${a.name}」新窗口已开`);
}

这里有一处必须顺手改的文案联动:DockBar 里那句「临时泊位空」的前提是「存在未固定且未运行的槽位」。p4 打开后,所有开过一次的应用都会被钉住,这行字大概率再也不会出现,而用户会以为「临时泊位坏了」。正确做法是把提示改成随开关变化的两句话——开关开时显示「临时泊位已并入固定泊位」,关时保留原文。开关不只改行为,还要改解释行为的文案,这是「装饰变契约」的最后一步。

九、把窗口接进来:window 模块的四个接点

前面八章都在讲「内容区里的桌面交互」。真正让应用变成「桌面应用」的,是窗口本身。当前 EntryAbility.ets 只有 24 行:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', () => {
    });
  }
}

下面这段是增量代码,未进入当前构建(当前 HAP 仍由系统默认窗口装饰管理),接口以 API 26 为准,落地前请在真机验证:

import { UIAbility } from '@kit.AbilityKit';
import { window, display } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN: number = 0x0B01;
const TAG: string = 'Berthside';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err: BusinessError) => {
      if (err.code) {
        hilog.error(DOMAIN, TAG, 'loadContent failed: %{public}s', err.message);
        return;
      }
      this.tuneDesktopWindow(windowStage);
    });
  }

  private tuneDesktopWindow(stage: window.WindowStage): void {
    // window 模块的尺寸单位是 px,不是 vp;必须按屏幕密度换算
    const density: number = display.getDefaultDisplaySync().densityPixels;
    const vp2pxLocal = (vp: number): number => Math.round(vp * density);

    try {
      const win: window.Window = stage.getMainWindowSync();

      // 接点 1:最小可用窗口 + 尺寸上限
      win.setWindowLimits({
        minWidth: vp2pxLocal(1080),
        minHeight: vp2pxLocal(700),
        maxWidth: vp2pxLocal(3840),
        maxHeight: vp2pxLocal(2160)
      }).catch((e: BusinessError) => {
        hilog.error(DOMAIN, TAG, 'setWindowLimits: %{public}s', e.message);
      });

      // 接点 2:恢复上次尺寸
      const w: number = AppStorage.get<number>('berthside.width') ?? vp2pxLocal(1440);
      const h: number = AppStorage.get<number>('berthside.height') ?? vp2pxLocal(900);
      win.resize(w, h).catch((e: BusinessError) => {
        hilog.error(DOMAIN, TAG, 'resize: %{public}s', e.message);
      });

      // 接点 3:尺寸变化写回(下一次启动接着用)
      win.on('windowSizeChange', (size: window.Size) => {
        AppStorage.setOrCreate('berthside.width', size.width);
        AppStorage.setOrCreate('berthside.height', size.height);
      });

      // 接点 4:窗口焦点与界面里的「聚焦中」对齐
      stage.on('windowStageEvent', (type: window.WindowStageEventType) => {
        if (type === window.WindowStageEventType.INACTIVE) {
          AppStorage.setOrCreate('berthside.active', false);
        } else if (type === window.WindowStageEventType.ACTIVE) {
          AppStorage.setOrCreate('berthside.active', true);
        }
      });
    } catch (e) {
      const err: BusinessError = e as BusinessError;
      hilog.error(DOMAIN, TAG, 'window setup failed: %{public}s', err.message);
    }
  }
}

四个接点各有讲究:

接点 1(setWindowLimits) 是把第四章算出来的「舞台五列 1342 vp、Dock 760 vp」变成硬约束。最小值按「四列仍可读」定在 1080 × 700 vp,而不是硬扛五列——下限要按「最差可接受」定,不要按「最漂亮」定。

接点 2(resize) 单位是 px,这是最容易踩的坑:直接写 resize(1440, 900) 在 density 1.5 的机器上只有 960 × 600 vp 的内容宽度,窗口打开就掉到三列。写 vp2px 换算,resize 的参数才是用户看到的尺寸。

接点 3(windowSizeChange) 是「窗口尺寸是连续信号」的具体体现。用户拖边缘是逐帧事件,把每次的 size 落盘当然不划算,但只落盘最后一次又需要防抖;最简单可靠的做法是用 AppStorage 存内存态,用 preferences 在 onBackground() 时落一次盘。AppStorage 只在内存,重启就没了,这一点不要记错。

接点 4(windowStageEvent) 解决的是一个很微妙的界面撒谎问题:应用窗口失焦(用户点开了 DevEco Studio)时,界面里那张卡片仍然写着「· 聚焦中」。把 ACTIVE / INACTIVE 映射到一个 @StorageProp,就能在失焦时把「聚焦中」降级成普通文字:

@StorageProp('berthside.active') active: boolean = true;

// 卡片里
Text(w.appName + (w.focused && this.active ? ' · 聚焦中' : ''))

应用内的焦点 ≠ 窗口的焦点,这两个概念在鸿蒙PC 上必须分清:前者是「哪个窗口卡片被选中」,后者是「操作系统的键盘焦点在哪个窗口」。混为一谈,用户切走再切回来就会看到两套互相矛盾的聚焦态。

十、ArkUI 视角:跨平台框架能给什么,必须按平台写什么

这一章把话说明白,因为「跨平台框架」这个词在鸿蒙语境下经常被误用。

本文的技术栈是 ArkUI,不是 ArkUI-X。 ArkUI 是鸿蒙原生的声明式 UI 框架(配 ArkTS 语言),能力边界是「一次开发,多设备形态部署」——手机、平板、PC/2in1、车机共用同一套声明式语法与状态模型,这属于跨设备;ArkUI-X 则是在 ArkUI 之上的一层跨平台扩展,用于把声明式 UI 复用到 Android / iOS 上。本文一行 ArkUI-X 代码都没有,也没有跨端壳工程,module.json5 里只声明了 deviceTypes: ['2in1']。

之所以仍然要谈「跨平台框架」的能力边界,是因为这份工程里的每一行代码都可以被追问一句:「换个端、换个设备形态,它还成立吗?」把答案列成表,比空谈「一份代码多端运行」有用得多:

能力归属换设备 / 换端时能不能带走
Row / Column / Flex + layoutWeight / BlankArkUI 布局引擎语法可带走,但宽度预算必须重算(本文 1342 vp 只在 2in1 成立)
@State / @Prop / @StorageProp / @BuilderArkUI 状态与渲染可带走,这是跨平台框架最稳的一层
ForEach 键生成器与 diff 复用ArkUI 渲染管线可带走(键管身份、属性管状态的模型是通用的)
onClick / onHover / GestureGroup(TapGesture)ArkUI 事件抽象语义可带走;onHover 在触摸设备上永远不触发,必须给点击兜底
deviceTypes: ['2in1']应用包配置必须按平台写,它决定应用能不能装在 PC 上
window.resize / setWindowLimits / windowStageEvent设备形态能力(2in1)必须按平台写,手机上没有「可缩放窗口」这回事
系统 Dock / 托盘 / 窗口装饰操作系统完全不可替代,只能适配不可自绘
键盘 Tab 顺序与回车激活输入设备需要显式接线,声明式框架不会自动帮你排

这张表解释了一个常见误解:用 ArkUI 写的东西「看起来」跨设备,实际上只有布局与状态是跨的,窗口与桌面是平台的。 一个能在手机、平板、PC 上都跑起来的 ArkUI 应用,到了 PC 上仍然要单独回答「窗口最小尺寸是多少、最小化之后去哪、托盘角标怎么清零」——这三件事没有一行代码可以跨设备复用,因为它们描述的不是界面,而是桌面这个操作系统的习惯。

反过来说,这也正是本文这套「泊坞」模型的价值:DockApp / WinPane / TrayPop 这三个数据类与它们的不变式(焦点唯一、口径守恒、id 单调)是框架无关的,换到任何跨平台框架里都成立;只有那些 window.* 调用是 2in1 独有的。把代码按这条线切成「模型层 / 视图层 / 平台层」,就是桌面应用能长期维护的关键。

十一、复现清单与十条踩坑

复现这份工程只需要三步:DevEco Studio 打开 项目源码/Berthside_ohos 的工程根目录(不是 entry)→ 配好 API 26 的 SDK 与自动签名 → 选择 2in1 设备运行。bundleName 是 com.berthside.dock,如果本机装过同包名的旧版本,先卸载再装(versionCode 相同的包会被 install 拒绝)。

下面十条都是这份工程实际踩出来的:

  1. ArkTS 禁止数组展开。[...this.logs] 这类写法要改成 [x].concat(this.logs),log() 里的那一行就是这么来的;同理对象字面量必须能推断出类型,否则 JSON.parse 出来的数组一展开就会让进程被杀。
  2. @State 数组里放类实例,改字段必须配 slice()。原地改 w.focused = true 不会触发刷新,this.wins = this.wins.slice() 换引用才会;两者缺一,界面就是死的。
  3. ForEach 的键必须包含所有影响渲染的状态位。只写 w.id 的话,焦点变化不会重建卡片——这是本项目最初「点聚焦没反应」的真正原因。
  4. 别把 hoverAppId 放进页面级 @State。鼠标滑过五个图标会让整页重渲染五次,把悬停状态下沉到 DockBar 内部即可。
  5. 不要用集合长度当 id。n${this.wins.length + 1}-${appId} 在反复开关窗口后一定撞车,改成单调递增的 seq。
  6. setTimeout 返回的是 number,用完必须 clearTimeout,并且在 aboutToDisappear() 里兜底清理,否则组件销毁后定时器仍会改已释放的状态。
  7. window.resize / windowSizeChange 的单位是 px,不是 vp。必须用 display.getDefaultDisplaySync().densityPixels 换算,否则窗口一打开就比预期小三分之一。
  8. 图标用 Unicode 字形省资源,但要固定盒模型。✎ ❏ ◆ ✦ ⌘ ♪ ◉ ▣ 这些字形在不同字重、不同字体下基线不一致,必须给 width / height / textAlign(TextAlign.Center),否则在 52 vp 的圆里会明显偏心。
  9. 真机截图要抓整屏,不要抓应用窗口。用 hdc shell uitest uiInput click <x> <y> 切标签,再用整屏快照,系统状态栏与系统 Dock 才会入镜——这是「一眼看出是鸿蒙PC」的唯一证据。
  10. deviceTypes 只写 2in1。写到手机上虽然能装,但程序坞的横向下限、卡片 250 vp 的固定宽度全都会失真,Dock 会挤成一条缝。

十二、桌面交互的六条验收标准

写到最后,把「什么样算做对了」写成可以逐条打勾的清单。这六条不依赖具体控件,也不依赖具体跨平台框架,属于桌面应用的通用契约:

  1. 口径守恒:任意时刻「桌面上打开的窗口数 + 已泊入数」都等于窗口总数,两个读数不允许各算各的。
  2. 焦点唯一且可解释:全场最多一个聚焦窗口;全桌泊入时允许零个,此时舞台必须显示明确的空态文案。
  3. 泊入可逆:每一次泊入都在日志里留下一条可读记录,并且能通过一次点击完整还原(包括原来的标题、所属应用与焦点)。
  4. 点击有确定语义:单击 Dock 图标只会在「聚焦 / 还原 / 启动」三者中选一个,且优先级固定,绝不产生用户没要求的新窗口。
  5. 窄窗不撒谎:窗口缩到 minWidth 时,卡片不重叠、Dock 不裁切、不出现横向抖动;被牺牲的只能是空白,不能是内容。
  6. 悬停有反馈且可撤销:指针进入 300ms 内有预览,离开立即消失;拖走窗口、切走应用之后再回来,不会残留一笔幽灵预览。

把这六条放到一起看,会发现它们全部指向同一件事:桌面交互的本质不是「多画几个窗口」,而是「维护一组用户能预测的状态」。 泊坞这套隐喻之所以好用,是因为它给每个状态都配了一个实物(泊位、汽水珠、气泡、开瓶志),用户不需要读文档就能猜到「窗口被收进哪儿了、怎么拿回来」。这也是 ArkUI 声明式框架给不了的——框架给的是表达状态的语法,状态本身怎么设计,还得照着桌面的习惯来。


源码与托管:工程目录 项目源码/Berthside_ohos(13 个手写 .ets,零三方依赖,oh-package.json5 无外部包)。如需开源复刻,建议以该目录作为初始提交推到 AtomGit(开源鸿蒙PC 社区组织下可直接申请新建项目),提交信息里注明「鸿蒙PC 窗口与桌面基础交互 · 程序坞窗口收纳」,方便后续按章节对应到提交。

一句话收尾:手机应用只需要回答「用户现在看到什么」,鸿蒙PC 应用还要回答「用户刚才收起来的那个窗口,现在躺在哪里」——把这个问题的答案写进模型、写进不变式、写进日志,桌面交互就成功了一半,剩下的一半交给 ArkUI 的声明式布局去算宽度。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐