Floating Panel

Floating Panel (플로팅 패널)

페이지 콘텐츠 위에 떠 있는, 드래그하고 크기 조절이 가능한 패널을 렌더링할 때 사용하는 컴포넌트예요. 창처럼 자유롭게 움직이고 크기를 바꿀 수 있는 패널에 쓰여요.

출처: 문서

본문

사용법 (Usage)

import { FloatingPanel } from "@chakra-ui/react"

<FloatingPanel.Root>
  <FloatingPanel.Trigger />
  <FloatingPanel.Positioner>
    <FloatingPanel.Content>
      <FloatingPanel.Header>
        <FloatingPanel.DragTrigger>
          <FloatingPanel.Title />
        </FloatingPanel.DragTrigger>
        <FloatingPanel.Control>
          <FloatingPanel.StageTrigger />
          <FloatingPanel.CloseTrigger />
        </FloatingPanel.Control>
      </FloatingPanel.Header>
      <FloatingPanel.Body />
      <FloatingPanel.ResizeTriggers />
    </FloatingPanel.Content>
  </FloatingPanel.Positioner>
</FloatingPanel.Root>

단축 (Shortcuts)

FloatingPanel 컴포넌트는 일반적인 사용 사례를 위한 단축(shortcut)을 제공해요.

FloatingPanelResizeTriggers

FloatingPanel.ResizeTriggers는 각 리사이즈 축에 대해 FloatingPanel.ResizeTrigger를 하나씩 렌더링해요.

<FloatingPanel.ResizeTriggers />

이 코드는 개별 핸들을 커스터마이즈할 필요가 없다면 다음의 축약형이에요.

<FloatingPanel.ResizeTrigger axis="n" />
<FloatingPanel.ResizeTrigger axis="s" />
<FloatingPanel.ResizeTrigger axis="e" />
<FloatingPanel.ResizeTrigger axis="w" />
<FloatingPanel.ResizeTrigger axis="ne" />
<FloatingPanel.ResizeTrigger axis="nw" />
<FloatingPanel.ResizeTrigger axis="se" />
<FloatingPanel.ResizeTrigger axis="sw" />

axes prop을 넘기면 특정 핸들만 렌더링할 수 있어요.

<FloatingPanel.ResizeTriggers axes={["s", "e", "se"]} />

예제 (Examples)

제어된 열기 (Controlled Open)

open과 onOpenChange prop을 사용해서 패널의 표시 여부를 제어할 수 있어요.

| 예제 (floating-panel-controlled-open) |

스토어 (Store)

플로팅 패널을 제어하는 또 다른 방법은 RootProvider 컴포넌트와 useFloatingPanel 스토어 훅을 사용하는 거예요.

이렇게 하면 패널 바깥에서도 패널의 상태와 메서드에 접근할 수 있어요.

RootProvider + useFloatingPanel 또는 Root 중 하나만 사용하세요. 둘 다 쓰지 마세요.

| 예제 (floating-panel-with-store) |

단계 (Stages)

FloatingPanel.StageTrigger에 stage prop을 사용해서 패널을 최소화, 최대화, 복원하는 버튼을 추가할 수 있어요. 사용 가능한 단계는 다음과 같아요.

default — 패널을 일반적인 크기와 위치로 복원
minimized — 패널을 콤팩트한 높이(헤더만)로 축소
maximized — 패널을 사용 가능한 경계를 채우도록 확장

<FloatingPanel.StageTrigger stage="minimized" />

| 예제 (floating-panel-stages) |

여러 개 (Multiple)

여러 FloatingPanel.Root 인스턴스를 렌더링해서 한 번에 여러 패널을 표시할 수 있어요. 각 루트는 자체 열기 상태, 위치, 크기를 독립적으로 관리해요.

| 예제 (floating-panel-multiple) |

오버레이 (Overlay)

createOverlay 함수를 사용해서 앱 어디에서나 플로팅 패널을 프로그래밍 방식으로 열 수 있어요. 오버레이의 Viewport 컴포넌트를 렌더링하고 .open()을 호출하면 패널이 표시돼요.

| 예제 (floating-panel-with-overlay) |

컨텍스트 (Context)

패널 안에서 useFloatingPanelContext를 사용해서 minimize, maximize, restore, setPosition, setSize를 프로그래밍 방식으로 호출할 수 있어요.

| 예제 (floating-panel-context) |

드래그 비활성화 (Disable Drag)

draggable={false}를 설정하면 사용자가 패널을 이동하지 못하게 할 수 있어요.

| 예제 (floating-panel-disable-drag) |

리사이즈 비활성화 (Disable Resize)

resizable={false}를 설정하면 사용자가 패널의 크기를 조절하지 못하게 할 수 있어요.

| 예제 (floating-panel-disable-resize) |

리사이즈 축 (Resize Axes)

FloatingPanel.ResizeTriggers에 axes prop을 넘겨서 어떤 리사이즈 핸들이 렌더링될지 제한할 수 있어요.

| 예제 (floating-panel-resize-axes) |

최소/최대 (Min/Max)

minSize와 maxSize prop을 사용해서 패널을 얼마나 작게 또는 크게 리사이즈할 수 있는지 제한할 수 있어요.

| 예제 (floating-panel-min-max) |

앵커 위치 (Anchor Position)

getAnchorPosition prop을 사용해서 패널이 열릴 때 트리거 요소를 기준으로 위치를 잡을 수 있어요.

| 예제 (floating-panel-anchor-position) |

경계 (Boundary)

allowOverflow={false}와 함께 getBoundaryEl을 사용해서 패널을 특정 컨테이너 안에 가둘 수 있어요.

| 예제 (floating-panel-boundary) |

위치 (Position)

position과 onPositionChange prop을 사용해서 패널의 위치를 프로그래밍 방식으로 제어할 수 있어요.

| 예제 (floating-panel-controlled-position) |

크기 (Size)

size와 onSizeChange prop을 사용해서 패널의 크기를 프로그래밍 방식으로 제어할 수 있어요.

| 예제 (floating-panel-controlled-size) |

오버플로 방지 (Prevent Overflow)

allowOverflow={false}를 설정하면 패널이 뷰포트 가장자리를 넘어 드래그되지 않도록 막을 수 있어요.

| 예제 (floating-panel-prevent-overflow) |

RTL

dir="rtl" prop을 설정하면 오른쪽에서 왼쪽(RTL) 레이아웃을 지원할 수 있어요.