diff --git "a/\352\270\260\354\210\240\353\270\224\353\241\234\352\267\270/_posts/2024-10-11-floatingUI.md" "b/\352\270\260\354\210\240\353\270\224\353\241\234\352\267\270/_posts/2024-10-11-floatingUI.md" index 6c1c399..08f4853 100644 --- "a/\352\270\260\354\210\240\353\270\224\353\241\234\352\267\270/_posts/2024-10-11-floatingUI.md" +++ "b/\352\270\260\354\210\240\353\270\224\353\241\234\352\267\270/_posts/2024-10-11-floatingUI.md" @@ -4,7 +4,7 @@ title: "Floating UI 소개" author: "김승태" categories: "프론트엔드 기술블로그" banner: - image: 썸네일로 넣고 싶은 이미지 링크 + image: assets/images/post/2023-11-05.webp background: "#000" height: "100vh" min_height: "38vh" @@ -14,8 +14,6 @@ banner: ## Floating Element란? -Floating UI를 소개하기 앞서 먼저 Floating Element에 대해서 말하고자 합니다. - Floating Element는 화면의 기본적인 문서 흐름에서 벗어나서, 다른 콘텐츠 위에 배치되는 UI 요소들을 말합니다. 보통 사용자가 특정 상호작용을 할 때 동적으로 나타나며, 화면의 특정 부분에 위치해 있거나, 특정 기준 (마우스 위치, 텍스트 필드 등)에 따라 위치가 조정됩니다. 여기서 말하는 floating element의 예시는 다음과 같습니다. @@ -59,38 +57,85 @@ function App() { `refs.setFloating` 는 floating element에 사용하는 함수입니다. -다양한 요구사항을 충족하기 위해 useFloating은 아래와 같은 다양한 return value와 option이 존재합니다. 자세한 예시는 [공식 문서](https://floating-ui.com/docs/useFloating)에 나와있습니다. +다양한 요구사항을 충족하기 위해 useFloating은 아래와 같은 다양한 API와 옵션이 존재합니다. 자세한 예시는 [공식 문서](https://floating-ui.com/docs/useFloating)에 나와있습니다. **return value** ```tsx interface UseFloatingReturn { + /** + * 이 context에는 관련 Hook과 컴포넌트에 제공되는 컨텍스트 데이터가 포함되어 있습니다. + * useHover, useClick, useDismiss 등의 다른 hook을 사용할 때 해당 context를 이용합니다. + */ context: FloatingContext; - // 이 context에는 관련 Hook과 컴포넌트에 제공되는 컨텍스트 데이터가 포함되어 있습니다. - // useHover, useClick, useDusmiss 등의 다른 hook을 사용할 때 해당 context를 이용합니다. + + /** + * reference에 대한 floating의 최종 배치입니다. + * 옵션에서 전달된 것과 달리 이 옵션은 flip()과 같은 미들웨어에 의해 변경될 수 있습니다. + */ placement: Placement; - // reference에 대한 floating 의 최종 배치입니다. - // 옵션에서 전달된 것과 달리 이 옵션은 flip()과 같은 미들웨어에 의해 변경될 수 있습니다. - strategy: Strategy; // floating element의 포지셔닝 전략입니다. - x: number; // floating element의 최종 x 좌표입니다. - y: number; // floating element의 최종 y 좌표입니다. - middlewareData: MiddlewareData; // 사용된 미들웨어에서 제공하는 데이터입니다. - isPositioned: boolean; // floating element가 아직 위치가 지정되지 않았는지 여부입니다. - update(): void; // floating element의 위치를 수동으로 업데이트하는 함수입니다. - floatingStyles: React.CSSProperties; // floating element에 적용해야 하는 스타일입니다. - // inline으로 적용합니다. ex)
+ + /** + * floating element의 최종 x 좌표입니다. + */ + strategy: Strategy; + + /** + * floating element의 최종 x 좌표입니다. + */ + x: number; + + /** + * floating element의 최종 y 좌표입니다. + */ + y: number; + + /** + * 사용된 미들웨어에서 제공하는 데이터입니다. + */ + middlewareData: MiddlewareData; + + /** + * floating element가 아직 위치가 지정되지 않았는지 여부입니다. + */ + isPositioned: boolean; + + /** + * floating element의 위치를 수동으로 업데이트하는 함수입니다. + */ + update(): void; + + /** + * floating element에 적용해야 하는 스타일입니다. + * inline으로 적용합니다. 예:
+ */ + floatingStyles: React.CSSProperties; + refs: { + /** + * reference로 지정한 element입니다. 예: ref.reference.current? + */ reference: React.MutableRefObject; - // reference로 지정한 element 입니다. ex) ref.reference.current? + + /** + * floating으로 지정한 element입니다. + */ floating: React.MutableRefObject; - // floating로 지정한 element 입니다 + + /** + * DOM reference element(사용 가능한 경우)에 대한 ref를 추가합니다. + * 이벤트 핸들러 내부 또는 이펙트에서 액세스할 수 있습니다. + */ domReference: React.MutableRefObject; - // DOM reference element(사용 가능한 경우)에 대한 ref를 추가합니다. - // 이벤트 핸들러 내부 또는 이펙트에서 액세스할 수 있습니다. - setReference(node: RT | null): void; // reference element를 설정하는 함수입니다. + + /** + * reference element를 설정하는 함수입니다. + */ + setReference(node: RT | null): void; setFloating(node: HTMLElement | null): void; setPositionReference(node: ReferenceElement): void; }; + elements: { reference: RT | null; floating: HTMLElement | null; @@ -102,18 +147,44 @@ interface UseFloatingReturn { ```tsx interface UseFloatingOptions { - placement?: Placement; // reference element에 대한 floating element의 배치입니다. - // ex) 'top', 'right' 등등 setReference 의 어느 곳에 보여질지 정합니다. - strategy?: 'fixed' | 'absolute'; // 사용할 CSS 위치 속성 유형입니다. - transform?: boolean; // floating element의 위치를 지정하기 위해 CSS 트랜스폼을 사용할지 여부 - // 인라일 스타일을 부여해서 placement의 위치를 잡습니다. + /** + * reference element에 대한 floating element의 배치입니다. + * 예: 'top', 'right' 등등 setReference의 어느 곳에 보여질지 정합니다. + */ + placement?: Placement; + + /** + * 사용할 CSS 위치 속성 유형입니다. + * 예: 'fixed' | 'absolute'. + */ + strategy?: 'fixed' | 'absolute'; + + /** + * floating element의 위치를 지정하기 위해 CSS 트랜스폼을 사용할지 여부입니다. + * 인라인 스타일을 부여하여 placement의 위치를 잡습니다. + */ + transform?: boolean; + + /** + * floating element의 위치를 변경하는 미들웨어 객체 배열입니다. + */ middleware?: Array; - // floating element의 위치를 변경하는 미들웨어 객체 배열입니다. - open?: boolean; // floating element가 열려 있는지 여부 - onOpenChange?( // open 상태가 변경되어야 할 때 호출되는 함수입니다. + + /** + * floating element가 열려 있는지 여부입니다. + */ + open?: boolean; + + /** + * open 상태가 변경되어야 할 때 호출되는 함수입니다. + * @param open - 현재 open 상태 + * @param event - 이벤트 객체 (ex: MouseEvent) + * @param reason - 상태 변경의 이유 (ex: 'hover', 'click') + */ + onOpenChange?( open: boolean, - event?: Event, // e.g. MouseEvent - reason?: OpenChangeReason, // e.g. 'hover', 'click' + event?: Event, + reason?: OpenChangeReason, ): void; elements?: { reference?: ReferenceElement | null; @@ -144,6 +215,11 @@ useFloating({ }); ``` +## 결론 + +Floating UI는 floating element를 쉽게 구현하고, 관리할 수 있는 라이브리리이며 더욱 세밀한 조정을 위한 미들웨어까지 제공합니다. +floating element가 필요하다면 Floating UI를 한번 고려해보세요. + ## 출처 [공식문서](https://floating-ui.com/)