由 GPUI 的 Web 后端渲染的真实组件。需要支持 WebGPU 的浏览器。
PopoverState 持有打开状态、触发器焦点、弹出层焦点范围以及禁用
状态。使用 cx.new(PopoverState::new) 只创建一次,并观察它以进行渲染。
可以选择使用 .with_initial_focus(&handle) 指向弹出层内的某个控件。
否则,打开时会聚焦内容范围,Tab 进入其第一个控件。
使用以下内容构建 Popover::new(id, &state):
.trigger(|button| ...),使用现有的 Button API 提供触发器的内容、无障碍名称和 外观。.accessibility_label(...),为弹出层的非模态对话框界面命名。.content(...),用于由应用负责的弹出内容和界面样式。.anchor(...)用于角落锚定,.offset(...)用于触发器间距。.side(Placement::Right).align(Align::Start)用于按侧边定位的弹出层,并带有 碰撞翻转。仅调用.align(...)时选择 Bottom;其默认的 侧边对齐为 Center。Top/Bottom 的 Start/End 遵循限定作用域的逻辑 方向。定位器会跟踪触发器的当前框架,并限制在 视口内。显式的角落锚点和上下文菜单的指针坐标 保留各自独立的定位约定。
库负责触发器的激活、焦点、禁用状态以及展开
元数据。所提供的 id 标识该触发器。其按钮构建器应
提供外观和无障碍名称,而弹出层内的应用按钮
可以调用 PopoverState::close(window, cx)。
状态方法包括 open、close、is_open、is_disabled、
set_disabled(disabled, window, cx)、focus_handle 和 content_focus_handle。
禁用会关闭已打开的弹出层,并阻止重新打开。关闭时请保持 Popover 处于挂载
状态,使其触发器保持标识,并能测量其锚定几何。
Popover 是非模态的:它不会困住焦点。Tab 会遍历其内容,然后 移到其触发器之后的下一个普通控件,同时关闭弹出层。在 第一个内容控件之前按 Shift-Tab 会关闭它并返回到触发器。外层的 Dialog 仍会限定该遍历。
Escape 会关闭获得焦点的弹出层并恢复触发器的焦点。如果 Popover 位于 Dialog 内,第一次 Escape 会让父对话框保持打开。在外部按下指针 会关闭弹出层,同时允许被点击的控件获得焦点。焦点移到 别处、父界面关闭以及窗口失去活动状态同样会将其关闭; 在另一个界面取得焦点之后,弹出层不会把焦点抢回来。
当应用移除整个获得焦点的 Popover 宿主(包括其 触发器)时,必须在同一次更新中将焦点移到仍然存在的控件。 弹出层会清理其打开状态,而不会任意选择替代目标。 示例中的标签切换和 Dialog 关闭,已经会在移除 弹出层界面之前移动焦点。