Popover

在当前窗口中，将调用方设置样式的内容放在锚点旁。

正在加载交互演示…

let popover = Popover::new("help-trigger", "help-popup", open)
    .side(AnchorSide::Bottom)
    .side_offset(8.0);
let mut root = popover.root().child(
    popover.trigger().on_click(toggle).child("Account"),
);
if popover.is_open() {
    root = root.child(popover.positioner().child(
        popover.popup().w(240.0).p(16.0).on_dismiss(dismiss).children([
            popover.title().child("Account"),
            popover.description().child("Manage your account settings."),
            popover.close("Close").on_click(dismiss).child("Done"),
        ]),
    ));
}
root

#导入

从 quickgui 导入 Popover。

use quickgui::*;

#用法

let popover = Popover::new("help-trigger", "help-popup", open)
    .side(AnchorSide::Bottom)
    .side_offset(8.0);
let mut root = popover.root().child(
    popover.trigger().on_click(toggle).child("Account"),
);
if popover.is_open() {
    root = root.child(popover.positioner().child(
        popover.popup().w(240.0).p(16.0).on_dismiss(dismiss).children([
            popover.title().child("Account"),
            popover.description().child("Manage your account settings."),
            popover.close("Close").on_click(dismiss).child("Done"),
        ]),
    ));
}
root

#结构

Popover::root
Popover::trigger
Popover::surface
Popover::portal
Popover::backdrop
Popover::positioner
Popover::popup
Popover::arrow
Popover::viewport
Popover::title
Popover::description
Popover::close

#API 参考

展开条目查看说明和完整签名。短横线表示声明中未记录默认值。

`Popover`

查看源码

pub fn new( trigger_id: impl Into<ElementId>, surface_id: impl Into<ElementId>, open: bool, ) -> Self

openpub const fn open(mut self, open: bool) -> Self—

Replace the controlled open flag, Base UI's Root `open` prop. The descriptor is copied per frame, so a component that retains the open flag itself can build one descriptor at construction time and stamp the current value onto it here.

pub const fn open(mut self, open: bool) -> Self

查看源码

kindpub const fn kind(mut self, kind: PopoverKind) -> Self—

Configures kind for this part.

pub const fn kind(mut self, kind: PopoverKind) -> Self

查看源码

placementpub const fn placement(mut self, placement: AnchorPlacement) -> Self—

Configures placement for this part.

pub const fn placement(mut self, placement: AnchorPlacement) -> Self

查看源码

sidepub const fn side(self, side: AnchorSide) -> Self—

Prefer one side of the anchor, keeping the current cross-axis alignment. This is the side half of [`Self::placement`], matching Base UI's `side` prop. A side is a preference: QuickGUI flips to the opposite side when the preferred one does not fit, and [`Self::resolved_side`] reports what actually happened.

pub const fn side(self, side: AnchorSide) -> Self

查看源码

alignpub const fn align(self, align: AnchorAlign) -> Self—

Prefer a cross-axis alignment, keeping the current side. This is the alignment half of [`Self::placement`], matching Base UI's `align` prop.

pub const fn align(self, align: AnchorAlign) -> Self

查看源码

side_offsetpub fn side_offset(self, offset: f32) -> Self—

Set the distance between the anchor and the positioner, Base UI's `sideOffset`. This is the Base UI-named alias of [`Self::anchor_gap`]. Both names stay supported and write the same bounded value.

pub fn side_offset(self, offset: f32) -> Self

查看源码

align_offsetpub fn align_offset(mut self, offset: f32) -> Self—

Shift the popover along its cross axis before collision handling, Base UI's `alignOffset`. Positive values move right on a top or bottom placement and down on a left or right placement. The shift runs before the surface is clamped into the viewport, so it can slide a popup along its trigger but never push it off screen.

pub fn align_offset(mut self, offset: f32) -> Self

查看源码

collision_paddingpub fn collision_padding(self, padding: f32) -> Self—

Set the collision padding kept inside the window viewport, Base UI's `collisionPadding`. This is the Base UI-named alias of [`Self::viewport_margin`]. Both names stay supported.

pub fn collision_padding(self, padding: f32) -> Self

查看源码

stickypub const fn sticky(mut self, sticky: bool) -> Self—

Choose whether the popover is kept inside the collision viewport, Base UI's `sticky`. QuickGUI keeps anchored surfaces on screen by default, which is Base UI's sticky behavior. Passing `false` locks the popover to its anchor so it travels off screen with a scrolling row instead of detaching from it.

pub const fn sticky(mut self, sticky: bool) -> Self

查看源码

anchor_elementpub fn anchor_element(mut self, anchor: impl Into<ElementId>) -> Self—

Position against a different mounted element instead of the trigger, Base UI's `anchor`.

pub fn anchor_element(mut self, anchor: impl Into<ElementId>) -> Self

查看源码

anchor_pointpub fn anchor_point(mut self, anchor: Point) -> Self—

Position against a logical window point instead of the trigger, Base UI's virtual `anchor`.

pub fn anchor_point(mut self, anchor: Point) -> Self

查看源码

anchor_triggerpub const fn anchor_trigger(mut self) -> Self—

Position against the trigger again, undoing an anchor override.

pub const fn anchor_trigger(mut self) -> Self

查看源码

modalpub const fn modal(mut self, modal: bool) -> Self—

Make the open popover modal, Base UI's `modal` prop. A modal popover contains Tab focus inside the popup and expects a mounted [`Self::backdrop_with`] to absorb outside pointer input. QuickGUI adds no dimming: the backdrop stays an invisible caller-owned element until the application paints it.

pub const fn modal(mut self, modal: bool) -> Self

查看源码

is_modalpub const fn is_modal(self) -> bool—

Whether this popover contains focus while open.

pub const fn is_modal(self) -> bool

查看源码

arrow_sizepub fn arrow_size(mut self, size: f32) -> Self—

Declare the edge length of a framework-positioned arrow. [`Self::arrow_with`] centers an arrow of this size on the anchor. Leaving it at zero pins the arrow to the resolved edge without a cross-axis offset, which is what an application that centers the arrow with its own layout wants.

pub fn arrow_size(mut self, size: f32) -> Self

查看源码

arrow_paddingpub fn arrow_padding(mut self, padding: f32) -> Self—

Keep a framework-positioned arrow this far from the popup's corners, Base UI's `arrowPadding`.

pub fn arrow_padding(mut self, padding: f32) -> Self

查看源码

track_placementpub fn track_placement(mut self, placement: &AnchorPlacementHandle) -> Self—

Adopt the placement QuickGUI resolved for this popover on the previous painted frame. Store an [`AnchorPlacementHandle`] on the view next to `open`, mount the positioner with [`Self::tracked_positioner_with`] or [`Self::tracked_surface_with`], and pass the handle here while declaring the next frame. [`Self::arrow_with`], [`Self::resolved_side`], [`Self::resolved_align`], and [`Self::state`] then follow the placement the popover really used instead of the declared preference. QuickGUI requests exactly one correcting frame when the resolved placement changes, so a flipped popover settles immediately and an unflipped one adds no redraw source.

pub fn track_placement(mut self, placement: &AnchorPlacementHandle) -> Self

查看源码

resolved_placementpub const fn resolved_placement(mut self, resolved: Option<ResolvedAnchorPlacement>) -> Self—

Adopt an already-read placement report. Use this when the application keeps the snapshot itself rather than the handle.

pub const fn resolved_placement(mut self, resolved: Option<ResolvedAnchorPlacement>) -> Self

查看源码

resolved_sidepub fn resolved_side(self) -> AnchorSide—

The side the popover actually opened on, or the declared preference before the first frame.

pub fn resolved_side(self) -> AnchorSide

查看源码

resolved_alignpub fn resolved_align(self) -> AnchorAlign—

The cross-axis alignment the popover actually used, or the declared preference.

pub fn resolved_align(self) -> AnchorAlign

查看源码

resolved_anchor_placementpub fn resolved_anchor_placement(self) -> AnchorPlacement—

The full placement the popover actually used, or the declared preference.

pub fn resolved_anchor_placement(self) -> AnchorPlacement

查看源码

statepub fn state(self) -> PopoverPartState—

A copyable snapshot of what Base UI exposes as `data-*` attributes and CSS variables. The application styles from this: it picks a transform origin from [`PopoverPartState::side`], hides a popup whose anchor scrolled away using [`PopoverPartState::anchor_hidden`], matches the trigger width with [`PopoverPartState::anchor_width`], and caps a scrolling viewport with [`PopoverPartState::available_height`]. Every measured field stays zero until the popover has been painted once with a bound placement handle.

pub fn state(self) -> PopoverPartState

查看源码

anchor_gappub fn anchor_gap(mut self, gap: f32) -> Self—

Set the structural distance between the trigger and positioner.

pub fn anchor_gap(mut self, gap: f32) -> Self

查看源码

viewport_marginpub fn viewport_margin(mut self, margin: f32) -> Self—

Set the structural collision margin inside the current window viewport.

pub fn viewport_margin(mut self, margin: f32) -> Self

查看源码

initial_focuspub fn initial_focus(mut self, focus: impl Into<ElementId>) -> Self—

Prefer a mounted popover descendant instead of the popover root when opening.

pub fn initial_focus(mut self, focus: impl Into<ElementId>) -> Self

查看源码

dismiss_on_escapepub const fn dismiss_on_escape(mut self, dismiss: bool) -> Self—

Configures dismiss on escape for this part.

pub const fn dismiss_on_escape(mut self, dismiss: bool) -> Self

查看源码

dismiss_on_pointer_outsidepub const fn dismiss_on_pointer_outside(mut self, dismiss: bool) -> Self—

Configures dismiss on pointer outside for this part.

pub const fn dismiss_on_pointer_outside(mut self, dismiss: bool) -> Self

查看源码

is_openpub const fn is_open(self) -> bool—

Configures is open for this part.

pub const fn is_open(self) -> bool

查看源码

trigger_idpub const fn trigger_id(self) -> ElementId—

Configures trigger id for this part.

pub const fn trigger_id(self) -> ElementId

查看源码

surface_idpub const fn surface_id(self) -> ElementId—

Stable popover identity retained under the existing `surface` name.

pub const fn surface_id(self) -> ElementId

查看源码

popover_idpub const fn popover_id(self) -> ElementId—

Configures popover id for this part.

pub const fn popover_id(self) -> ElementId

查看源码

positioner_idpub fn positioner_id(self) -> ElementId—

Configures positioner id for this part.

pub fn positioner_id(self) -> ElementId

查看源码

backdrop_idpub fn backdrop_id(self) -> ElementId—

Configures backdrop id for this part.

pub fn backdrop_id(self) -> ElementId

查看源码

title_idpub fn title_id(self) -> ElementId—

Configures title id for this part.

pub fn title_id(self) -> ElementId

查看源码

description_idpub fn description_id(self) -> ElementId—

Configures description id for this part.

pub fn description_id(self) -> ElementId

查看源码

close_idpub fn close_id(self) -> ElementId—

Configures close id for this part.

pub fn close_id(self) -> ElementId

查看源码

arrow_idpub fn arrow_id(self) -> ElementId—

Stable identity of the framework-positioned arrow part.

pub fn arrow_id(self) -> ElementId

查看源码

viewport_idpub fn viewport_id(self) -> ElementId—

Stable identity of the scrolling viewport mounted inside the popup.

pub fn viewport_id(self) -> ElementId

查看源码

trigger_focuspub fn trigger_focus(self) -> FocusHandle—

Configures trigger focus for this part.

pub fn trigger_focus(self) -> FocusHandle

查看源码

surface_focuspub fn surface_focus(self) -> FocusHandle—

Configures surface focus for this part.

pub fn surface_focus(self) -> FocusHandle

查看源码

popover_focuspub fn popover_focus(self) -> FocusHandle—

Configures popover focus for this part.

pub fn popover_focus(self) -> FocusHandle

查看源码

focus_surfacepub fn focus_surface(self, cx: &mut EventContext)—

Move focus to the declared initial target, or the popover root, in the same controlled update.

pub fn focus_surface(self, cx: &mut EventContext)

查看源码

`Popover::root`

查看源码

pub fn root(self) -> Element

Group the trigger and floating content in an ordinary, unstyled view.

`Popover::root_with`

查看源码

pub fn root_with(self, root: Element) -> Element

Use an existing view as the popover's composition root.

`Popover::trigger_with`

查看源码

pub fn trigger_with(self, trigger: Element) -> Element

Decorate an application-owned trigger without adding appearance.

`Popover::trigger`

查看源码

pub fn trigger(self) -> Element

Create an unstyled semantic trigger root.

`Popover::positioner_with`

查看源码

pub fn positioner_with(self, positioner: Element) -> Element

Decorate the caller-owned portal/positioner without adding popover appearance. QuickGUI's retained overlay node is itself the portal, so this part combines the Base UI-style Portal and Positioner boundary without introducing a full-window wrapper that would block unrelated pointer input.

`Popover::positioner`

查看源码

pub fn positioner(self) -> Element

Create the unstyled positioner part. Use [`Self::positioner_with`] to supply an existing element.

`Popover::tracked_positioner_with`

查看源码

pub fn tracked_positioner_with( self, positioner: Element, placement: &AnchorPlacementHandle, ) -> Element

Decorate the positioner and publish the placement it resolves to. This is [`Self::positioner_with`] plus [`crate::Element::report_anchor_placement`]: the handle receives the side, alignment, anchor rectangle, and remaining room the popover actually used, and [`Self::track_placement`] feeds it back into the descriptor on the next frame.

`Popover::tracked_positioner`

查看源码

pub fn tracked_positioner(self, placement: &AnchorPlacementHandle) -> Element

Create the unstyled tracked positioner part. Use [`Self::tracked_positioner_with`] to supply an existing element.

`Popover::portal_with`

查看源码

pub fn portal_with(self, portal: Element) -> Element

Base UI's Portal name for the combined portal/positioner part. QuickGUI's retained overlay node is itself the portal, so Portal and Positioner are one element; both names decorate it identically.

`Popover::portal`

查看源码

pub fn portal(self) -> Element

Create the unstyled portal part. Use [`Self::portal_with`] to supply an existing element.

`Popover::popup_with`

查看源码

pub fn popup_with(self, popover: Element) -> Element

Decorate an application-owned popover without adding layout or appearance. The popover emits [`crate::Event::Dismiss`] under [`Self::surface_id`] for every enabled dismissal path. Mounted title/description parts are related without copying their text.

`Popover::popup`

查看源码

pub fn popup(self) -> Element

Create the unstyled popup part. Use [`Self::popup_with`] to supply an existing element.

`Popover::surface_with`

查看源码

pub fn surface_with(self, surface: Element) -> Element

Decorate one caller-owned element as both positioner and popover. This compact form has the same unstyled contract as composing [`Self::positioner_with`] around [`Self::popup_with`]. Use separate parts when the application needs to animate or size the positioner independently from popover presentation.

`Popover::tracked_surface_with`

查看源码

pub fn tracked_surface_with( self, surface: Element, placement: &AnchorPlacementHandle, ) -> Element

Decorate the merged surface and publish the placement it resolves to.

`Popover::tracked_surface`

查看源码

pub fn tracked_surface(self, placement: &AnchorPlacementHandle) -> Element

Create the unstyled tracked surface part. Use [`Self::tracked_surface_with`] to supply an existing element.

`Popover::surface`

查看源码

pub fn surface(self) -> Element

Create an unstyled merged positioner/popover root.

`Popover::arrow_with`

查看源码

pub fn arrow_with(self, arrow: Element) -> Element

Position a caller-owned arrow on the edge the popover actually opened against. The arrow is absolutely positioned inside the popup, pinned to the edge that faces the anchor and centered on the anchor along the cross axis. When [`Self::track_placement`] has supplied a placement report the offsets follow the real placement, including a flip — never the declared preference. Before the first painted frame, or without a bound handle, the arrow follows the declared side and stays centered on the popup, and QuickGUI's one correcting frame moves it as soon as the real placement is known. The application owns the arrow's size, shape, rotation, and color. Declare [`Self::arrow_size`] when QuickGUI should center an arrow of a known edge length, and [`Self::arrow_padding`] to keep it clear of the popup's corners. The arrow is hidden from assistive technology: it is decoration attached to a surface that already carries the relationship.

`Popover::arrow`

查看源码

pub fn arrow(self) -> Element

Create the unstyled arrow part. Use [`Self::arrow_with`] to supply an existing element.

`Popover::viewport_with`

查看源码

pub fn viewport_with(self, viewport: Element) -> Element

Decorate a caller-owned scrolling viewport mounted inside the popup. Base UI's Viewport clips content that changes size between triggers so the popup can animate between them. QuickGUI supplies the stable identity and the scroll container; height, padding, and motion stay application-owned — cap it with [`PopoverPartState::available_height`] to keep a long popup inside the window.

`Popover::viewport`

查看源码

pub fn viewport(self) -> Element

Create the unstyled viewport part. Use [`Self::viewport_with`] to supply an existing element.

`Popover::backdrop_with`

查看源码

pub fn backdrop_with(self, backdrop: Element) -> Element

Decorate an optional caller-painted viewport backdrop.

`Popover::backdrop`

查看源码

pub fn backdrop(self) -> Element

Create the unstyled backdrop part. Use [`Self::backdrop_with`] to supply an existing element.

`Popover::title_with`

查看源码

pub fn title_with(self, title: Element) -> Element

Assign the stable mounted label target used by the popover.

`Popover::title`

查看源码

pub fn title(self) -> Element

Create the unstyled title part. Use [`Self::title_with`] to supply an existing element.

`Popover::description_with`

查看源码

pub fn description_with(self, description: Element) -> Element

Assign the stable mounted description target used by the popover.

`Popover::description`

查看源码

pub fn description(self) -> Element

Create the unstyled description part. Use [`Self::description_with`] to supply an existing element.

`Popover::close_with`

查看源码

pub fn close_with(self, label: impl Into<Arc<str>>, close: Element) -> Element

Decorate a caller-owned close control with button behavior and no visual defaults.

`Popover::close`

查看源码

pub fn close(self, label: impl Into<Arc<str>>) -> Element

Create the unstyled close part. Use [`Self::close_with`] to supply an existing element.