# Image Frame URL: /lynx/components/image-frame Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/image-frame.mdx 사용자가 업로드한 이미지를 표시하기 위한 컴포넌트입니다. Lynx Engine 최소 버전: 3.9 사용 가능 버전: @seed-design/lynx-react@1.0.0, @seed-design/lynx-css@1.0.0 ## Preview ```tsx import "./styles"; import { ImageFrame } from "@seed-design/lynx-react"; export default function ImageFramePreview() { return ( 이미지 } /> ); } ``` ## Installation - npm: npm install @seed-design/lynx-react @seed-design/lynx-css - pnpm: pnpm add @seed-design/lynx-react @seed-design/lynx-css - yarn: yarn add @seed-design/lynx-react @seed-design/lynx-css - bun: bun add @seed-design/lynx-react @seed-design/lynx-css ## Usage ```tsx import { ImageFrame } from "@seed-design/lynx-react"; ``` ```tsx 이미지를 불러올 수 없습니다.} /> ``` `width`·`height`·`margin` 등 공통 레이아웃 prop을 받습니다. `margin`과 `bleed`는 함께 사용하지 않으며, `bleed`는 Lynx Box와 같이 px 길이·`0`·`"safeArea"`를 사용합니다. ## Props ## Lynx에서의 동작 Lynx Engine 3.9 이상을 지원합니다. - 로딩 중에도 이미지를 마운트합니다. `src`가 바뀌면 이전 요청의 이벤트를 새 상태에 반영하지 않습니다. - `alt`는 `accessibility-label`로 전달합니다. 장식용 이미지는 빈 문자열을 사용합니다. - `onLoad`와 `onError` 대신 `bindload`와 `binderror`를 사용합니다. `onLoadingStatusChange`로 로딩 상태를 관찰할 수 있습니다. - `ratio`의 기본값은 `4 / 3`, `borderRadius`의 기본값은 `"r2"`입니다. - `ImageFrameIcon`의 `svg`에는 Lynx 아이콘 컴포넌트를 전달합니다. - `ImageFrameReactionButton`은 토글 버튼입니다. `pressed`, `defaultPressed`, `onPressedChange`, `disabled`를 제공하며 접근성 이름은 `accessibility-label`로 지정합니다. - 좋아요 버튼은 `hit-slop`으로 터치 영역을 기본 8px씩 확장합니다. 부모가 콘텐츠를 자르면 확장 영역도 제한될 수 있습니다. - `as`, `asChild`, DOM 속성, 이미지의 `loading`, `decoding`, `crossOrigin`, `referrerPolicy`, `sizes`, `srcSet`은 지원하지 않습니다. ## Examples ### Ratio `ratio`로 이미지 영역의 비율을 지정합니다. ```tsx import "./styles"; import { ImageFrame, HStack, VStack, Text } from "@seed-design/lynx-react"; export default function ImageFrameRatio() { return ( 이미지 } /> 1:1 이미지 } /> 4:3 이미지 } /> 16:9 ); } ``` ### Border Radius `borderRadius`에는 토큰, `0`, CSS 길이를 전달합니다. 개별 모서리는 `borderTopLeftRadius` 같은 prop으로 지정합니다. ```tsx ``` ```tsx import "./styles"; import { ImageFrame, HStack, VStack, Text } from "@seed-design/lynx-react"; export default function ImageFrameBorderRadius() { return ( 이미지 } /> 20 / r1 (4px) 이미지 } /> 24 / r1 (4px) 이미지 } /> 36 / r1_5 (6px) 이미지 } /> 42 / r1_5 (6px) 이미지 } /> 48 / r1_5 (6px) 이미지 } /> 64+ / r2 (8px) ); } ``` ### Stroke `stroke` prop으로 테두리 스타일을 적용할 수 있습니다. ```tsx import "./styles"; import { ImageFrame, HStack, VStack, Text } from "@seed-design/lynx-react"; export default function ImageFrameStroke() { return ( 이미지 } /> stroke=false 이미지 } /> stroke=true ); } ``` ### Fallback Image `fallback`은 로딩 중이거나 오류가 발생했을 때 표시하고, 로딩에 성공하면 언마운트합니다. 다시 표시할 때 유지해야 하는 상태는 부모에서 관리하세요. ```tsx import "./styles"; import { ImageFrame, HStack } from "@seed-design/lynx-react"; export default function ImageFrameFallbackExample() { return ( 이미지 } /> 이미지 } /> 이미지 } /> ); } ``` ### Overlay `ImageFrameFloater`를 자식으로 넣고 `placement`로 위치를 지정합니다. 세로와 가로 위치를 조합한 9개 값을 사용할 수 있습니다. `ImageFrameFloater`는 [Float](/lynx/foundation/layout/float)를 조합해 기본 간격과 Safe Area 보정을 더합니다. 이미지와 무관한 요소를 배치할 때는 `Float`를 직접 사용할 수 있습니다. ```tsx import "./styles"; import IconCarrotFill from "@karrotmarket/lynx-monochrome-icon/IconCarrotFill"; import { ImageFrame, ImageFrameFloater, ImageFrameBadge, ImageFrameIcon, ImageFrameIndicator, ImageFrameReactionButton, HStack, VStack, Text, } from "@seed-design/lynx-react"; import { useState } from "@lynx-js/react"; export default function ImageFrameOverlayExample() { const [liked, setLiked] = useState(false); return ( 이미지 } > NEW ImageFrameBadge 이미지 } > } /> ImageFrameIcon 이미지 } > +9 ImageFrameIndicator 이미지 } > ImageFrameReactionButton ); } ``` #### Multiple Overlays 여러 위치에 오버레이를 동시에 배치할 수 있습니다. ```tsx import "./styles"; import { ImageFrame, ImageFrameFloater, ImageFrameBadge, ImageFrameReactionButton, } from "@seed-design/lynx-react"; import { useState } from "@lynx-js/react"; export default function ImageFrameOverlayMultipleExample() { const [liked, setLiked] = useState(false); return ( 이미지 } > NEW ); } ``` #### Custom Overlay `ImageFrameFloater`는 커스텀 UI도 `children`으로 받습니다. ```tsx import "./styles"; import { ImageFrame, ImageFrameFloater } from "@seed-design/lynx-react"; export default function ImageFrameOverlayCustomExample() { return ( 이미지 } > Custom Element ); } ``` #### Offset `offsetX`와 `offsetY`로 가로와 세로 여백을 지정합니다. `0`, SEED 간격 토큰, CSS 길이를 사용할 수 있습니다. 가장자리의 기본 여백은 6px이며, 중앙 축의 기본 오프셋은 0입니다. ```tsx import { ImageFrame, ImageFrameFloater, ImageFrameIndicator } from "@seed-design/lynx-react"; +9 ``` ```tsx import "./styles"; import { ImageFrame, ImageFrameFloater, ImageFrameIndicator } from "@seed-design/lynx-react"; export default function ImageFrameOverlayInsetExample() { return ( 이미지 } > default 이미지 } > offset=0 이미지 } > offset=12 ); } ``` ## Overlay Props ## Extending to Safe Area `bleedX="safeArea"`를 지정하면 이미지가 좌우 Safe Area까지 확장되고, `ImageFrameFloater`는 안전 영역 안에 배치됩니다. `*-start`에는 왼쪽 inset, `*-end`에는 오른쪽 inset이 `offsetX`에 더해집니다. `*-center`는 좌우 inset 차이의 절반만큼 이동해 안전 영역의 중앙에 놓입니다. `bleedLeft`·`bleedRight`를 따로 지정한 경우 해당 방향에 실제로 `"safeArea"`가 적용될 때만 보정합니다. px 길이로 확장하거나 확장하지 않은 이미지는 기존 Floater 위치를 유지합니다. 배지의 위치 보정은 `bleed` prop을 기준으로 계산합니다. `bleed`와 함께 `style`이나 `className`으로 같은 방향의 margin을 덮어쓰지 마세요. margin만 바꾸면 배지의 보정값은 그대로 남습니다. 한쪽 확장을 끄려면 `bleedX="safeArea" bleedLeft={0}`처럼 해당 방향의 `bleed`를 지정하고, 추가 여백은 바깥 컨테이너에서 조절하세요. `Box pl="safeArea" pr="safeArea"`처럼 좌우 inset을 이미 확보한 컨테이너 바로 안에서 사용하세요. inset을 확보하지 않은 곳에 적용하면 화면 밖으로 넘칠 수 있습니다. Lynx에서는 비율에 맞는 높이를 계산할 수 있도록 프레임 너비를 지정합니다. 예제는 `useSafeArea()`로 읽은 좌우 inset을 너비에 더하고, 확장을 끄면 부모 콘텐츠 너비로 돌아갑니다. ### 확장 전 / 확장 후 | 비교 | 확장 전 (AS IS) | 확장 후 (TO BE) | | --- | --- | --- | | 배경·스크롤 영역 | 이미지가 안전 영역 안에서 끝남 | 이미지가 좌우 끝까지 이어짐 | | 콘텐츠 | 안전 영역 안에 배치 | 배지의 시작·끝·중앙은 안전 영역을 기준으로 배치 | 아래 스위치를 켜고 끄며 같은 예제에서 비교할 수 있습니다. 브라우저에는 비교용 좌우 inset을 적용합니다. 붉은 빗금은 콘텐츠를 피해야 하는 inset 영역이며, 두 경계선 사이는 안전 영역입니다. QR로 연 기기에서는 실제 inset을 사용하므로, 좌우 inset이 모두 `0`이면 차이가 보이지 않을 수 있습니다. 적용 조건은 [Safe Area 가이드](/lynx/getting-started/safe-area)를 참고하세요. ```tsx import "./styles"; import { useGlobalProps, useState } from "@lynx-js/react"; import { Box, ImageFrame, ImageFrameBadge, ImageFrameFloater, Text, useSafeArea, VStack, } from "@seed-design/lynx-react"; import { Switch } from "@/components/ui/switch"; export default function Example() { useGlobalProps(); const [extend, setExtend] = useState(false); const { safeAreaInsetLeft, safeAreaInsetRight } = useSafeArea(); return ( {extend ? '확장 후 (TO BE) · bleedX="safeArea"' : "확장 전 (AS IS) · bleedX=0"} 이미지는 화면 끝까지, 배지는 안전 영역 안에 놓입니다. 이미지 } > 시작 중앙 끝 ); } ```