본문 바로가기

비개발자의 개발 일지

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

시리즈 보기
php

부트스트랩 캐러셀 캡션 · 모달 메서드 · 팝오버 메서드 완전 정리

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

 

 

Bootstrap Methods

부트스트랩 캐러셀 캡션 · 모달 메서드 · 팝오버 메서드 완전 정리

캐러셀 캡션과 커스텀 컨트롤, 모달 옵션, 팝오버 메서드 사용법을 Bootstrap 3 기준으로 정리합니다.

0 오늘 분석할 코드
<div class="carousel-caption"><h3>슬라이드 효과</h3><p>캡션</p></div>
<div id="custom_carousel" class="carousel slide" data-ride="carousel" data-interval="2500">...</div>
<script>
$('#custom_carousel').on('slide.bs.carousel', function (evt) {
  $('#custom_carousel .controls li.active').removeClass('active');
  $('#custom_carousel .controls li:eq(' + $(evt.relatedTarget).index() + ')').addClass('active');
});
$('#myModal').modal({ keyboard: true });
$('.popover-show').popover('show');
$('.popover-options a').popover({ html: true });
</script>
carousel-caption캐러셀 이미지 위에 제목과 설명을 올리는 영역입니다.
data-ride캐러셀 자동 실행을 지정하는 Bootstrap 3/4 속성입니다.
data-interval슬라이드 자동 전환 간격입니다.
relatedTarget캐러셀 이벤트에서 다음 슬라이드 요소를 가리킵니다.
modal()모달 플러그인을 jQuery 방식으로 초기화합니다.
keyboardESC 키로 모달을 닫을지 정하는 옵션입니다.
popover('show')팝오버를 즉시 표시하는 메서드입니다.
html:true팝오버 content/title 안 HTML 해석을 허용합니다.
1 문서 전체 흐름

105번 폴더는 단순 Bootstrap 컴포넌트 사용을 넘어 메서드와 이벤트로 제어하는 예제입니다. 캐러셀 캡션, 커스텀 캐러셀 컨트롤, 모달 옵션, 팝오버 show/hide/destroy/toggle과 html 옵션을 함께 다룹니다.

  • 캐러셀 캡션은 이미지 위의 제목과 설명입니다.
  • 커스텀 캐러셀은 아래쪽 controls li를 슬라이드 상태와 동기화합니다.
  • 모달은 modal({ keyboard: true })로 옵션을 전달합니다.
  • 팝오버는 문자열 메서드로 상태를 제어합니다.
2 carousel-caption
항목 역할 주의
carousel-caption 슬라이드 설명 영역 item 내부에 둡니다.
h3 캡션 제목 짧고 명확하게
p 캡션 설명 이미지와 겹치지 않게
item active 첫 슬라이드 처음 보이는 항목
3 캡션 작성 주의

caption 내부에는 HTML 태그를 사용할 수 있지만, 이미지 위에 올라가기 때문에 대비와 길이가 중요합니다. 모바일에서 캡션이 이미지 주요 부분을 가리지 않는지도 확인해야 합니다.

  • 캡션 제목은 짧게 유지합니다.
  • 배경 이미지가 밝으면 글자 대비가 낮아질 수 있습니다.
  • 긴 설명은 슬라이드 밖 본문으로 분리합니다.
  • 각 슬라이드의 alt와 caption이 서로 보완되게 작성합니다.

 

반응형

 

4 custom_carousel 구조

custom_carousel 예제는 기본 indicators 대신 하단 nav li를 컨트롤로 사용합니다. 각 li는 data-target="#custom_carousel"과 data-slide-to 번호를 갖습니다.

항목 역할 주의
data-ride=carousel 자동 실행 페이지 로드 후 시작
data-interval=2500 전환 간격 2.5초마다 이동
controls li 하단 메뉴 data-slide-to로 슬라이드 연결
li.active 현재 메뉴 이벤트에서 갱신
5 slide.bs.carousel 이벤트

커스텀 캐러셀은 slide.bs.carousel 이벤트에서 evt.relatedTarget의 index를 읽어 하단 controls의 active를 갱신합니다.

$('#custom_carousel').on('slide.bs.carousel', function (evt) {
  $('#custom_carousel .controls li.active').removeClass('active');
  $('#custom_carousel .controls li:eq(' + $(evt.relatedTarget).index() + ')').addClass('active');
});
6 relatedTarget 이해

relatedTarget은 이벤트가 이동하려는 다음 슬라이드 item입니다. $(evt.relatedTarget).index()는 carousel-inner 안에서 몇 번째 item인지 반환하므로 controls li와 순서가 같아야 합니다.

  1. 슬라이드 전환이 시작됩니다.
  2. 이벤트 객체에 relatedTarget이 들어옵니다.
  3. 다음 item의 index를 구합니다.
  4. 기존 controls li.active를 제거합니다.
  5. 같은 index의 controls li에 active를 붙입니다.
7 커스텀 컨트롤 CSS

controls는 가로 스크롤 가능한 nav처럼 스타일링되어 있습니다. white-space:nowrap과 display:table-cell로 항목을 한 줄에 배치합니다.

항목 역할 주의
overflow-x:auto 가로 스크롤 항목이 많을 때 대응
white-space:nowrap 줄바꿈 방지 메뉴를 한 줄 유지
display:table-cell 균등 셀 느낌 li 배치
active border-top 현재 항목 강조 빨간 선으로 표시
8 modal 메서드

modal-method 예제는 버튼 data-toggle로 모달을 열 수 있게 하고, 동시에 $('#myModal').modal({ keyboard: true })로 옵션을 전달합니다. keyboard true는 ESC 키로 닫을 수 있음을 의미합니다.

항목 역할 주의
$('#myModal').modal(...) 모달 초기화 jQuery 방식
keyboard:true ESC 닫기 허용 기본값 확인 필요
data-target=#myModal 버튼 연결 id 일치 필요
data-dismiss=modal 닫기 버튼 Bootstrap JS 필요
9 모달 구조 점검

모달은 modal, modal-dialog, modal-content, modal-header, modal-body, modal-footer의 계층을 유지해야 합니다. 구조가 깨지면 스타일과 포커스 동작이 어색해질 수 있습니다.

  • modal id는 고유해야 합니다.
  • aria-labelledby는 modal-title id를 가리킵니다.
  • 닫기 버튼은 header와 footer에 둘 수 있습니다.
  • 저장 버튼은 실제 저장 로직과 연결해야 합니다.
10 popover 메서드
항목 역할 주의
popover('show') 즉시 표시 페이지 로드 시 바로 보일 수 있음
popover('hide') 숨김 초기에는 보이지 않음
popover('destroy') 인스턴스 제거 다시 사용하려면 재초기화 필요
popover('toggle') 표시/숨김 전환 버튼 클릭형 동작에 적합
11 popover 옵션

popover-options 예제는 html:true를 사용해 title과 content 안의 HTML 태그를 해석합니다. 강력하지만 사용자 입력을 그대로 넣으면 보안 위험이 생길 수 있습니다.

$(".popover-options a").popover({
  html: true
});

학습용 고정 HTML에는 사용할 수 있지만, 사용자 입력에는 sanitize나 text 출력 방식을 고려해야 합니다.

12 메서드 선택 기준
상황 메서드 이유
안내를 처음부터 보여 줌 show 사용자 주목이 필요합니다.
초기 상태 숨김 hide 필요할 때만 표시합니다.
동적 UI 제거 destroy 이벤트와 데이터를 정리합니다.
버튼으로 열고 닫기 toggle 상태 전환이 간단합니다.
HTML 설명 허용 {html:true} 제목/본문에 태그를 쓸 수 있습니다.
13 리소스 경로

custom_carousel은 ./css, ./js, ./imgs 경로를 사용하고, 다른 예제는 ../css, ../js를 사용합니다. 폴더 구조가 다르면 CSS와 이미지가 바로 깨질 수 있습니다.

  • slide 이미지 경로를 실제 위치와 맞춥니다.
  • bootstrap.min.js 경로가 예제마다 다릅니다.
  • normalize 파일명은 원문에서 nomalize.css로 되어 있습니다.
  • 이미지 alt는 빈 값보다 구체적인 설명이 좋습니다.
14 JavaScript 로드 순서

모든 메서드는 jQuery 플러그인으로 등록된 뒤 호출해야 합니다. 따라서 jQuery, bootstrap.min.js, 사용자 초기화 스크립트 순서를 지킵니다.

항목 역할 주의
jQuery 첫 번째 $ 함수 제공
bootstrap.min.js 두 번째 modal/popover/carousel 등록
사용자 스크립트 세 번째 이벤트와 메서드 호출
$(document).ready DOM 준비 후 실행 요소 선택 안정화
15 Bootstrap 3 기준

item, data-toggle, modal jQuery 메서드, popover jQuery 메서드는 Bootstrap 3 문법입니다. 최신 버전에서는 클래스명과 초기화 API가 달라질 수 있습니다.

항목 역할 주의
item Bootstrap 3 캐러셀 항목 최신은 carousel-item
data-toggle Bootstrap 3/4 Bootstrap 5는 data-bs-toggle
popover('show') jQuery 플러그인 방식 최신은 JS 인스턴스 방식 검토
btn-default Bootstrap 3 버튼 최신은 btn-secondary 계열
16 디버깅 체크리스트
  • 캐러셀 id와 controls data-target이 일치합니다.
  • controls li 개수와 item 개수가 같습니다.
  • relatedTarget index와 controls 순서가 같습니다.
  • modal id와 button data-target이 일치합니다.
  • popover 메서드를 호출하기 전에 대상 요소가 존재합니다.
  • html:true 사용 시 입력값 출처를 확인합니다.
17 접근성 점검
  • 캐러셀 캡션은 이미지 대체 텍스트와 중복/보완 관계를 고려합니다.
  • 자동 슬라이드는 사용자가 읽을 시간을 충분히 줍니다.
  • 모달은 제목 연결과 닫기 버튼 접근성을 유지합니다.
  • 팝오버에 중요한 정보만 숨기지 말고 본문에도 핵심을 남깁니다.
  • HTML 팝오버는 스크린리더에서 읽히는 순서를 확인합니다.
18 메서드별 디버깅
기능 증상 확인할 것
custom carousel 하단 메뉴 active가 안 바뀜 slide.bs.carousel 이벤트와 relatedTarget index
carousel caption 캡션이 안 보임 item 내부에 carousel-caption이 있는지 확인
modal method ESC가 동작하지 않음 keyboard 옵션과 포커스 상태
popover show 페이지 로드 시 안 보임 초기화 호출 시점과 대상 선택자
popover destroy 다시 열리지 않음 destroy 후 재초기화 필요 여부
html option HTML이 문자로 보임 {html:true} 옵션 적용 여부
19 운영 적용 순서
  1. 기본 구조 확인: 캐러셀, 모달, 팝오버 HTML 구조가 먼저 정상인지 봅니다.
  2. 스크립트 순서 확인: jQuery, bootstrap.min.js, 사용자 스크립트 순서를 지킵니다.
  3. 이벤트 연결: slide.bs.carousel 같은 이벤트가 실제 발생하는지 확인합니다.
  4. 상태 동기화: 슬라이드와 하단 controls의 active가 같은 index를 가리키는지 봅니다.
  5. 보안 검토: html:true 팝오버에는 신뢰된 HTML만 넣습니다.
20 최신 버전 이전 메모
  • Bootstrap 5에서는 jQuery 플러그인 메서드 호출 방식이 그대로 동작하지 않습니다.
  • data-toggle은 data-bs-toggle로 바뀌며, 초기화 API도 JavaScript 클래스 중심입니다.
  • carousel item 클래스명과 이벤트 객체 구조를 버전 문서에서 다시 확인합니다.
  • popover html 옵션은 보안 정책과 sanitizer 설정까지 함께 확인합니다.
  • btn-default는 최신 버전에서 btn-secondary 계열로 바꿔야 할 수 있습니다.
M 자주 하는 실수
실수 문제 해결
controls와 item 개수 불일치 active 표시가 다른 항목에 붙습니다. li와 item 순서를 맞춥니다.
relatedTarget index 오해 현재 슬라이드가 아니라 다음 슬라이드 기준입니다. 이벤트 시점을 확인합니다.
modal 옵션을 로드 전 호출 modal 함수가 없습니다. bootstrap.min.js 뒤에서 호출합니다.
popover destroy 후 재사용 기대 인스턴스가 제거되어 동작하지 않습니다. 필요하면 다시 초기화합니다.
html:true에 사용자 입력 사용 HTML 삽입 위험이 있습니다. 신뢰된 고정 HTML만 사용합니다.

핵심 한 줄 요약

carousel커스텀 캐러셀은 slide 이벤트의 relatedTarget index로 컨트롤 active를 맞춥니다.
modal모달은 jQuery modal 메서드에 옵션 객체를 전달해 동작을 조절합니다.
popover팝오버는 show, hide, destroy, toggle 메서드와 html 옵션을 사용할 수 있습니다.

Tags

#Bootstrap#carousel#carousel-caption#modal#popover#jQuery#relatedTarget#data-interval#Bootstrap3#티스토리
▼ 티스토리 태그 입력란 복사용
Bootstrap, carousel, carousel-caption, modal, popover, jQuery, relatedTarget, data-interval, Bootstrap3, 티스토리
반응형

'php' 카테고리의 다른 글

부트스트랩 alert메서드 · 캐러셀메서드 · 쇼핑몰 레이아웃 완전 정리  (0) 2026.07.18
부트스트랩 탭 이벤트 · collapse메서드 · 툴팁메서드 · 영수증 폼 완전 정리  (0) 2026.07.18
부트스트랩 이벤트 · jQuery 초기화 완전 정리  (0) 2026.07.18
부트스트랩 어코디언 · 툴팁 · 팝오버 · 어픽스 완전 정리  (0) 2026.07.18
부트스트랩 캐러셀 · 모달 · 스크롤스파이 완전 정리  (0) 2026.07.18

관련글

댓글

티스토리툴바