crossdesk/docs/deskhub.md

# 桌面墙（DeskHub）

主窗口标题栏下方可以切换“连接”和“桌面墙”，菜单位于同一行右侧。每次启动软件默认进入“连接”页，不恢复上次退出时的页面；保存的位置会在窗口显示前恢复。连接页保留原有布局和紧凑尺寸；桌面墙可以调整尺寸及全屏。普通窗口切换模式时保持左上角位置，仅分别记忆尺寸。切回连接页会退出全屏并恢复普通窗口位置与紧凑尺寸，再进入桌面墙会恢复它的尺寸及全屏状态。已断开的显示器所对应的位置会修正到可用屏幕内。

全屏按钮通过短暂淡出、等待窗口尺寸稳定、淡入完成切换，常规总时长约 0.2 秒；过渡期间屏蔽设备操作与重复全屏点击。窗口尺寸变化会立即更新网格，避免在新窗口中先显示旧的行列布局。过渡复用现有 UI 更新循环，不启动嵌套事件循环；失败或超时会恢复内容与交互。

可见的普通窗口若低于连接页最小尺寸，桌面墙恢复上次有效大小，连接页恢复固定大小；最小化、隐藏和全屏窗口不会触发这一恢复。窗口恢复以实际尺寸确认完成，期间不记录过渡尺寸；macOS 的最大化恢复使用无动画原生窗口调整，避免系统缩放动画嵌套事件循环。

## 使用

- 在桌面墙中点“添加设备”，填写设备 ID、密码和可选的分组名称，再点“添加并连接”。密码仅用于本次连接，勾选“记住密码”才会通过原有凭据机制保存；不会写入桌面墙配置。
- “从最近连接添加”支持多选、全选和统一指定分组。导入后只加入桌面墙，使用“批量选择 → 连接”再发起连接。同一分组内重复设备会跳过；不指定分组时，已在桌面墙中的设备不会重复加入。
- 连接成功后立即记录在连接页的“最近连接”中，无需等到断开，也不要求记住密码。失败的连接不会新增最近记录。
- “全部设备”显示保存的成员及当前活动会话。分组成员与连接相互独立：断开后成员仍在，重启后不会自动连接。
- 卡片名称栏以文字标签显示“在线／离线”，与画面中的连接状态分开，不遮挡预览。在线状态订阅包含全部分组中的设备；尚未收到结果、结果过期或服务器断连时显示“未知”，已有活动连接的设备仍显示在线。
- 鼠标悬停时，名称栏右侧显示与近期连接一致的改名、修改分组、移除、连接／断开操作条，并显示按钮提示。两处的连接按钮均随实际会话状态切换：未连接时显示连接箭头，已连接时显示叉号，点击断开该设备；点卡片仍可查看设备。名称与近期连接共用别名；移除会先确认，只移除当前分组或桌面墙中的成员，不删除近期记录或断开会话。批量选择时隐藏操作条。
- 两处的“修改分组”共用操作条组件、分组弹窗和保存逻辑。可以选择多个已有分组、填写新分组，或选“未分组”清除分组归属。分组与桌面墙成员独立保存：近期连接修改分组不会自动加入桌面墙，也不会自动连接；通过“从最近连接添加”或“添加设备”才保存为桌面墙成员，未指定新分组时保留已有分组。从“全部设备”移除成员后仍保留其分组信息；在特定分组中移除则取消对应分组归属，移除最后一个分组后仍保留在“全部设备”中。修改分组保留墙内设备的顺序，保存失败时保留弹窗和输入。
- 近期连接的设备提示浮窗显示所属分组；多个分组并列显示并自动换行，没有分组时显示“未分组”。分组变更后自动刷新。
- “近期连接”标题行右侧可按“全部设备”、未分组或已有分组筛选；一个设备可出现在它所属的多个分组中。筛选与桌面墙当前分组独立，不改变历史记录、在线状态订阅或桌面墙成员。分组修改后自动更新结果；当前分组被清空删除时回到全部设备。
- 网格随窗口大小增加行列，紧凑窗口为 3 × 2；翻页不关闭连接。分组内顺序不会按在线状态自动重排。
- 点卡片进入只读放大视图，点“接管操控”才开始发送键鼠。点“释放操控”或按 Ctrl/⌘ + Shift + Esc 可以释放。切换设备、翻页、打开本地操作面板、切换模式及窗口失焦也会释放。
- 放大视图使用一行设备操作栏，只保留返回、设备名称、状态和接管／释放操控按钮；紧凑窗口的设备缩略图位于下方，宽窗口移到右侧。缩略图显示设备名、在线状态和当前设备标记，缺少画面或画面停滞时有状态占位；滚动条单独留出空间。调整尺寸后当前设备仍在列表中，选中时自动滚入可见区域。主预览和缩略图均完整等比显示，鼠标坐标按实际预览区域映射。
- 在“近期连接”中点击已连接设备的卡片画面，可打开原有独立串流窗口，使用声音、显示器切换、隐私屏、文件传输等完整单会话工具。关闭墙内设备的独立窗口不会断开墙中的会话。
- 批量选择复用固定底栏，设备卡片的位置和尺寸不变。底栏提供“全选”：选中当前筛选下的所有设备，跨页生效；全部选中后显示“取消全选”。翻页保留选择，切换分组清空选择；已选数量与跨页数量、连接／断开／分发文件及分页控件在同一底栏显示。断开和文件分发会先列出完整目标；提交后的操作目标不会跟随之后的选择变化。

## 预览与兼容性

桌面墙的所有已连接设备统一使用各自的交互画质、30／60 帧设置和降级策略。缩略图、放大查看、操控、翻页和隐藏窗口均不改变发送档位。新版两端通过 `supports_deskhub_preview` 同步订阅，视频按编码器协商的帧率发送，不再额外限帧；声音仍需明确开启。

为兼容旧版控制端，被控端仍接受暂停和 1／8 帧订阅；这些低帧率请求使用保持分辨率策略，避免套用交互视频的帧率与关键帧时延预算而反复缩小画面。当前桌面墙不再发出这些请求。

预览在解码回调中随收到的画面生成有界缩略图，可见桌面墙随 UI 刷新显示最新帧。UI 不处理全分辨率转换，只保留当前可见设备的最新预览，超过 5 秒未更新会标记停帧。画面保持比例，以完整矩形显示；外层圆角卡片与画面之间保留内边距，不裁切桌面内容或画面边角。实际显示帧率受设备性能与网络状况影响。

旧版被控端仍可连接，按其支持的交互视频策略发送。多设备同时发送交互视频会增加带宽和编解码负载。

## 批量操作

连接和文件分发最多并行启动 4 个操作。尚未开始连接的设备卡片显示“排队中”，轮到后自动切换为实际连接状态。断开立即执行，同时取消该设备排队中的操作及重连请求，不等待文件传输完成。单台等待密码不会阻塞其他设备，可以从对应设备的放大视图填写密码。连接状态显示在设备卡片上，文件传输详情可在该设备的独立串流窗口中查看。

批量操作仅在本次运行中执行，不提供任务列表、操作历史或重启后的恢复。成员资料与窗口状态保存在应用缓存目录的 `deskhub.json` 和 `deskhub.json.window` 中，不含设备密码和文件内容。

`deskhub.json` 第 2 版分别保存分组记录和桌面墙设备 ID。第 1 版配置仍可读取，原有桌面墙成员、分组和顺序会保留；旧版数据未记录加入来源，因此不会自动移除已有成员。

批量远程命令、重启尚未提供。实际大规模并发容量需要用真实设备测量。

## 验证

```sh
xmake build crossdesk
xmake run slint_ui_smoke_test
xmake run crossdesk_wire_test
xmake run keyboard_state_wire_test
```