ImageView
단일 또는 다중 이미지를 슬라이드로 표시하고, 클릭 시 원본 크기 확대 보기를 제공하는 이미지 뷰어 컴포넌트
개요
Cals ImageView는 Foundation Image와 Carousel을 조합하여, 단일/다중 이미지를 슬라이드 형태로 표시하는 뷰어입니다. 이미지를 클릭하면 원본 크기 확대 보기가 열리고, 로드에 실패하면 대체 아이콘이 표시됩니다. 라벨/필수/도움말 등 폼 메타 정보도 함께 제공합니다.
주요 특징
- ✅ 단일/다중 슬라이드: 이미지가 2장 이상이면 화살표와 인디케이터를 표시
- ✅ 확대 보기: 이미지를 클릭하면 원본 크기 확대 오버레이(닫기/ESC)
- ✅ 에러 대체: 로드 실패 시 대체 아이콘을 배경과 함께 표시
- ✅ 슬라이드 이벤트: onChange로 현재/이전 인덱스와 현재 이미지 전달
- ✅ 라벨 메타: title, required, labelTooltip, orientation 지원
- ✅ 라벨 스타일: color, font* 등 라벨 텍스트 스타일 오버라이드
- ✅ URL 변환: resolveSrc 콜백으로 S3 Pre-Signed URL 등 주입
기본 사용
images에 { id, src } 목록을 전달합니다. 1장이면 화살표/인디케이터가 표시되지 않습니다.
Preview
다중 이미지 슬라이드
2장 이상이면 좌우 화살표와 하단 인디케이터로 슬라이드를 넘길 수 있습니다.
Preview
슬라이드 변경 이벤트
onChange로 currentIndex, previousIndex, currentImage를 전달받습니다.
<ImageView
images={images}
onChange={(data) => {
console.log(data.currentIndex, data.previousIndex, data.currentImage)
}}
/>라벨 / 필수 / 도움말
title로 라벨을, orientation으로 라벨 위치를, required로 필수 표시를, labelTooltip으로 도움말을 설정합니다.
Preview
라벨 스타일 설정
color, fontSize, fontWeight, fontStyle 등으로 라벨 텍스트 스타일을 지정합니다.
Preview
S3 Pre-Signed URL (resolveSrc)
S3 등 인증이 필요한 이미지는 resolveSrc 콜백으로 표시 시점에 인증 URL을 주입합니다. 임시 파일 필터링·썸네일 변환 등 경로 가공은 프로젝트팀이 images를 전처리하여 전달합니다.
<ImageView
images={images}
resolveSrc={async (item) => await getPreSignedUrl(item.src, "download")}
/>API Reference
ImageViewItem
| 필드 | Type | 필수 | Description |
|---|---|---|---|
id | string | ✅ | 슬라이드 key |
src | string | ✅ | 이미지 URL |
alt | string | - | 대체 텍스트(접근성) |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
images | ImageViewItem[] | [] | 표시할 이미지 목록 |
onChange | (data: { currentIndex; previousIndex; currentImage }) => void | - | 슬라이드 변경 콜백 |
resolveSrc | (item) => string | Promise<string> | - | 표시 URL 변환(S3 Pre-Signed URL 등) |
height | string | number | 200 | 캐러셀 뷰포트 높이 |
visible | boolean | true | 표시 여부 (false → 렌더 안 함) |
title | string | - | 라벨 텍스트 |
showLabel | boolean | false | 라벨 영역 표시 여부 |
labelTooltip | string | - | 라벨 도움말 (아이콘 hover 시 Tooltip) |
required | boolean | - | 필수 표시 |
orientation | "horizontal" | "vertical" | - | 라벨 위치 (horizontal=왼쪽) |
color / fontFamily / fontSize / fontWeight / fontStyle / textAlign | string | - | 라벨 텍스트 스타일 오버라이드 |
className | string | - | 컨테이너 className |
ref | Ref<ImageViewRef> | - | currentIndex/currentImage/scroll 제어 |
ImageViewRef
| 멤버 | Type | Description |
|---|---|---|
currentIndex | number | 현재 슬라이드 인덱스 |
currentImage | ImageViewItem | undefined | 현재 이미지 정보 |
scrollTo(index) | (index: number) => void | 지정 슬라이드로 이동 |
scrollNext() | () => void | 다음 슬라이드 |
scrollPrev() | () => void | 이전 슬라이드 |
element | HTMLDivElement | null | 컨테이너 DOM 요소 |
접근성
권장 사항
- ✅ 각 이미지에
alt텍스트를 제공하여 대체 텍스트를 노출 - ✅ 캐러셀 영역/슬라이드에 region/group role이 부여됨(Foundation 기본)
- ✅ 확대 보기 오버레이는 role=“dialog”, aria-modal로 동작(Foundation 기본)
관련 컴포넌트
Last updated on