HoverGallery#

마우스를 올리면 호버 위치에 따라 이미지가 전환되어 표시되는 갤러리 컴포넌트입니다. 제품 목록, 포트폴리오 카드 등에서 미리 보기 효과를 줄 때 활용합니다.

Live Preview#

Web

Flutter

Loading Flutter...

Web Flutter

Copy

class HoverGalleryDefaultExample extends StatefulComponent {
  const HoverGalleryDefaultExample({super.key});

  @override
  State<HoverGalleryDefaultExample> createState() =>
      _HoverGalleryDefaultExampleState();
}

class _HoverGalleryDefaultExampleState
    extends State<HoverGalleryDefaultExample> {
  @override
  Component build(BuildContext context) {
    return CoHoverGallery(
      imageUrls: [
        'https://picsum.photos/seed/a/400/300',
        'https://picsum.photos/seed/b/400/300',
        'https://picsum.photos/seed/c/400/300',
      ],
    );
  }
}

class HoverGalleryDefaultExample extends StatefulWidget {
  const HoverGalleryDefaultExample({super.key});

  @override
  State<HoverGalleryDefaultExample> createState() =>
      _HoverGalleryDefaultExampleState();
}

class _HoverGalleryDefaultExampleState
    extends State<HoverGalleryDefaultExample> {
  @override
  Widget build(BuildContext context) {
    return CoHoverGallery(
      imageUrls: [
        'https://picsum.photos/seed/a/400/300',
        'https://picsum.photos/seed/b/400/300',
        'https://picsum.photos/seed/c/400/300',
      ],
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 이커머스 제품 목록에서 호버 시 여러 각도의 제품 이미지를 미리 볼 때
• 포트폴리오 그리드에서 프로젝트의 스크린샷을 순서대로 보여줄 때
• 갤러리나 카탈로그에서 클릭 없이 빠른 이미지 미리 보기를 제공할 때

대신 다른 컴포넌트를 사용하세요:

• Carousel: 명시적인 탐색(화살표, 인디케이터)과 함께 이미지를 전환할 때
• Card: 호버 없이 단일 이미지를 카드 형태로 표시할 때

기본 사용법 (Basic Usage)#

// URL 리스트로 간편 생성
CoHoverGallery(
  imageUrls: [
    'https://example.com/product-1.jpg',
    'https://example.com/product-2.jpg',
    'https://example.com/product-3.jpg',
  ],
)

// 커스텀 위젯 빌더 (색상 컨테이너, SVG 등)
CoHoverGallery(
  itemCount: 3,
  itemBuilder: (index) => Container(
    color: [Colors.blue, Colors.green, Colors.orange][index],
  ),
)

// URL 리스트로 간편 생성
CoHoverGallery(
  imageUrls: [
    'https://example.com/product-1.jpg',
    'https://example.com/product-2.jpg',
    'https://example.com/product-3.jpg',
  ],
)

// 커스텀 컴포넌트 빌더
CoHoverGallery(
  itemCount: 3,
  itemBuilder: (index) => div(
    [],
    styles: Styles(raw: {
      'background': ['blue', 'green', 'orange'][index],
      'width': '100%',
      'height': '100%',
    }),
  ),
)

Props / Parameters#

동작 스펙 (Behavior)#

인터랙션#

• 호버 이동: 마우스 X 좌표에 따라 갤러리 영역을 이미지 수만큼 분할, 해당 영역의 이미지를 표시
• 클릭/탭: 탭한 위치의 이미지로 전환
• 호버 없음: 첫 번째 이미지만 표시

애니메이션#

• Flutter: AnimatedSwitcher로 crossfade (300ms)
• Web: CSS opacity transition (300ms)

사용 가이드라인 (Usage Guidelines)#

Do#

CoHoverGallery(
  imageUrls: product.images, // 모두 동일 비율 권장
  height: 200,
)

Don't#

// 20개의 이미지 — 호버로 탐색하기 어려움
CoHoverGallery(
  imageUrls: product.allImages, // 20장 이상
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: Semantics 위젯으로 이미지 설명 제공 권장
• Web: imageUrls 모드에서 자동 alt 텍스트 생성

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Carousel: 명시적 탐색 컨트롤이 있는 이미지 슬라이드
• Card: HoverGallery를 감싸 카드 레이아웃 구성에 사용
• DotIndicator: HoverGallery 아래에 현재 이미지 위치 표시