SuperAPI AI 工具集

desktop-mini-player-window

前端与建站

查看项目

更新于 10-17 16:15

技能介绍

用途:该技能面向 Compose Desktop 媒体类应用,说明如何在不新建第二个应用的前提下,增加一个始终置顶、无边框的迷你播放控制窗口。迷你窗口作为同一应用 composition 中的另一个窗口存在,其显示与否由 composition 之外的一个布尔值控制,内容是读取与主窗口相同的状态持有者。

主要能力与实现要点:

  1. 单一状态源:通过 MiniPlayerManager.isOpen 这类可变状态控制窗口显隐,托盘菜单、应用内按钮和窗口自身关闭按钮都可直接翻转它,无需窗口句柄或消息传递。
  2. 共享状态持有者:把已有实例传入迷你窗口,不要为小窗口另建依赖作用域、视图模型或播放器引擎句柄,否则两个窗口可能给出不一致的状态。
  3. 关闭主窗口不等于退出应用:主窗口的关闭请求应路由为 visible = false,并保留唯一退出路径(例如托盘中的退出项),退出前先释放播放器。
  4. 回退策略一致:若主窗口在某些环境(如虚拟机)下回退为带装饰、不透明窗口,迷你窗口需要同样的回退,否则可能出现进程正常但窗口不可见。
  5. 拖动实现:无边框窗口需自行处理拖动。资料指出局部拖动增量在移动坐标系中累加会漂移抖动,建议在拖动开始时记录操作系统指针位置与窗口位置,之后每帧用绝对坐标计算;并给出 detectDragGestures 示例代码。
  6. 拖动区域避开缩放边角:拖动条只占顶边中段并设固定高度,同时设置移动光标作为可拖动提示。
  7. 最小尺寸:设在原生窗口上,单位为设备像素,需乘以显示缩放变换;在窗口内容存在后通过 LaunchedEffect 设置,仅在 Compose 层限制会导致原生缩放先变小再被纠正而出现闪烁。
  8. 几何持久化:仅绝对位置可写入,默认对齐方式无坐标需做类型保护;用不可能成为真实坐标的哨兵值表示从未保存;读取时将尺寸钳制到当前最小值;在拖动结束或防抖时持久化,避免按位置触发的 effect 在拖动每一步都写盘。
  9. 响应式控件集:按窗口约束分支布局(宽高比判断方形或高窗口,再按宽度阈值分紧凑、中等、完整),宽度不足时去掉可选按钮;悬停只用于视觉反馈,不能作为访问控件的唯一方式。
  10. 快捷键:在窗口上绑定播放控制键,只消费已处理的事件并返回 true,其余事件返回 false,以免破坏 Tab 焦点和其他快捷键。

使用方式:资料以代码片段展示 application 块中声明主窗口与条件渲染的 MiniPlayerWindow、MiniPlayerManager 对象、拖动手势与最小尺寸设置。未提供安装命令或完整工程配置。

适用场景:Compose Desktop 媒体播放器需要常驻小窗控制播放,并希望与主窗口共享播放状态。

限制与验证:资料给出 grep 检查命令(isOpen、exitApplication、alwaysOnTop/undecorated/transparent/MouseInfo/minimumSize、LaunchedEffect(windowState) 等)以及手工验证步骤:慢速拖动检查是否精确跟随、四角缩放、缩到最小尺寸检查闪烁、关闭主窗口确认迷你窗口与音频存活、重启确认位置与尺寸恢复、删除偏好确认首次默认位置。具体平台兼容性与驱动差异需以实际环境为准。