콜랩스

콜랩스 (Collapse)

몇 가지 클래스와 JavaScript 플러그인으로 프로젝트 전반의 콘텐츠 표시 여부를 토글합니다.

출처: 문서

본문

동작 방식 (How it works)

콜랩스 JavaScript 플러그인은 콘텐츠를 보이고 숨기는 데 사용됩니다. 버튼이나 앵커가 트리거로 쓰이며, 토글하려는 특정 요소에 매핑됩니다. 요소를 접으면 그 높이가 현재 값에서 0으로 애니메이션됩니다. CSS가 애니메이션을 처리하는 방식 때문에 .collapse 요소에는 padding을 사용할 수 없습니다. 대신 그 클래스를 별도의 감싸는(wrapping) 요소로 사용하세요.

이 컴포넌트의 애니메이션 효과는 prefers-reduced-motion 미디어 쿼리에 의존합니다. 저희 접근성 문서의 reduced motion 섹션을 참고하세요.

예제 (Example)

아래 버튼을 클릭하면 클래스 변경을 통해 다른 요소를 보이거나 숨길 수 있습니다.

  • .collapse는 콘텐츠를 숨깁니다.
  • .collapsing은 전환 중에 적용됩니다.
  • .collapse.show는 콘텐츠를 보여줍니다.

일반적으로 data-bs-target 속성이 있는 <button>을 사용하는 것을 권장합니다. 의미론적 관점에서 권장되지는 않지만, href 속성(그리고 role="button")을 가진 <a> 링크를 쓸 수도 있습니다. 두 경우 모두 data-bs-toggle="collapse"가 필요합니다.

<p class="d-inline-flex gap-1">
  <a class="btn btn-primary" data-bs-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample">
    Link with href
  </a>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
    Button with data-bs-target
  </button>
</p>
<div class="collapse" id="collapseExample">
  <div class="card card-body">
    Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
  </div>
</div>

가로 접기 (Horizontal)

콜랩스 플러그인은 가로 접기를 지원합니다. .collapse-horizontal 변형 클래스를 추가하면 높이 대신 너비가 전환되고, 바로 아래 자식 요소에 너비를 설정하세요. 직접 Sass를 작성하거나, 인라인 스타일을 쓰거나, 너비 유틸리티를 사용해도 좋습니다.

아래 예시에는 문서에서 과도한 리페인트를 피하려고 min-height가 설정되어 있지만, 반드시 필요한 것은 아닙니다. 자식 요소의 너비만 있으면 됩니다.

<p>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseWidthExample" aria-expanded="false" aria-controls="collapseWidthExample">
    Toggle width collapse
  </button>
</p>
<div style="min-height: 120px;">
  <div class="collapse collapse-horizontal" id="collapseWidthExample">
    <div class="card card-body" style="width: 300px;">
      This is some placeholder content for a horizontal collapse. It’s hidden by default and shown when triggered.
    </div>
  </div>
</div>

여러 토글과 타깃 (Multiple toggles and targets)

<button> 또는 <a> 요소는 data-bs-target이나 href 속성에 셀렉터를 참조해 여러 요소를 보이거나 숨길 수 있습니다. 반대로 여러 <button> 또는 <a> 요소가 각자의 data-bs-target이나 href 속성으로 같은 요소를 참조해 동일 요소를 보이거나 숨길 수도 있습니다.

<p class="d-inline-flex gap-1">
  <a class="btn btn-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">Toggle first element</a>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">Toggle second element</button>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target=".multi-collapse" aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">Toggle both elements</button>
</p>
<div class="row">
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample1">
      <div class="card card-body">
        Some placeholder content for the first collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
      </div>
    </div>
  </div>
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample2">
      <div class="card card-body">
        Some placeholder content for the second collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
      </div>
    </div>
  </div>
</div>

접근성 (Accessibility)

컨트롤 요소에 aria-expanded를 꼭 추가하세요. 이 속성은 컨트롤에 연결된 콜랩스 요소의 현재 상태를 스크린 리더 같은 보조 기술에 명시적으로 전달합니다. 콜랩스 요소가 기본적으로 닫혀 있다면 컨트롤 요소의 이 속성은 aria-expanded="false"여야 합니다. show 클래스로 콜랩스 요소를 기본 열림으로 설정했다면 대신 컨트롤에 aria-expanded="true"를 설정하세요. 플러그인은 콜랩스 요소가 열렸는지 닫혔는지(JavaScript로, 또는 사용자가 같은 콜랩스 요소에 연결된 다른 컨트롤 요소를 트리거했을 때)에 따라 이 속성을 자동으로 토글합니다. 컨트롤 요소의 HTML 요소가 버튼(예: <a>나 <div>)이 아니라면 role="button" 속성을 추가해야 합니다.

컨트롤 요소가 단일 콜랩스 요소를 타깃한다면 — 즉 data-bs-target 속성이 id 셀렉터를 가리킨다면 — 콜랩스 요소의 id를 담은 aria-controls 속성을 컨트롤 요소에 추가하세요. 최신 스크린 리더와 이와 유사한 보조 기술은 이 속성을 이용해 사용자에게 콜랩스 요소 자체로 직접 이동하는 추가 단축키를 제공합니다.

참고: Bootstrap의 현재 구현은 ARIA Authoring Practices Guide의 accordion 패턴에 설명된 다양한 선택적 키보드 상호작용을 다루지 않습니다 – 이것들은 커스텀 JavaScript로 직접 포함해야 합니다.

CSS

Sass 변수 (Sass variables)

$transition-collapse:         height .35s ease;
$transition-collapse-width:   width .35s ease;

클래스 (Classes)

콜랩스 전환 클래스는 여러 컴포넌트(콜랩스와 어코디언)에서 공유되므로 scss/_transitions.scss에서 찾을 수 있습니다.

.collapse {
  &:not(.show) {
    display: none;
  }
}

.collapsing {
  height: 0;
  overflow: hidden;
  @include transition($transition-collapse);

  &.collapse-horizontal {
    width: 0;
    height: auto;
    @include transition($transition-collapse-width);
  }
}

사용법 (Usage)

콜랩스 플러그인은 무거운 작업을 처리하기 위해 몇 가지 클래스를 사용합니다.

  • .collapse는 콘텐츠를 숨깁니다.
  • .collapse.show는 콘텐츠를 보여줍니다.
  • .collapsing은 전환이 시작될 때 추가되고 끝나면 제거됩니다.

이 클래스들은 _transitions.scss에서 찾을 수 있습니다.

데이터 속성으로 (Via data attributes)

요소에 data-bs-toggle="collapse"와 data-bs-target을 추가하기만 하면 하나 이상의 콜랩스 요소의 컨트롤이 자동으로 지정됩니다. data-bs-target 속성은 콜랩스를 적용할 CSS 셀렉터를 받습니다. 콜랩스 요소에 collapse 클래스를 추가하는 것을 잊지 마세요. 기본 열림으로 설정하고 싶으면 show 클래스를 추가하세요.

콜랩스 영역에 어코디언 같은 그룹 관리를 추가하려면 data-bs-parent="#selector" 데이터 속성을 추가하세요. 자세한 내용은 accordion 페이지를 참고하세요.

JavaScript로 (Via JavaScript)

수동으로 활성화합니다:

const collapseElementList = document.querySelectorAll('.collapse')
const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl))

옵션 (Options)

옵션은 데이터 속성이나 JavaScript로 전달할 수 있으므로 data-bs-animation="{value}"처럼 data-bs-에 옵션 이름을 붙일 수 있습니다. 데이터 속성으로 옵션을 전달할 때는 옵션 이름의 표기(camelCase)를 "kebab-case"로 바꿔야 합니다. 예를 들어 data-bs-customClass="beautifier" 대신 data-bs-custom-class="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에 주어진 값을 덮어씁니다. 또한 기존 데이터 속성이 data-bs-delay='{"show":0,"hide":150}'처럼 JSON 값을 담을 수 있습니다.

최종 설정 객체는 data-bs-config, data-bs-, js 객체를 병합한 결과로, 가장 나중에 주어진 키-값이 다른 것들을 덮어씁니다.

이름 타입 기본값 설명
parent selector, DOM element null parent가 제공되면, 지정된 parent 아래의 모든 콜랩스 요소는 이 콜랩스 항목이 표시될 때 닫힙니다. (전통적인 어코디언 동작과 유사 – 이는 card 클래스에 의존합니다.) 이 속성은 타깃 콜랩스 영역에 설정해야 합니다.
toggle boolean true 호출 시 콜랩스 요소를 토글합니다.

메서드 (Methods)

모든 API 메서드는 비동기이며 전환을 시작합니다. 전환이 시작되자마자, 즉 끝나기 전에 호출자에게 반환됩니다. 또한 전환 중인 컴포넌트에 대한 메서드 호출은 무시됩니다. 자세한 내용은 JavaScript 문서를 참고하세요.

콘텐츠를 콜랩스 요소로 활성화합니다. 선택적 options 객체를 받습니다.

생성자(constructor)로 콜랩스 인스턴스를 만들 수 있습니다:

const bsCollapse = new bootstrap.Collapse('#myCollapse', {
  toggle: false
})
메서드 설명
dispose 요소의 콜랩스를 파괴합니다. (DOM 요소에 저장된 데이터를 제거합니다.)
getInstance DOM 요소에 연결된 콜랩스 인스턴스를 가져올 수 있는 정적 메서드입니다. 이렇게 사용할 수 있습니다: bootstrap.Collapse.getInstance(element).
getOrCreateInstance DOM 요소에 연결된 콜랩스 인스턴스를 반환하거나, 초기화되지 않았다면 새로 만드는 정적 메서드입니다. 이렇게 사용할 수 있습니다: bootstrap.Collapse.getOrCreateInstance(element).
hide 콜랩스 요소를 숨깁니다. 콜랩스 요소가 실제로 숨겨지기 전에(즉, hidden.bs.collapse 이벤트가 발생하기 전에) 호출자에게 반환됩니다.
show 콜랩스 요소를 보여줍니다. 콜랩스 요소가 실제로 보이기 전에(즉, shown.bs.collapse 이벤트가 발생하기 전에) 호출자에게 반환됩니다.
toggle 콜랩스 요소를 보이거나 숨김으로 토글합니다. 콜랩스 요소가 실제로 보이거나 숨겨지기 전에(즉, shown.bs.collapse 또는 hidden.bs.collapse 이벤트가 발생하기 전에) 호출자에게 반환됩니다.

이벤트 (Events)

Bootstrap의 콜랩스 클래스는 콜랩스 기능에 훅을 걸기 위한 몇 가지 이벤트를 노출합니다.

이벤트 타입 설명
hide.bs.collapse hide 메서드가 호출되는 즉시 발생합니다.
hidden.bs.collapse 콜랩스 요소가 사용자에게 숨겨졌을 때 발생합니다 (CSS 전환이 완료될 때까지 기다립니다).
show.bs.collapse show 인스턴스 메서드가 호출되는 즉시 발생합니다.
shown.bs.collapse 콜랩스 요소가 사용자에게 보이게 되었을 때 발생합니다 (CSS 전환이 완료될 때까지 기다립니다). 
const myCollapsible = document.getElementById('myCollapsible')
myCollapsible.addEventListener('hidden.bs.collapse', event => {
  // do something...
})

더 알아보기 (Learn more)