GPUI Deck

Popover

비모달 열기/닫기 상태, 모서리 또는 충돌을 고려한 측면/정렬 배치, 포커스, 바깥 닫기, Escape.

GPUI 웹 백엔드가 그리는 실제 컴포넌트입니다. 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 닫기는 팝업 화면을 제거하기 전에 이미 포커스를 옮깁니다.