Image Frame
사용자가 업로드한 이미지를 표시하기 위한 컴포넌트입니다.
Installation
Usage
width·height·margin 등 공통 레이아웃 prop을 받습니다. margin과 bleed는 함께 사용하지 않으며, bleed는 Lynx Box와 같이 px 길이·0·"safeArea"를 사용합니다.
Props
Prop
Type
srcstringaltstringratio?number | undefinedstroke?boolean | undefinedfallback?React.ReactNodeonLoadingStatusChange?((status: ImageLoadingStatus) => void) | undefinedLynx에서의 동작
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로 이미지 영역의 비율을 지정합니다.
Border Radius
borderRadius에는 토큰, 0, CSS 길이를 전달합니다. 개별 모서리는 borderTopLeftRadius 같은 prop으로 지정합니다.
Stroke
stroke prop으로 테두리 스타일을 적용할 수 있습니다.
Fallback Image
fallback은 로딩 중이거나 오류가 발생했을 때 표시하고, 로딩에 성공하면 언마운트합니다. 다시 표시할 때 유지해야 하는 상태는 부모에서 관리하세요.
Overlay
ImageFrameFloater를 자식으로 넣고 placement로 위치를 지정합니다. 세로와 가로 위치를 조합한 9개 값을 사용할 수 있습니다.
ImageFrameFloater는 Float를 조합해 기본 간격과 Safe Area 보정을 더합니다. 이미지와 무관한 요소를 배치할 때는 Float를 직접 사용할 수 있습니다.
Multiple Overlays
여러 위치에 오버레이를 동시에 배치할 수 있습니다.
Custom Overlay
ImageFrameFloater는 커스텀 UI도 children으로 받습니다.
Offset
offsetX와 offsetY로 가로와 세로 여백을 지정합니다. 0, SEED 간격 토큰, CSS 길이를 사용할 수 있습니다. 가장자리의 기본 여백은 6px이며, 중앙 축의 기본 오프셋은 0입니다.
Overlay Props
Prop
Type
placementNonNullable<"bottom-center" | "bottom-end" | "bottom-start" | "middle-center" | "middle-end" | "middle-start" | "top-center" | "top-end" | "top-start" | undefined>zIndex?number | (string & {}) | undefinedProp
Type
Prop
Type
svgReact.ReactElement<LynxIconElementProps, string | React.JSXElementConstructor<any>>Prop
Type
childrenReact.ReactNodeProp
Type
pressed?boolean | undefineddefaultPressed?boolean | undefinedonPressedChange?((pressed: boolean) => void) | undefinedExtending 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 가이드를 참고하세요.
비교용 inset: 왼쪽 24px · 오른쪽 48px (가상)
붉은 빗금은 콘텐츠를 피해야 하는 inset 영역이며, 두 경계선 사이는 안전 영역입니다.
Last updated on