GPUI Deck

Hover Card

悬停时延迟显示的富内容预览、触摸长按预览、从触发器到卡片的指针移动、不移动焦点的焦点预览,以及关闭处理。

由 GPUI 的 Web 后端渲染的真实组件。需要支持 WebGPU 的浏览器。

HoverCard 为 Button 的普通操作提供一个丰富的、非交互式的预览。 请保留一个稳定的触发器焦点句柄,并创建 HoverCardState::new(&trigger_focus, window, cx)。观察该状态以重绘 使用方。可选的 .with_delays(open_duration, close_duration) 用于配置挂载之前 指针进入和离开的延迟;默认值为 500 毫秒和 200 毫秒。

HoverCard::new("preset-preview", &preview)
    .accessibility_label("Recording preset preview")
    .offset(px(6.))
    .trigger(|button| {
        button
            .accessibility_label("Recording preset. Edit settings")
            .on_click(open_settings)
            .child("Preset: Balanced")
    })
    .content(preview_surface)

触发器构建器会保留 Button 的操作,并提供其外观。 状态持有其焦点句柄和禁用状态;使用 set_disabled 来 协调预览和 Button。HoverCard 上的 Styled 方法作用于 宿主框架。请单独为应用提供的内容设置样式,并使用 .anchor(...) 和 .offset(...) 调整现有的 Popup 几何。

输入行为
指针进入触发器在进入延迟之后打开,且不移动焦点
指针离开触发器和卡片在离开延迟之后关闭,除非触发器仍保留键盘焦点
指针进入卡片或返回触发器取消延迟关闭
键盘焦点进入触发器立即打开;焦点仍停留在 Button 上
Escape关闭可见的预览,并在本次进入期间抑制重新打开
点击 / Enter / Space关闭预览;Button 或被点击的控件仍会执行其普通操作
焦点变化 / 窗口失去活动状态关闭,且不移动焦点

关闭延迟让指针可以越过触发器到卡片之间的间隙。通过键盘打开的 预览会保留到失焦或被显式关闭,即使指针移开也是如此。 Escape 会让焦点保持原位,并且不会仅因为绘制了另一帧 或指针在同一触发器内移动而重新打开卡片。重新进入触发器 或键盘焦点可以再次显示它。取消一个尚未显示的待处理 预览,会使 Escape 仍可供外层界面使用。

状态方法有 is_open、is_disabled、focus_handle、 close(window, cx) 和 set_disabled(disabled, window, cx)。显式关闭 会抑制本次进入。重新启用后需等待下一次进入或获得焦点。 卸载会取消延迟的任务并清除保留的可见性;已挂载的 Escape 订阅仅属于该窗口。

Popup 负责定位、视口限制、延迟绘制和遮挡。可见的 预览是一个辅助性的 Tooltip 界面,没有 Tab 停靠点;它从不 形成焦点陷阱。accessibility_label 为该界面命名。请将关键 信息放在 Button 的无障碍描述或其普通 目的地中,而不要只放在指针预览里。交互式内容应放在 Popover 中。触摸没有悬停:在触发器上长按会立即 打开预览,且不会激活 Button,随后在任意位置的下一次按下会将其关闭。 不提供全局的悬停提供者。

示例预览当前的录制预设、录制日期和备注 状态。点击同一个 Button 或在其上按 Enter 会打开设置 Dialog, 关闭后焦点会返回到该 Button。