팝오버
iOS에서 볼 수 있는 것과 같은 부트스트랩 팝오버를 사이트의 모든 요소에 추가하기 위한 문서 및 예제입니다.
개요
팝오버 플러그인을 사용할 때 알아야 할 사항:
- Popover는 위치 지정을 위해 타사 라이브러리 Popper 에 의존합니다 . 전에 popper.min.js 를 포함
bootstrap.js하거나bootstrap.bundle.min.jsPopper가 포함된 것을 사용해야 합니다. - 팝오버 에는 종속성으로 팝오버 플러그인 이 필요합니다 .
- 팝오버는 성능상의 이유로 선택되어 있으므로 직접 초기화해야 합니다 .
- 길이가 0
title이고content값은 팝오버를 표시하지 않습니다. container: 'body'더 복잡한 구성 요소(예: 입력 그룹, 버튼 그룹 등)에서 렌더링 문제를 방지하려면 지정 합니다.- 숨겨진 요소에 대한 팝오버 트리거는 작동하지 않습니다.
.disabled또는 요소 에 대한 팝오버disabled는 래퍼 요소에서 트리거되어야 합니다.- 여러 줄을 가로지르는 앵커에서 트리거되면 팝오버가 앵커의 전체 너비 사이 중앙에 위치합니다. 이 동작을 방지 하려면
.text-nowrap에 사용하십시오.<a> - 팝오버는 해당 요소가 DOM에서 제거되기 전에 숨겨야 합니다.
- 팝오버는 shadow DOM 내부의 요소 덕분에 트리거될 수 있습니다.
prefers-reduced-motion미디어 쿼리에 따라 다릅니다. 접근성 설명서의 감소된 동작 섹션을 참조하십시오
.
몇 가지 예에서 팝오버가 작동하는 방식을 보려면 계속 읽으십시오.
예
팝오버 활성화
위에서 언급했듯이 팝오버를 사용하려면 먼저 초기화해야 합니다. 페이지의 모든 팝오버를 초기화하는 한 가지 방법은 다음 data-bs-toggle과 같이 속성별로 선택하는 것입니다.
const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl))
라이브 데모
위의 스니펫과 유사한 JavaScript를 사용하여 다음 라이브 팝오버를 렌더링합니다. 를 통해 제목을 설정 data-bs-title하고 를 통해 본문 내용을 설정합니다 data-bs-content.
title하십시오
. data-bs-title가 사용 되면
Popper는 요소가 렌더링될 때
title자동으로 대체합니다
.data-bs-title<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>네 방향
위, 오른쪽, 아래 및 왼쪽의 네 가지 옵션을 사용할 수 있습니다. RTL에서 부트스트랩을 사용할 때 방향이 미러링됩니다. data-bs-placement방향을 변경하도록 설정 합니다.
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
Popover on left
</button>관습container
container팝오버를 방해하는 일부 스타일이 상위 요소에 있는 경우 팝오버의 HTML이 대신 해당 요소 내에 나타나도록 사용자 정의를 지정하고 싶을 것입니다. 이것은 응답 테이블, 입력 그룹 등에서 일반적입니다.
const popover = new bootstrap.Popover('.example-popover', {
container: 'body'
})
명시적 사용자 정의를 설정하려는 또 다른 상황 은 팝오버 자체가 모달에 추가되도록 하기 위해 모달 대화 상자container 내부 의 팝오버입니다. 이것은 대화형 요소를 포함하는 팝오버에 특히 중요합니다. 모달 대화 상자는 포커스를 트랩하므로 팝오버가 모달의 자식 요소가 아니면 사용자는 이러한 대화형 요소에 포커스를 맞추거나 활성화할 수 없습니다.
const popover = new bootstrap.Popover('.example-popover', {
container: '.modal-body'
})
커스텀 팝오버
v5.2.0에 추가됨CSS 변수 를 사용하여 팝오버의 모양을 사용자 정의할 수 있습니다 . 사용자 정의 모양의 범위를 지정하기 위해 사용자 정의 클래스를 설정하고 data-bs-custom-class="custom-popover"이를 사용하여 일부 로컬 CSS 변수를 재정의합니다.
.custom-popover {
--bs-popover-max-width: 200px;
--bs-popover-border-color: var(--bs-primary);
--bs-popover-header-bg: var(--bs-primary);
--bs-popover-header-color: var(--bs-white);
--bs-popover-body-padding-x: 1rem;
--bs-popover-body-padding-y: .5rem;
}
<button type="button" class="btn btn-secondary"
data-bs-toggle="popover" data-bs-placement="right"
data-bs-custom-class="custom-popover"
data-bs-title="Custom popover"
data-bs-content="This popover is themed via CSS variables.">
Custom popover
</button>다음 클릭 시 닫기
focus사용자가 다음에 토글 요소가 아닌 다른 요소를 클릭할 때 팝오버를 해제 하려면 트리거를 사용하십시오 .
다음 클릭 시 닫기에 필요한 특정 마크업
적절한 크로스 브라우저 및 크로스 플랫폼 동작을 위해서는 <a>태그가 아닌 태그 를 사용해야 하며 속성 <button>도 포함해야 합니다.tabindex
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>const popover = new bootstrap.Popover('.popover-dismiss', {
trigger: 'focus'
})
장애인 요소
속성이 있는 요소는 disabled대화형이 아니므로 사용자가 해당 요소를 가리키거나 클릭하여 팝오버(또는 도구 설명)를 트리거할 수 없습니다. 이 문제를 해결하려면 래퍼 <div>또는 <span>, 이상적으로는 tabindex="0".
비활성화된 팝오버 트리거 의 경우 비활성화된 요소 를 클릭data-bs-trigger="hover focus" 할 것으로 예상하지 않을 수 있으므로 팝오버가 사용자에게 즉각적인 시각적 피드백으로 나타나도록 할 수도 있습니다 .
<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
<button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>CSS
변수
v5.2.0에 추가됨Bootstrap의 진화하는 CSS 변수 접근 방식의 일부로, 팝오버는 이제 .popover향상된 실시간 사용자 정의를 위해 로컬 CSS 변수를 사용합니다. CSS 변수의 값은 Sass를 통해 설정되므로 Sass 사용자 정의도 계속 지원됩니다.
--#{$prefix}popover-zindex: #{$zindex-popover};
--#{$prefix}popover-max-width: #{$popover-max-width};
@include rfs($popover-font-size, --#{$prefix}popover-font-size);
--#{$prefix}popover-bg: #{$popover-bg};
--#{$prefix}popover-border-width: #{$popover-border-width};
--#{$prefix}popover-border-color: #{$popover-border-color};
--#{$prefix}popover-border-radius: #{$popover-border-radius};
--#{$prefix}popover-inner-border-radius: #{$popover-inner-border-radius};
--#{$prefix}popover-box-shadow: #{$popover-box-shadow};
--#{$prefix}popover-header-padding-x: #{$popover-header-padding-x};
--#{$prefix}popover-header-padding-y: #{$popover-header-padding-y};
@include rfs($popover-header-font-size, --#{$prefix}popover-header-font-size);
--#{$prefix}popover-header-color: #{$popover-header-color};
--#{$prefix}popover-header-bg: #{$popover-header-bg};
--#{$prefix}popover-body-padding-x: #{$popover-body-padding-x};
--#{$prefix}popover-body-padding-y: #{$popover-body-padding-y};
--#{$prefix}popover-body-color: #{$popover-body-color};
--#{$prefix}popover-arrow-width: #{$popover-arrow-width};
--#{$prefix}popover-arrow-height: #{$popover-arrow-height};
--#{$prefix}popover-arrow-border: var(--#{$prefix}popover-border-color);
Sass 변수
$popover-font-size: $font-size-sm;
$popover-bg: $white;
$popover-max-width: 276px;
$popover-border-width: $border-width;
$popover-border-color: var(--#{$prefix}border-color-translucent);
$popover-border-radius: $border-radius-lg;
$popover-inner-border-radius: subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow: $box-shadow;
$popover-header-font-size: $font-size-base;
$popover-header-bg: shade-color($popover-bg, 6%);
$popover-header-color: $headings-color;
$popover-header-padding-y: .5rem;
$popover-header-padding-x: $spacer;
$popover-body-color: $body-color;
$popover-body-padding-y: $spacer;
$popover-body-padding-x: $spacer;
$popover-arrow-width: 1rem;
$popover-arrow-height: .5rem;
용법
JavaScript를 통해 팝오버 활성화:
const exampleEl = document.getElementById('example')
const popover = new bootstrap.Popover(exampleEl, options)
키보드 및 보조 기술 사용자를 위한 팝오버 작동 만들기
키보드 사용자가 팝오버를 활성화할 수 있도록 하려면 전통적으로 키보드에 초점을 맞출 수 있고 대화형인 HTML 요소(예: 링크 또는 양식 컨트롤)에만 팝오버를 추가해야 합니다. 속성을 추가하여 임의의 HTML 요소(예: <span>s)에 초점을 맞출 수 있지만 tabindex="0", 이는 키보드 사용자를 위해 비대화형 요소에 잠재적으로 성가시고 혼란스러운 탭 정지를 추가하며 현재 대부분의 보조 기술은 이 상황에서 팝오버의 내용을 알리지 않습니다. . 또한 팝오버에 대한 트리거로만 의존하지 마십시오. hover이렇게 하면 키보드 사용자가 팝오버를 트리거할 수 없게 됩니다.
옵션 을 사용하여 팝오버에 풍부하고 구조화된 HTML을 삽입할 수 있지만 html과도한 양의 콘텐츠를 추가하지 않는 것이 좋습니다. 현재 팝오버가 작동하는 방식은 일단 표시되면 해당 콘텐츠가 aria-describedby속성이 있는 트리거 요소에 연결된다는 것입니다. 결과적으로 팝오버의 전체 콘텐츠는 하나의 길고 중단 없는 스트림으로 보조 기술 사용자에게 발표됩니다.
또한 팝오버에 대화형 컨트롤(예: 양식 요소 또는 링크)을 포함할 수도 있지만(허용되는 속성 및 태그에 이러한 요소를 추가하여 allowList) 현재 팝오버는 키보드 포커스 순서를 관리하지 않는다는 점에 유의하십시오. 키보드 사용자가 팝오버를 열면 포커스는 트리거 요소에 유지되고 팝오버는 일반적으로 문서 구조에서 트리거를 즉시 따르지 않기 때문에 앞으로/누르는 것이 보장되지 않습니다.TAB키보드 사용자를 팝오버 자체로 이동합니다. 간단히 말해서, 단순히 팝오버에 대화형 컨트롤을 추가하면 키보드 사용자와 보조 기술 사용자가 이러한 컨트롤에 접근할 수 없거나 사용할 수 없게 되거나 최소한 비논리적인 전체 포커스 순서를 만들 수 있습니다. 이러한 경우 대신 모달 대화 상자를 사용하는 것이 좋습니다.
옵션
옵션은 데이터 속성이나 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}'있습니다.
sanitize,
sanitizeFn및
allowList옵션을 제공할 수 없습니다.
| 이름 | 유형 | 기본 | 설명 |
|---|---|---|---|
allowList |
물체 | 기본값 | 허용된 속성 및 태그가 포함된 개체입니다. |
animation |
부울 | true |
팝오버에 CSS 페이드 전환을 적용합니다. |
boundary |
문자열, 요소 | 'clippingParents' |
팝오버의 오버플로 제약 조건 경계(팝퍼의 preventOverflow 수정자에만 적용됨). 기본적으로 'clippingParents'HTMLElement 참조를 허용하고 허용할 수 있습니다(JavaScript를 통해서만). 자세한 내용은 Popper의 detectOverflow 문서 를 참조하십시오 . |
container |
문자열, 요소, 거짓 | false |
특정 요소에 팝오버를 추가합니다. 예: container: 'body'. 이 옵션은 문서 흐름에서 팝오버를 트리거 요소 근처에 배치할 수 있다는 점에서 특히 유용합니다. 이렇게 하면 창 크기 조정 중에 팝오버가 트리거 요소에서 떠다니는 것을 방지할 수 있습니다. |
content |
문자열, 요소, 함수 | '' |
data-bs-content속성이 없는 경우 기본 콘텐츠 값 입니다. 함수가 주어지면 this팝오버가 연결된 요소로 설정된 참조로 호출됩니다. |
customClass |
문자열, 함수 | '' |
팝오버가 표시되면 클래스를 추가합니다. 이러한 클래스는 템플릿에 지정된 클래스 외에 추가됩니다. 여러 클래스를 추가하려면 공백으로 구분합니다 'class-1 class-2'. 추가 클래스 이름을 포함하는 단일 문자열을 반환해야 하는 함수를 전달할 수도 있습니다. |
delay |
숫자, 개체 | 0 |
팝오버 표시 및 숨기기 지연(ms) - 수동 트리거 유형에는 적용되지 않습니다. 숫자가 제공되면 숨기기/표시 모두에 지연이 적용됩니다. 개체 구조: delay: { "show": 500, "hide": 100 }. |
fallbackPlacements |
문자열, 배열 | ['top', 'right', 'bottom', 'left'] |
배열의 게재위치 목록을 제공하여 대체 게재위치를 정의합니다(선호도 순서대로). 자세한 내용은 Popper의 행동 문서 를 참조하십시오 . |
html |
부울 | false |
팝오버에서 HTML을 허용합니다. true이면 팝오버의 HTML 태그가 팝오버에서 title렌더링됩니다. false인 경우 innerText속성을 사용하여 DOM에 콘텐츠를 삽입합니다. XSS 공격이 걱정된다면 텍스트를 사용하세요. |
offset |
숫자, 문자열, 함수 | [0, 0] |
대상을 기준으로 한 팝오버의 오프셋입니다. 다음과 같이 쉼표로 구분된 값을 사용하여 데이터 속성의 문자열을 전달할 수 있습니다 data-bs-offset="10,20". 오프셋을 결정하는 데 함수가 사용되면 포퍼 배치, 참조 및 포퍼 사각형을 첫 번째 인수로 포함하는 객체와 함께 호출됩니다. 트리거 요소 DOM 노드는 두 번째 인수로 전달됩니다. 함수는 두 개의 숫자( skidding , distance ) 가 있는 배열을 반환해야 합니다 . 자세한 내용은 Popper의 오프셋 문서 를 참조하십시오 . |
placement |
문자열, 함수 | 'top' |
팝오버 위치 지정 방법: 자동, 위, 아래, 왼쪽, 오른쪽. auto가 지정되면 팝오버의 방향을 동적으로 변경합니다 . 위치를 결정하는 데 함수가 사용되면 첫 번째 인수로 팝오버 DOM 노드를 사용하고 두 번째 인수로 트리거 요소 DOM 노드를 사용하여 호출됩니다. 컨텍스트 는 this팝오버 인스턴스로 설정됩니다. |
popperConfig |
null, 객체, 함수 | null |
Bootstrap의 기본 Popper 구성을 변경하려면 Popper의 구성 을 참조하십시오 . 함수가 Popper 구성을 생성하는 데 사용되면 Bootstrap의 기본 Popper 구성을 포함하는 객체와 함께 호출됩니다. 기본값을 사용하고 고유한 구성과 병합하는 데 도움이 됩니다. 함수는 Popper에 대한 구성 개체를 반환해야 합니다. |
sanitize |
부울 | true |
살균을 활성화하거나 비활성화합니다. 활성화 'template'되면 옵션 'content'이 'title'삭제됩니다. |
sanitizeFn |
널, 함수 | null |
여기에서 자신만의 살균 기능을 제공할 수 있습니다. 이는 삭제를 수행하기 위해 전용 라이브러리를 사용하려는 경우에 유용할 수 있습니다. |
selector |
문자열, 거짓 | false |
선택기가 제공되면 팝오버 개체가 지정된 대상에 위임됩니다. 실제로 이것은 동적으로 추가된 DOM 요소에 팝오버를 적용하는 데에도 사용됩니다( jQuery.on지원). 이 문제 와 유익한 예를 참조하십시오 . |
template |
끈 | '<div class="popover" role="popover"><div class="popover-arrow"></div><div class="popover-inner"></div></div>' |
팝오버를 생성할 때 사용할 기본 HTML입니다. 팝오버 title는 에 주입됩니다 .popover-inner. .popover-arrow팝오버의 화살이 될 것입니다. 가장 바깥쪽 래퍼 요소에는 .popover클래스 및 role="popover". |
title |
문자열, 요소, 함수 | '' |
title속성이 없는 경우 기본 제목 값 입니다. 함수가 주어지면 this팝오버가 연결된 요소로 설정된 참조로 호출됩니다. |
trigger |
끈 | 'hover focus' |
팝오버가 트리거되는 방법: 클릭, 호버, 포커스, 수동. 여러 트리거를 전달할 수 있습니다. 공백으로 구분하십시오. 팝오버가 , 및 메서드 'manual'를 통해 프로그래밍 방식으로 트리거됨을 나타냅니다 . 이 값은 다른 트리거와 결합할 수 없습니다. 그 자체로 키보드를 통해 트리거할 수 없는 팝오버가 발생하며 키보드 사용자에게 동일한 정보를 전달하는 대체 방법이 있는 경우에만 사용해야 합니다..popover('show').popover('hide').popover('toggle')'hover' |
기능 사용popperConfig
const popover = new bootstrap.Popover(element, {
popperConfig(defaultBsPopperConfig) {
// const newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
행동 양식
비동기식 메서드 및 전환
모든 API 메서드는 비동기식 이며 전환 을 시작합니다 . 전환이 시작되자마자 그러나 끝나기 전에 호출자에게 돌아갑니다 . 또한 전환 구성 요소에 대한 메서드 호출은 무시 됩니다.
| 방법 | 설명 |
|---|---|
disable |
요소의 팝오버가 표시되는 기능을 제거합니다. 팝오버는 다시 활성화된 경우에만 표시될 수 있습니다. |
dispose |
요소의 팝오버를 숨기고 제거합니다(DOM 요소에 저장된 데이터 제거). 위임을 사용하는 팝오버( 옵션 을 사용 하여selector 생성됨 )는 하위 트리거 요소에서 개별적으로 소멸될 수 없습니다. |
enable |
요소의 팝오버에 표시할 수 있는 기능을 제공합니다. 팝오버는 기본적으로 활성화되어 있습니다. |
getInstance |
DOM 요소와 연결된 팝오버 인스턴스를 가져올 수 있는 정적 메서드입니다. |
getOrCreateInstance |
DOM 요소와 연결된 팝오버 인스턴스를 가져오거나 초기화되지 않은 경우 새 인스턴스를 만들 수 있는 정적 메서드입니다. |
hide |
요소의 팝오버를 숨깁니다. 팝오버가 실제로 숨겨 지기 전에(즉, hidden.bs.popover이벤트가 발생하기 전에) 호출자에게 반환합니다. 이것은 팝오버의 "수동" 트리거로 간주됩니다. |
setContent |
초기화 후 팝오버의 내용을 변경하는 방법을 제공합니다. |
show |
요소의 팝오버를 표시합니다. 팝오버가 실제로 표시 되기 전에(즉, shown.bs.popover이벤트가 발생하기 전에) 호출자에게 반환합니다. 이것은 팝오버의 "수동" 트리거로 간주됩니다. 제목과 내용이 모두 길이가 0인 팝오버는 표시되지 않습니다. |
toggle |
요소의 팝오버를 토글합니다. 팝오버가 실제로 표시되거나 숨겨 지기 전에(즉, shown.bs.popover또는 hidden.bs.popover이벤트가 발생하기 전에) 호출자에게 반환합니다. 이것은 팝오버의 "수동" 트리거로 간주됩니다. |
toggleEnabled |
요소의 팝오버를 표시하거나 숨길 수 있는 기능을 토글합니다. |
update |
요소의 팝오버 위치를 업데이트합니다. |
// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance
// setContent example
myPopover.setContent({
'.popover-header': 'another title',
'.popover-body': 'another content'
})
setContent메서드는
object인수를 허용합니다. 여기서 각 속성 키는
string팝오버 템플릿 내에서 유효한 선택기이고 관련된 각 속성 값은
string|
element|
function|
null
이벤트
| 이벤트 | 설명 |
|---|---|
hide.bs.popover |
hide이 이벤트는 인스턴스 메서드가 호출 되면 즉시 시작됩니다 . |
hidden.bs.popover |
이 이벤트는 팝오버가 사용자에게 숨겨지면 시작됩니다(CSS 전환이 완료될 때까지 기다림). |
inserted.bs.popover |
이 이벤트는 show.bs.popover팝오버 템플릿이 DOM에 추가되었을 때 이벤트 후에 시작됩니다. |
show.bs.popover |
show이 이벤트는 인스턴스 메서드가 호출 되면 즉시 발생합니다 . |
shown.bs.popover |
이 이벤트는 팝오버가 사용자에게 표시되면 시작됩니다(CSS 전환이 완료될 때까지 기다림). |
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
// do something...
})