주요 콘텐츠로 건너뛰기 문서 탐색으로 건너뛰기
Check
in English

회전 목마

회전 목마와 같은 요소(이미지 또는 텍스트 슬라이드)를 순환하기 위한 슬라이드쇼 구성 요소입니다.

이 페이지에서

작동 방식

캐러셀은 CSS 3D 변환과 약간의 JavaScript로 구축된 일련의 콘텐츠를 순환하는 슬라이드쇼입니다. 일련의 이미지, 텍스트 또는 사용자 지정 마크업과 함께 작동합니다. 또한 이전/다음 컨트롤 및 표시기에 대한 지원도 포함합니다.

Page Visibility API 가 지원되는 브라우저에서 캐러셀은 웹페이지가 사용자에게 표시되지 않을 때(예: 브라우저 탭이 비활성화된 경우, 브라우저 창이 최소화된 경우 등) 슬라이딩을 방지합니다.

이 구성 요소의 애니메이션 효과는 prefers-reduced-motion미디어 쿼리에 따라 다릅니다. 접근성 설명서의 감소된 동작 섹션을 참조하십시오 .

중첩 캐러셀은 지원되지 않으며 캐러셀은 일반적으로 접근성 표준을 준수하지 않습니다.

예시

캐러셀은 슬라이드 크기를 자동으로 정규화하지 않습니다. 따라서 콘텐츠의 크기를 적절하게 조정하려면 추가 유틸리티나 사용자 정의 스타일을 사용해야 할 수도 있습니다. 캐러셀은 이전/다음 컨트롤 및 표시기를 지원하지만 명시적으로 필요하지는 않습니다. 필요에 따라 추가하고 사용자 정의하십시오.

.active슬라이드 중 하나에 클래스를 추가해야 합니다. 그렇지 않으면 캐러셀이 표시되지 않습니다. 또한 특히 단일 페이지에서 여러 캐러셀을 사용하는 경우 선택적 컨트롤 id에 대해 고유한 항목을 설정해야 합니다. .carousel제어 및 표시기 요소에는 요소와 일치하는 속성 ( data-bs-target또는 링크의 경우)이 있어야 합니다 .hrefid.carousel

슬라이드만

슬라이드만 있는 회전목마가 있습니다. 브라우저 기본 이미지 정렬을 방지하기 위해 .d-block및 캐러셀 이미지가 있는지 확인 합니다..w-100

HTML 
<div id="carouselExampleSlidesOnly" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
</div>

컨트롤 포함

이전 및 다음 컨트롤에 추가합니다. 요소를 사용하는 것이 좋지만 와 함께 요소를 <button>사용할 수도 있습니다 .<a>role="button"

HTML 
<div id="carouselExampleControls" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControls" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

지표 포함

컨트롤과 함께 캐러셀에 표시기를 추가할 수도 있습니다.

HTML 
<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="true">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

캡션 포함

.carousel-caption에 있는 요소 를 사용하여 슬라이드에 캡션을 쉽게 추가할 수 있습니다 .carousel-item. 옵션 표시 유틸리티 를 사용하여 아래와 같이 작은 뷰포트에서 쉽게 숨길 수 있습니다 . 처음에는 로 숨기고 .d-none중형 기기에서는 로 다시 가져옵니다 .d-md-block.

HTML 
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="false">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

크로스페이드

.carousel-fade슬라이드 대신 페이드 ​​전환을 사용하여 슬라이드에 애니메이션을 적용하려면 슬라이드에 추가 하세요. 캐러셀 콘텐츠(예: 텍스트 전용 슬라이드)에 따라 적절한 크로스페이딩 .bg-body을 위해 s에 또는 일부 사용자 정의 CSS를 추가할 수 있습니다..carousel-item

HTML 
<div id="carouselExampleFade" class="carousel slide carousel-fade" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleFade" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

에 추가 data-bs-interval=""하여 .carousel-item다음 항목으로의 자동 순환 사이의 지연 시간을 변경합니다.

HTML 
<div id="carouselExampleInterval" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleInterval" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

터치 스와이프 비활성화

캐러셀은 터치스크린 기기에서 왼쪽/오른쪽으로 스와이프하여 슬라이드 사이를 이동할 수 있도록 지원합니다. data-bs-touch속성 을 사용하여 비활성화할 수 있습니다 . 아래 예에는 data-bs-ride속성이 포함되어 있지 않으므로 자동 재생되지 않습니다.

HTML 
<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleControlsNoTouching" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

어두운 변종

더 어두운 컨트롤, 표시기 및 캡션을 위해 에 추가 .carousel-dark합니다 . 컨트롤이 CSS 속성 .carousel을 사용하여 기본 흰색 채우기에서 반전되었습니다 . 캡션과 컨트롤에는 및 filter를 사용자 지정하는 추가 Sass 변수가 있습니다 .colorbackground-color

HTML 
<div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="...">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

사용자 지정 전환

의 전환 기간은 컴파일하기 전에 Sass 변수를 사용하거나 컴파일된 CSS를 사용하는 경우 사용자 정의 스타일 .carousel-item로 변경할 수 있습니다 . $carousel-transition-duration여러 전환이 적용되는 경우 변형 전환이 먼저 정의되었는지 확인하십시오(예: transition: transform 2s ease, opacity .5s ease-out).

사스

변수

모든 캐러셀에 대한 변수:

$carousel-control-color:             $white;
$carousel-control-width:             15%;
$carousel-control-opacity:           .5;
$carousel-control-hover-opacity:     .9;
$carousel-control-transition:        opacity .15s ease;

$carousel-indicator-width:           30px;
$carousel-indicator-height:          3px;
$carousel-indicator-hit-area-height: 10px;
$carousel-indicator-spacer:          3px;
$carousel-indicator-opacity:         .5;
$carousel-indicator-active-bg:       $white;
$carousel-indicator-active-opacity:  1;
$carousel-indicator-transition:      opacity .6s ease;

$carousel-caption-width:             70%;
$carousel-caption-color:             $white;
$carousel-caption-padding-y:         1.25rem;
$carousel-caption-spacer:            1.25rem;

$carousel-control-icon-width:        2rem;

$carousel-control-prev-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/></svg>");
$carousel-control-next-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/></svg>");

$carousel-transition-duration:       .6s;
$carousel-transition:                transform $carousel-transition-duration ease-in-out; // Define transform transition first if using multiple transitions (e.g., `transform 2s ease, opacity .5s ease-out`)

다크 캐러셀 의 변수 :

$carousel-dark-indicator-active-bg:  $black;
$carousel-dark-caption-color:        $black;
$carousel-dark-control-icon-filter:  invert(1) grayscale(100);

용법

데이터 속성을 통해

데이터 속성을 사용하여 캐러셀의 위치를 ​​쉽게 제어할 수 있습니다. 현재 위치를 기준으로 슬라이드 위치를 변경하는 또는 data-bs-slide키워드를 허용합니다 . 또는 를 사용 하여 슬라이드 위치를 로 시작하는 특정 인덱스로 이동하는 캐러셀에 원시 슬라이드 인덱스를 전달합니다 .prevnextdata-bs-slide-todata-bs-slide-to="2"0

이 data-bs-ride="carousel"속성은 캐러셀을 페이지 로드 시 시작되는 애니메이션으로 표시하는 데 사용됩니다. 캐러셀을 초기화하는 데 사용하지 않는 경우 data-bs-ride="carousel"직접 초기화해야 합니다. 동일한 캐러셀의 (중복적이고 불필요한) 명시적 JavaScript 초기화와 함께 사용할 수 없습니다.

자바스크립트를 통해

다음을 사용하여 수동으로 캐러셀을 호출합니다.

const carousel = new bootstrap.Carousel('#myCarousel')

옵션

옵션은 데이터 속성이나 JavaScript를 통해 전달할 수 있으므로 에서 data-bs-와 같이 옵션 이름을 에 추가할 수 있습니다 data-bs-animation="{value}". 데이터 속성을 통해 옵션을 전달할 때 옵션 이름의 대소문자 유형을 " camelCase "에서 " kebab-case "로 변경해야 합니다. 예를 들어, data-bs-custom-class="beautifier"대신 를 사용 data-bs-customClass="beautifier"하십시오.

Bootstrap 5.2.0부터 모든 구성 요소 는 JSON 문자열로 간단한 구성 요소 구성을 수용할 수 있는 실험적 으로 예약된 데이터 속성 을 지원합니다. data-bs-config요소에 data-bs-config='{"delay":0, "title":123}'및 data-bs-title="456"속성이 있는 경우 최종 title값은 456이고 별도의 데이터 속성은 에 제공된 값을 재정의합니다 data-bs-config. 또한 기존 데이터 속성은 와 같은 JSON 값을 저장할 수 data-bs-delay='{"show":0,"hide":150}'있습니다.

이름 유형 기본 설명
interval 숫자 5000 항목을 자동으로 순환하는 사이의 지연 시간입니다.
keyboard 부울 true 캐러셀이 키보드 이벤트에 반응해야 하는지 여부입니다.
pause 문자열, 부울 "hover" 로 설정 "hover"하면 캐러셀의 순환이 일시 중지되고 캐러셀 mouseenter의 순환이 다시 시작됩니다 mouseleave. 로 설정 false하면 캐러셀 위로 마우스를 가져가도 일시중지되지 않습니다. 터치 지원 장치에서 로 설정하면 "hover"사이클링이 touchend자동으로 다시 시작되기 전에 두 간격 동안(사용자가 캐러셀과의 상호작용을 마치면) 일시 중지됩니다. 이것은 마우스 동작에 추가됩니다.
ride 문자열, 부울 false 로 설정 true하면 사용자가 첫 번째 항목을 수동으로 순환한 후 캐러셀이 자동 재생됩니다. 로 설정하면 "carousel"로드 시 캐러셀이 자동 재생됩니다.
touch 부울 true 캐러셀이 터치스크린 기기에서 왼쪽/오른쪽으로 스와이프 상호작용을 지원해야 하는지 여부입니다.
wrap 부울 true 캐러셀이 계속 순환해야 하는지 아니면 정지해야 하는지 여부.

행동 양식

비동기식 메서드 및 전환

모든 API 메서드는 비동기식 이며 전환 을 시작합니다 . 전환이 시작되자마자 그러나 끝나기 전에 호출자에게 돌아갑니다 . 또한 전환 구성 요소에 대한 메서드 호출은 무시 됩니다.

자세한 내용은 JavaScript 설명서를 참조하십시오 .

예를 들어 추가 옵션으로 초기화하고 항목 순환을 시작하기 위해 캐러셀 생성자를 사용하여 캐러셀 인스턴스를 만들 수 있습니다.

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000,
  wrap: false
})
방법 설명
cycle 캐러셀 항목을 왼쪽에서 오른쪽으로 순환합니다.
dispose 요소의 회전 목마를 파괴합니다. (DOM 요소에 저장된 데이터 제거)
getInstance DOM 요소와 연결된 캐러셀 인스턴스를 가져올 수 있는 정적 메서드는 다음과 같이 사용할 수 있습니다 bootstrap.Carousel.getInstance(element).
getOrCreateInstance DOM 요소에 연결된 캐러셀 인스턴스를 반환하거나 초기화되지 않은 경우 새 인스턴스를 만드는 정적 메서드입니다. 다음과 같이 사용할 수 있습니다 bootstrap.Carousel.getOrCreateInstance(element).
next 다음 항목으로 순환합니다. 다음 항목이 표시 되기 전에(예: 이벤트가 발생하기 전에) 호출자에게 반환합니다 .slid.bs.carousel
nextWhenVisible 페이지가 표시되지 않거나 캐러셀 또는 해당 상위 항목이 표시되지 않는 경우 캐러셀을 다음으로 순환하지 마세요. 대상 항목이 표시되기 전에 호출자에게 반환됩니다 .
pause 캐러셀이 항목을 순환하는 것을 중지합니다.
prev 이전 항목으로 순환합니다. 이전 항목이 표시 되기 전(예: slid.bs.carousel이벤트가 발생하기 전) 호출자에게 반환합니다.
to 캐러셀을 특정 프레임으로 순환합니다(0 기반, 배열과 유사). 대상 항목이 표시 되기 전(예: 이벤트가 발생하기 전) 호출자에게 반환합니다 .slid.bs.carousel

이벤트

부트스트랩의 캐러셀 클래스는 캐러셀 기능에 연결하기 위한 두 가지 이벤트를 노출합니다. 두 이벤트에는 다음과 같은 추가 속성이 있습니다.

  • direction: 캐러셀이 미끄러지는 방향( "left"또는 "right").
  • relatedTarget: 활성 항목으로 슬라이드되는 DOM 요소입니다.
  • from: 현재 항목의 인덱스
  • to: 다음 항목의 인덱스

모든 캐러셀 이벤트는 캐러셀 자체(즉, <div class="carousel">)에서 발생합니다.

이벤트 유형 설명
slid.bs.carousel 캐러셀이 슬라이드 전환을 완료하면 시작됩니다.
slide.bs.carousel slide인스턴스 메서드가 호출 되면 즉시 발생합니다 . 
const myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', event => {
  // do something...
})