HTML 구조 & 스타일링

Flicking의 HTML 구조 작동 방식과 다양한 프레임워크에서 캐러셀의 외관을 커스터마이징하는 방법을 알아보세요.

---

HTML 구조 이해하기

Flicking은 정상적인 동작을 위해 필수적인 3레이어 구조를 사용합니다:

.flicking-viewport (보이는 영역)

캐러셀의 보이는 영역을 정의하는 가장 바깥쪽 컨테이너입니다.

• 페이지에서 사용자가 보는 영역입니다
• 여기에 너비와 높이를 설정하여 캐러셀의 보이는 크기를 제어합니다
• Flicking이 내부적으로 overflow: hidden을 자동으로 관리합니다

.flicking-camera (움직이는 컨테이너)

사용자가 스와이프하거나 탐색할 때 실제로 움직이는 중간 레이어입니다.

• 모든 패널을 포함하고 슬라이딩 동작을 처리합니다
• 이 요소에 직접 스타일을 적용하지 마세요 - Flicking이 위치와 transform을 관리합니다
• 이 요소의 스타일을 수정하면 캐러셀 기능이 망가질 수 있습니다

.panel (개별 슬라이드)

실제 콘텐츠 항목 - 각각이 캐러셀 슬라이드입니다.

• 자유롭게 스타일링하여 캐러셀 항목을 디자인하세요
• 패널 너비를 조절하여 한 번에 보이는 패널 수를 결정합니다
• 여백, 배경, 테두리 등을 필요에 따라 추가하세요

JavaScript vs React/Vue3

바닐라 JavaScript를 사용할 때는 HTML에 .flicking-viewport와 .flicking-camera 래퍼 div가 필요합니다. React와 Vue3 컴포넌트는 이를 자동으로 생성합니다.

---

필수 기본 CSS

Flicking이 올바르게 작동하려면 기본 CSS 파일을 임포트해야 합니다. 이는 선택 사항이 아닙니다 - 기본 CSS 없이는 캐러셀이 정상적으로 작동하지 않습니다.

CSS 임포트

JavaScript

import "@egjs/flicking/dist/flicking.css";

React

import "@egjs/react-flicking/dist/flicking.css";

Vue3

import "@egjs/vue3-flicking/dist/flicking.css";

또는 <style> 섹션에서:

@import url("@egjs/vue3-flicking/dist/flicking.css");

기본 CSS의 역할

기본 CSS는 Flicking이 작동하는 데 필수적인 스타일을 제공합니다:

1. 뷰포트 관리

.flicking-viewport {
  position: relative;    /* 카메라의 위치 기준점 */
  overflow: hidden;      /* 보이는 영역 밖의 패널 숨김 */
}

overflow: hidden이 없으면 활성 패널만 표시되는 대신 모든 패널이 한 번에 보입니다.

2. 카메라 레이아웃

.flicking-camera {
  display: flex;              /* 패널을 수평으로 배치 */
  flex-direction: row;        /* 수평 레이아웃 (세로 모드에서는 vertical) */
  will-change: transform;     /* 애니메이션 성능 최적화 */
}

Flexbox 레이아웃이 패널을 올바르게 배치하고 부드러운 슬라이딩 애니메이션을 가능하게 합니다.

3. 패널 크기 조정

.flicking-camera > * {
  flex-shrink: 0;            /* 패널이 축소되는 것을 방지 */
}

이렇게 하면 패널이 맞추기 위해 압축되지 않고 지정된 너비를 유지합니다.

기능 작동에 필수

기본 CSS가 없으면 Flicking이 올바르게 작동하지 않습니다:

• ❌ 모든 패널이 한 번에 표시됨 (overflow 숨김 없음)
• ❌ 잘못된 패널 레이아웃
• ❌ 슬라이딩 애니메이션 깨짐
• ❌ 성능 저하

반드시 기본 CSS 파일을 임포트하세요!

---

스타일링 가이드

Flicking은 스타일링 자유도를 극대화하기 위해 최소한의 기본 스타일을 제공합니다. 주관적인 디자인이나 제한적인 레이아웃이 없으며 캐러셀의 외관을 완전히 제어할 수 있습니다.

유일한 규칙: .flicking-camera 스타일(position, transform, width)을 수정하지 마세요. Flicking이 이를 내부적으로 관리합니다.

그 외 모든 것은 자유롭게 커스터마이징할 수 있습니다. 아래 예제는 시작하는 데 도움이 되는 참고 패턴이며, 필수 사항이 아닙니다. 디자인 요구에 맞게 자유롭게 수정하세요.

---

뷰포트 스타일링 (보이는 영역 제어)

JavaScript에서는 .flicking-viewport 클래스가 있는 HTML 요소에 스타일을 적용합니다:

<div id="carousel" class="flicking-viewport my-carousel">
  <div class="flicking-camera">
    <div class="panel">패널 1</div>
  </div>
</div>

.my-carousel {
  max-width: 1200px;
  margin: 0 auto;
  border-radius: 8px;
}

React/Vue3에서는 컴포넌트 자체가 .flicking-viewport로 렌더링되므로 커스텀 클래스를 컴포넌트에 직접 적용합니다:

React

{/* className은 Flicking 컴포넌트에 적용 */}
<Flicking className="my-carousel">
  <div className="panel">패널 1</div>
</Flicking>

/* 커스텀 클래스 스타일 - .flicking-viewport에 적용됨 */
.my-carousel {
  max-width: 1200px;
  margin: 0 auto;
  border-radius: 8px;
}

Vue3

<template>
  <!-- class는 Flicking 컴포넌트에 적용 -->
  <Flicking class="my-carousel">
    <div class="panel">패널 1</div>
  </Flicking>
</template>

<style scoped>
/* 커스텀 클래스 스타일 - .flicking-viewport에 적용됨 */
.my-carousel {
  max-width: 1200px;
  margin: 0 auto;
  border-radius: 8px;
}
</style>

핵심 차이점

• JavaScript: .flicking-viewport 요소를 직접 만들고 커스텀 클래스를 추가합니다
• React/Vue3: 컴포넌트가 내부적으로 .flicking-viewport를 생성하고 className/class를 적용합니다

결과는 동일합니다: 커스텀 스타일이 뷰포트에 적용됩니다!

---

패널 스타일링 (슬라이드 디자인)

/* 전체 너비 패널 (한 번에 하나의 패널) */
.panel {
  width: 100%;
  height: 400px;
  padding: 20px;
  background: #f9f9f9;
}

/* 고정 너비 패널 (여러 개 표시) */
.panel {
  width: 300px;        /* 고정 크기 */
  height: 400px;
  flex-shrink: 0;      /* 축소 방지 */
}

/* 패널 사이 간격 추가 */
.panel {
  margin-right: 20px;
}

/* 또는 flexbox의 gap 사용 (모던 방식) */
.flicking-camera {
  gap: 20px;          /* 모든 패널 사이 간격 */
}

---

일반적인 패턴

뷰 당 여러 패널

.panel {
  width: calc((100% - 40px) / 3);  /* 20px 간격의 3개 패널 */
  flex-shrink: 0;
}

반응형 패널

.panel {
  width: 100%;
  height: 400px;
}

@media (min-width: 768px) {
  .panel {
    width: 50%;      /* 태블릿에서 2개 패널 */
  }
}

@media (min-width: 1024px) {
  .panel {
    width: 33.333%;  /* 데스크탑에서 3개 패널 */
  }
}

.flicking-camera에 스타일을 적용하지 마세요

.flicking-camera에 width, height, transform 스타일을 추가하지 마세요. Flicking이 이 속성들을 내부적으로 제어합니다. 필요한 경우 간격(gap)만 사용하세요.

---

모범 사례

✅ 해야 할 것

• 기본 CSS 파일을 먼저 임포트하기
• .flicking-viewport와 .panel을 자유롭게 스타일링하기
• 스타일에 커스텀 클래스명 사용하기
• 다양한 화면 크기에서 반응형 디자인 테스트하기
• 패널 간격이 필요한 경우 .flicking-camera에 gap 사용하기

❌ 하지 말아야 할 것

• 기본 CSS 임포트를 생략하지 마세요
• .flicking-camera의 position, transform, width를 수정하지 마세요
• Flicking의 내부 스타일을 !important로 오버라이드하지 마세요
• .flicking-camera에 직접 margin을 추가하지 마세요