본문 바로가기

비개발자의 개발 일지

현장 팀장에서 수출 ERP까지 — AI와 함께 시스템을 만든 기록

시리즈 보기
php

부트스트랩 캐러셀 · 모달 · 스크롤스파이 완전 정리

by 왕진 2026. 7. 18.
반응형

 

 

Bootstrap JavaScript

부트스트랩 캐러셀 · 모달 · 스크롤스파이 완전 정리

캐러셀, 모달, 스크롤스파이를 Bootstrap 3 JavaScript 컴포넌트 흐름으로 정리합니다.

0 오늘 분석할 코드
<div id="carousel-example-generic" class="carousel slide">...</div>
<button class="btn btn-primary" data-toggle="modal" data-target="#myModal">모달 열기</button>
<div class="modal fade" id="myModal" tabindex="-1" role="dialog">...</div>
<div data-spy="scroll" data-target="#navbar-example2" data-offset="0" class="scrollspy-example">
  <h4 id="fat">@fat</h4>
</div>
<script>$('.carousel').carousel()</script>
carousel여러 슬라이드를 좌우로 넘기는 컴포넌트입니다.
carousel-inner슬라이드 item들을 담는 영역입니다.
carousel-indicators현재 슬라이드 위치를 표시하는 점 목록입니다.
modal화면 위에 뜨는 대화상자 컴포넌트입니다.
modal-dialog모달 창의 외형 위치를 담당합니다.
data-toggleBootstrap 3에서 JS 동작을 연결하는 속성입니다.
scrollspy스크롤 위치에 따라 nav active를 바꾸는 기능입니다.
data-target동작 대상이 되는 요소 선택자입니다.
1 세 컴포넌트의 공통점

캐러셀, 모달, 스크롤스파이는 모두 Bootstrap JavaScript 플러그인이 필요합니다. CSS 클래스만으로 외형 일부는 보일 수 있지만, 슬라이드 전환, 모달 열기, 스크롤 위치 감지는 jQuery와 bootstrap.min.js가 있어야 동작합니다.

  • jQuery를 먼저 로드합니다.
  • bootstrap.min.js를 그 다음 로드합니다.
  • data-toggle, data-target, data-spy 같은 속성이 동작을 연결합니다.
  • id와 href/data-target 선택자가 정확히 일치해야 합니다.
2 캐러셀 기본 구조
클래스/속성 역할 주의
carousel slide 캐러셀 전체 id가 컨트롤 href와 연결됩니다.
carousel-indicators 슬라이드 점 data-slide-to 번호가 item 순서와 맞아야 합니다.
carousel-inner 슬라이드 묶음 item들을 감쌉니다.
item active 첫 슬라이드 active가 없으면 처음 화면이 비어 보일 수 있습니다.
3 캐러셀 컨트롤

left carousel-control과 right carousel-control은 이전/다음 슬라이드 이동 버튼입니다. href는 캐러셀 id를 가리키고 data-slide는 prev 또는 next입니다.

  1. 캐러셀 전체에 고유 id를 붙입니다.
  2. 왼쪽 컨트롤 href를 그 id로 맞춥니다.
  3. data-slide="prev"를 둡니다.
  4. 오른쪽 컨트롤은 data-slide="next"를 둡니다.
  5. icon-prev와 icon-next로 방향 아이콘을 표시합니다.

 

반응형

 

4 캐러셀 이미지

원문은 slide1.jpg, slide2.jpg, slide3.jpg를 item 안에 배치합니다. 이미지 경로가 틀리면 캐러셀 구조는 보이지만 화면이 비어 보일 수 있습니다.

  • 모든 이미지 경로가 HTML 파일 기준으로 맞는지 확인합니다.
  • alt에는 First slide 같은 대체 문구를 넣습니다.
  • 이미지 비율이 다르면 슬라이드 높이가 흔들릴 수 있습니다.
  • 첫 item에는 active를 반드시 둡니다.
5 캐러셀 초기화

원문은 $('.carousel').carousel()로 캐러셀을 초기화합니다. data 속성만으로도 동작할 수 있지만, 명시 초기화는 플러그인 연결 여부를 확인하기 좋습니다.

클래스/속성 역할 주의
$('.carousel').carousel() 캐러셀 초기화 jQuery 필요
data-slide-to 특정 슬라이드 번호 0부터 시작
data-slide prev/next 이동 컨트롤에 사용
active 현재 슬라이드 item과 indicator에 사용
6 모달 열기

모달은 버튼이나 링크에 data-toggle="modal"과 data-target="#myModal"을 붙여 엽니다. a 태그는 href="#myModal"과 data-toggle="modal" 조합도 가능합니다.

클래스/속성 역할 주의
data-toggle=modal 모달 동작 연결 Bootstrap JS 필요
data-target=#myModal 열 모달 id id와 정확히 일치
btn btn-primary 버튼 외형 트리거 요소
href=#myModal 링크 트리거 a 태그 방식
7 모달 구조

modal fade 안에 modal-dialog, modal-content, modal-header, modal-body, modal-footer가 순서대로 들어갑니다. 각 영역을 나누면 제목, 본문, 버튼을 명확히 관리할 수 있습니다.

  1. div.modal.fade에 id를 지정합니다.
  2. modal-dialog로 창 영역을 만듭니다.
  3. modal-content 안에 실제 콘텐츠를 넣습니다.
  4. modal-header에는 제목과 닫기 버튼을 둡니다.
  5. modal-body에는 본문을 둡니다.
  6. modal-footer에는 닫기와 저장 버튼을 둡니다.
8 모달 접근성

원문은 role="dialog", aria-labelledby, aria-hidden, sr-only Close를 사용합니다. 모달은 포커스와 닫기 동작이 중요하므로 접근성 속성을 함께 확인해야 합니다.

클래스/속성 역할 주의
role=dialog 대화상자 의미 보조기술에 구조 전달
aria-labelledby 제목 연결 modal-title id와 연결
tabindex=-1 포커스 제어 모달 열림 시 포커스 이동
data-dismiss=modal 닫기 버튼 Bootstrap JS가 처리
9 스크롤스파이 구조

스크롤스파이는 nav 링크의 href와 본문 섹션 id를 연결합니다. data-spy="scroll"이 붙은 스크롤 영역은 data-target으로 nav를 가리킵니다.

클래스/속성 역할 주의
data-spy=scroll 스크롤 감지 스크롤 영역에 붙임
data-target=#navbar-example2 대상 nav nav id와 일치
data-offset 활성화 보정값 고정 헤더 높이 보정
href=#fat 섹션 링크 본문 id와 일치
10 스크롤스파이 nav

원문은 navbar 안에 @fat, @mdo 링크와 dropdown 내부 one, two, three 링크를 둡니다. 각 href는 본문 h4의 id와 연결됩니다.

  • nav 링크 href="#fat"은 h4 id="fat"과 연결됩니다.
  • dropdown 내부 링크도 스크롤스파이 대상이 될 수 있습니다.
  • 스크롤 영역에는 충분한 높이와 overflow가 필요합니다.
  • 외부 doc.css가 스크롤 영역 스타일을 담당할 수 있습니다.
11 스크롤 영역

scrollspy-example 영역 안에는 여러 h4와 p가 이어집니다. 스크롤 위치가 바뀔 때 가장 가까운 섹션에 해당하는 nav 항목이 active로 바뀝니다.

  1. 스크롤 가능한 컨테이너를 만듭니다.
  2. 각 섹션 제목에 id를 붙입니다.
  3. nav 링크 href를 같은 id로 맞춥니다.
  4. data-spy와 data-target을 설정합니다.
  5. 스크롤하면서 active 변화가 맞는지 확인합니다.
12 JavaScript 로드 순서

세 예제 모두 문서 하단에 jQuery와 bootstrap.min.js를 로드합니다. 이 순서가 바뀌면 Bootstrap 플러그인이 jQuery를 찾지 못해 동작하지 않습니다.

클래스/속성 역할 주의
jQuery 먼저 로드 Bootstrap 3 플러그인의 기반
bootstrap.min.js 나중 로드 모달, 캐러셀, 스크롤스파이 제공
초기화 스크립트 마지막 플러그인 로드 후 실행
콘솔 확인 오류 확인 $ is not defined 등 확인
13 Bootstrap 3 기준

원문은 Bootstrap 3 문법입니다. Bootstrap 5에서는 data-toggle이 data-bs-toggle로 바뀌고, item은 carousel-item으로 바뀌는 등 차이가 큽니다.

클래스/속성 역할 주의
item Bootstrap 3 캐러셀 항목 Bootstrap 4/5는 carousel-item
data-toggle Bootstrap 3/4 방식 Bootstrap 5는 data-bs-toggle
left/right control Bootstrap 3 컨트롤 최신 버전은 carousel-control-prev/next
jQuery 의존 Bootstrap 3 필요 Bootstrap 5는 jQuery 불필요
14 실전 선택 기준
목표 컴포넌트 이유
이미지 홍보 영역 carousel 여러 이미지를 좁은 공간에 순차 표시합니다.
확인 대화상자 modal 현재 화면 위에서 중요한 결정을 받습니다.
긴 문서 목차 scrollspy 현재 읽는 섹션을 nav에 표시합니다.
드롭다운 포함 목차 scrollspy + dropdown 하위 섹션까지 연결할 수 있습니다.
15 검증 체크리스트
  • 캐러셀 id와 indicator data-target, control href가 모두 일치합니다.
  • 첫 carousel item과 indicator에 active가 있습니다.
  • 모달 trigger의 data-target과 modal id가 일치합니다.
  • 모달 닫기 버튼에 data-dismiss="modal"이 있습니다.
  • 스크롤스파이 nav href와 본문 id가 일치합니다.
  • jQuery, bootstrap.min.js, 초기화 스크립트 순서가 맞습니다.
16 접근성 점검
  • 캐러셀 이미지는 의미 있는 alt를 갖습니다.
  • 자동 슬라이드가 사용자를 방해하지 않는지 확인합니다.
  • 모달 제목은 aria-labelledby와 연결합니다.
  • 모달 닫기 버튼은 키보드와 스크린리더에서 이해 가능해야 합니다.
  • 스크롤스파이 링크 텍스트는 섹션 제목을 충분히 설명해야 합니다.
17 컴포넌트별 디버깅
컴포넌트 증상 확인할 것
carousel 슬라이드가 넘어가지 않음 bootstrap.min.js 로드와 carousel id 연결
carousel 첫 이미지가 안 보임 첫 item에 active가 있는지 확인
modal 버튼 클릭 후 아무 반응 없음 data-target과 modal id 일치 여부
modal 닫기 버튼이 동작하지 않음 data-dismiss="modal"과 스크립트 로드
scrollspy active가 바뀌지 않음 스크롤 영역 높이, data-target, 섹션 id
dropdown 스크롤스파이 하위 메뉴가 안 열림 dropdown-toggle과 Bootstrap JS
18 실전 적용 순서
  1. 구조 작성: id, class, data 속성을 먼저 맞춥니다.
  2. 리소스 확인: 이미지 파일, CSS, jQuery, bootstrap.min.js 경로를 확인합니다.
  3. 초기 상태 확인: active 항목, 모달 제목, 스크롤 영역을 점검합니다.
  4. 동작 테스트: 클릭, 닫기, 이전/다음, 스크롤 이동을 실제로 실행합니다.
  5. 접근성 보완: alt, aria, sr-only, 키보드 조작을 확인합니다.
19 최신 버전 이전 메모
  • Bootstrap 5에서는 data-toggle 대신 data-bs-toggle을 사용합니다.
  • carousel의 item 클래스는 carousel-item으로 바뀐 버전이 있습니다.
  • 모달 닫기 속성도 data-dismiss에서 data-bs-dismiss로 바뀔 수 있습니다.
  • Bootstrap 5는 jQuery 의존성이 없으므로 초기화 방식이 달라집니다.
  • 스크롤스파이는 offset 처리와 target 설정을 버전 문서에 맞춰 다시 확인해야 합니다.
  • 마이그레이션 전에는 원본 예제의 Bootstrap 버전을 파일 주석이나 문서에 남깁니다.
  • 동작이 있는 컴포넌트는 클래스 변환 후 반드시 실제 클릭과 스크롤 테스트를 다시 합니다.
  • 이미지나 긴 본문 같은 샘플 데이터도 실제 서비스 데이터 길이로 바꿔 레이아웃을 확인합니다.
  • 접근성 속성은 버전 변경 후에도 삭제하지 말고 최신 권장 방식으로 갱신합니다.
  • 캐러셀 자동 전환 시간은 사용자가 내용을 읽을 수 있을 만큼 충분한지 확인합니다.
  • 모달 안의 저장 버튼은 실제 저장 로직과 닫기 동작을 분리해서 설계합니다.
  • 스크롤스파이 대상 영역은 높이와 overflow 설정이 실제 스크롤을 만들고 있는지 확인합니다.
  • 드롭다운이 포함된 nav는 작은 화면에서 collapse와 함께 정상 동작하는지 확인합니다.
M 자주 하는 실수
실수 문제 해결
스크립트 로드 순서 오류 컴포넌트가 동작하지 않습니다. jQuery 다음 bootstrap.min.js를 로드합니다.
캐러셀 active 누락 첫 화면이 비어 보일 수 있습니다. 첫 item과 indicator에 active를 둡니다.
모달 id 불일치 버튼을 눌러도 모달이 열리지 않습니다. data-target과 modal id를 맞춥니다.
스크롤스파이 id 불일치 active가 바뀌지 않습니다. nav href와 섹션 id를 맞춥니다.
Bootstrap 5 문법과 혼동 data-toggle이 동작하지 않을 수 있습니다. 원문은 Bootstrap 3 기준으로 읽습니다.

핵심 한 줄 요약

carousel캐러셀은 id, indicator, item active, control 연결이 핵심입니다.
modal모달은 trigger와 modal id 연결, header/body/footer 구조가 핵심입니다.
scrollspy스크롤스파이는 nav href와 본문 id를 정확히 맞춰야 합니다.

Tags

#Bootstrap#carousel#modal#scrollspy#data-toggle#data-target#jQuery#Bootstrap3#JavaScript#티스토리
▼ 티스토리 태그 입력란 복사용
Bootstrap, carousel, modal, scrollspy, data-toggle, data-target, jQuery, Bootstrap3, JavaScript, 티스토리
반응형

'php' 카테고리의 다른 글

부트스트랩 이벤트 · jQuery 초기화 완전 정리  (0) 2026.07.18
부트스트랩 어코디언 · 툴팁 · 팝오버 · 어픽스 완전 정리  (0) 2026.07.18
부트스트랩 라벨 · 배지 · 알림 · 목록그룹 완전 정리  (0) 2026.07.18
부트스트랩 드롭다운 · 점보트론 · 내비게이션바 · 진행바 완전 정리  (0) 2026.07.18
부트스트랩 네비게이션 · 페이지네이션 · 패널 완전 정리  (0) 2026.07.17

관련글

댓글

티스토리툴바