ImageView
단일 또는 다중 이미지를 슬라이드로 표시하고, 클릭 시 원본 크기 확대 보기를 제공하는 이미지 뷰어 컴포넌트
개요
Cals ImageView는 Foundation Image와 Carousel을 조합하여, 단일/다중 이미지를 슬라이드 형태로 표시하는 뷰어입니다. 이미지를 클릭하면 원본 크기 확대 보기가 열리고, 로드에 실패하면 대체 아이콘이 표시됩니다. 라벨/필수/도움말 등 폼 메타 정보도 함께 제공합니다.
주요 특징
- ✅ 단일/다중 슬라이드: 이미지가 2장 이상이면 화살표와 인디케이터를 표시
- ✅ 확대 보기: 이미지를 클릭하면 원본 크기 확대 오버레이(닫기/ESC)
- ✅ 확대 비활성화: zoomable=false로 확대 기능을 끌 수 있음 (자체 확대 UI 사용 시)
- ✅ 에러 대체: 로드 실패 시 대체 아이콘을 배경과 함께 표시
- ✅ 슬라이드 이벤트: onChange로 현재/이전 인덱스와 현재 이미지 전달
- ✅ 라벨 메타: label, 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)
}}
/>라벨 / 필수 / 도움말
label로 라벨을, orientation으로 라벨 위치를, required로 필수 표시를, labelTooltip으로 도움말을 설정합니다. title은 다른 컨트롤과 동일하게 HTML title 속성(native tooltip)으로 적용됩니다.
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 등) |
zoomable | boolean | true | 이미지 클릭 확대 기능 활성화 여부 |
height | string | number | 200 | 캐러셀 뷰포트 높이 |
visible | boolean | true | 표시 여부 (false → 렌더 안 함) |
label | string | - | 라벨 텍스트 |
title | string | - | HTML title 속성 (native tooltip) |
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 요소 |
확대 기능 비활성화 (zoomable)
자체 확대 UI를 사용하거나 이미지 클릭 동작을 별도 핸들러로 처리할 때, zoomable={false}로 내장 확대 기능을 비활성화합니다.
Preview
접근성
권장 사항
- ✅ 각 이미지에
alt텍스트를 제공하여 대체 텍스트를 노출 - ✅ 캐러셀 영역/슬라이드에 region/group role이 부여됨(Foundation 기본)
- ✅ 확대 보기 오버레이는 role=“dialog”, aria-modal로 동작(Foundation 기본)