Chuyển đến nội dung chính Chuyển đến điều hướng tài liệu
in English

Popovers

Tài liệu và ví dụ để thêm các cửa sổ bật lên Bootstrap, như các cửa sổ bật lên được tìm thấy trong iOS, vào bất kỳ phần tử nào trên trang web của bạn.

Tổng quan

Những điều cần biết khi sử dụng plugin popover:

  • Popover dựa vào thư viện Popper của bên thứ 3 để định vị. Bạn phải bao gồm popper.min.js trước bootstrap.js hoặc sử dụng bootstrap.bundle.min.js/ bootstrap.bundle.jscó chứa Popper để popover hoạt động!
  • Các cửa sổ bật lên yêu cầu plugin chú giải công cụ như một phần phụ thuộc.
  • Cửa sổ bật lên được chọn tham gia vì lý do hiệu suất, vì vậy bạn phải tự khởi tạo chúng .
  • Độ dài bằng 0 titlecontentcác giá trị sẽ không bao giờ hiển thị cửa sổ bật lên.
  • Chỉ định container: 'body'để tránh các sự cố hiển thị trong các thành phần phức tạp hơn (như nhóm đầu vào, nhóm nút của chúng tôi, v.v.).
  • Kích hoạt cửa sổ bật lên trên các phần tử ẩn sẽ không hoạt động.
  • Cửa sổ bật lên cho .disabledhoặc disabledcác phần tử phải được kích hoạt trên một phần tử trình bao bọc.
  • Khi được kích hoạt từ các neo bao quanh nhiều dòng, các cửa sổ bật lên sẽ được căn giữa giữa chiều rộng tổng thể của các neo. Sử dụng .text-nowraptrên <a>s của bạn để tránh hành vi này.
  • Các cửa sổ bật lên phải được ẩn trước khi các phần tử tương ứng của chúng bị xóa khỏi DOM.
  • Popover có thể được kích hoạt nhờ vào một phần tử bên trong Shadow DOM.
Theo mặc định, thành phần này sử dụng trình vệ sinh nội dung tích hợp, loại bỏ bất kỳ phần tử HTML nào không được phép rõ ràng. Xem phần sanitizer trong tài liệu JavaScript của chúng tôi để biết thêm chi tiết.
Hiệu ứng hoạt ảnh của thành phần này phụ thuộc vào prefers-reduced-motiontruy vấn phương tiện. Xem phần chuyển động giảm trong tài liệu hỗ trợ tiếp cận của chúng tôi .

Hãy tiếp tục đọc để biết cách hoạt động của các cửa sổ bật lên với một số ví dụ.

Ví dụ: Bật cửa sổ bật lên ở mọi nơi

Một cách để khởi tạo tất cả các cửa sổ bật lên trên một trang là chọn chúng theo data-bs-togglethuộc tính của chúng:

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

Ví dụ: Sử dụng containertùy chọn

Khi bạn có một số kiểu trên phần tử mẹ cản trở cửa sổ bật lên, bạn sẽ muốn chỉ định một tùy chỉnh containerđể HTML của cửa sổ bật lên xuất hiện bên trong phần tử đó.

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
})

Thí dụ

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Bốn hướng

Có bốn tùy chọn: căn trên, phải, dưới và căn trái. Chỉ đường được phản chiếu khi sử dụng Bootstrap trong RTL.

<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>

Bỏ qua trong lần nhấp tiếp theo

Sử dụng trình focuskích hoạt để loại bỏ các cửa sổ bật lên trong lần nhấp tiếp theo của người dùng vào một phần tử khác với phần tử bật tắt.

Đánh dấu cụ thể cần thiết để loại bỏ khi nhấp chuột tiếp theo

Để có hành vi trên nhiều trình duyệt và đa nền tảng phù hợp, bạn phải sử dụng thẻ <a>, không phải<button> thẻ và bạn cũng phải bao gồm một tabindexthuộc tính.

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})

Các phần tử bị vô hiệu hóa

Các phần tử có disabledthuộc tính không tương tác, có nghĩa là người dùng không thể di chuột hoặc nhấp vào chúng để kích hoạt cửa sổ bật lên (hoặc chú giải công cụ). Để giải quyết vấn đề này, bạn sẽ muốn kích hoạt cửa sổ bật lên từ trình bao bọc <div>hoặc <span>lý tưởng là có thể lấy tiêu điểm bằng bàn phím tabindex="0".

Đối với trình kích hoạt cửa sổ bật lên bị tắt, bạn cũng có thể muốn data-bs-trigger="hover focus"cửa sổ bật lên xuất hiện dưới dạng phản hồi trực quan ngay lập tức cho người dùng của bạn vì họ có thể không mong đợi nhấp vào phần tử bị vô hiệu hóa.

<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>

Sass

Biến

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$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;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

Cách sử dụng

Bật cửa sổ bật lên qua JavaScript:

var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)

Làm cho cửa sổ bật lên hoạt động đối với người dùng bàn phím và công nghệ hỗ trợ

Để cho phép người dùng bàn phím kích hoạt cửa sổ bật lên của bạn, bạn chỉ nên thêm chúng vào các phần tử HTML truyền thống có thể lấy tiêu điểm và tương tác với bàn phím (chẳng hạn như liên kết hoặc điều khiển biểu mẫu). Mặc dù các phần tử HTML tùy ý (chẳng hạn như <span>các) có thể được đặt tiêu điểm bằng cách thêm tabindex="0"thuộc tính, điều này sẽ thêm các điểm dừng tab có thể gây khó chịu và khó hiểu trên các phần tử không tương tác cho người dùng bàn phím và hầu hết các công nghệ hỗ trợ hiện không thông báo nội dung của cửa sổ bật lên trong tình huống này . Ngoài ra, đừng chỉ dựa vào hoverlàm trình kích hoạt cho các cửa sổ bật lên của bạn, vì điều này sẽ khiến chúng không thể kích hoạt cho người dùng bàn phím.

Mặc dù bạn có thể chèn HTML có cấu trúc, phong phú vào các cửa sổ bật lên với htmltùy chọn này, chúng tôi thực sự khuyên bạn nên tránh thêm quá nhiều nội dung. Cách hoạt động của cửa sổ bật lên hiện tại là, sau khi được hiển thị, nội dung của chúng được gắn với phần tử trình kích hoạt có aria-describedbythuộc tính. Do đó, toàn bộ nội dung của cửa sổ bật lên sẽ được thông báo cho người dùng công nghệ hỗ trợ dưới dạng một luồng dài, không bị gián đoạn.

Ngoài ra, mặc dù cũng có thể bao gồm các điều khiển tương tác (chẳng hạn như các phần tử biểu mẫu hoặc liên kết) trong cửa sổ bật lên của bạn (bằng cách thêm các phần tử này vào các allowListthuộc tính và thẻ được phép), hãy lưu ý rằng hiện tại cửa sổ bật lên không quản lý thứ tự tiêu điểm bàn phím. Khi người dùng bàn phím mở một cửa sổ bật lên, tiêu điểm vẫn ở phần tử kích hoạt và vì cửa sổ bật lên thường không ngay lập tức theo trình kích hoạt trong cấu trúc của tài liệu, không có gì đảm bảo rằng việc di chuyển tiếp / nhấnTABsẽ di chuyển người dùng bàn phím vào chính cửa sổ bật lên. Nói tóm lại, chỉ cần thêm các điều khiển tương tác vào cửa sổ bật lên có thể khiến các điều khiển này không thể truy cập / không sử dụng được đối với người dùng bàn phím và người dùng công nghệ hỗ trợ, hoặc ít nhất là tạo ra một trật tự tiêu điểm tổng thể phi logic. Trong những trường hợp này, hãy xem xét sử dụng hộp thoại phương thức để thay thế.

Tùy chọn

Các tùy chọn có thể được chuyển qua các thuộc tính dữ liệu hoặc JavaScript. Đối với các thuộc tính dữ liệu, hãy nối tên tùy chọn vào data-bs-, như trong data-bs-animation="". Đảm bảo thay đổi kiểu chữ hoa của tên tùy chọn từ camelCase thành kebab-case khi chuyển các tùy chọn qua thuộc tính dữ liệu. Ví dụ, thay vì sử dụng data-bs-customClass="beautifier", hãy sử dụng data-bs-custom-class="beautifier".

Lưu ý rằng vì lý do bảo mật sanitize, các tùy chọn sanitizeFnvà và allowListkhông thể được cung cấp bằng các thuộc tính dữ liệu.
Tên Loại hình Mặc định Sự mô tả
animation boolean true Áp dụng chuyển đổi mờ dần CSS cho cửa sổ bật lên
container chuỗi | phần tử | sai false

Thêm cửa sổ bật lên cho một phần tử cụ thể. container: 'body'Ví dụ :. Tùy chọn này đặc biệt hữu ích ở chỗ nó cho phép bạn định vị cửa sổ bật lên trong luồng tài liệu gần phần tử kích hoạt - điều này sẽ ngăn cửa sổ bật lên trôi ra khỏi phần tử kích hoạt trong quá trình thay đổi kích thước cửa sổ.

content chuỗi | phần tử | hàm số ''

Giá trị nội dung mặc định nếu data-bs-contentthuộc tính không có.

Nếu một hàm được cung cấp, nó sẽ được gọi với thistập tham chiếu của nó tới phần tử mà cửa sổ bật lên được gắn vào.

delay số | sự vật 0

Độ trễ hiển thị và ẩn cửa sổ bật lên (mili giây) - không áp dụng cho loại kích hoạt thủ công

Nếu một số được cung cấp, độ trễ được áp dụng cho cả ẩn / hiện

Cấu trúc đối tượng là:delay: { "show": 500, "hide": 100 }

html boolean false Chèn HTML vào cửa sổ bật lên. Nếu sai, innerTextthuộc tính sẽ được sử dụng để chèn nội dung vào DOM. Sử dụng văn bản nếu bạn lo lắng về các cuộc tấn công XSS.
placement chuỗi | hàm số 'right'

Cách định vị cửa sổ bật lên - tự động | đầu trang | dưới cùng | trái | bên phải.
Khi autođược chỉ định, nó sẽ tự động định hướng lại cửa sổ bật lên.

Khi một hàm được sử dụng để xác định vị trí, nó được gọi với nút DOM popover làm đối số đầu tiên và nút DOM phần tử kích hoạt là nút thứ hai của nó. Bối thiscảnh được đặt thành phiên bản popover.

selector chuỗi | sai false Nếu một bộ chọn được cung cấp, các đối tượng bật lên sẽ được ủy quyền cho các mục tiêu được chỉ định. Trên thực tế, điều này được sử dụng để cho phép nội dung HTML động có thêm cửa sổ bật lên. Xem điều nàymột ví dụ thông tin .
template sợi dây '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

Base HTML to use when creating the popover.

The popover's title will be injected into the .popover-header.

The popover's content will be injected into the .popover-body.

.popover-arrow will become the popover's arrow.

The outermost wrapper element should have the .popover class.

title string | element | function ''

Default title value if title attribute isn't present.

If a function is given, it will be called with its this reference set to the element that the popover is attached to.

trigger string 'click' How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. manual cannot be combined with any other trigger.
fallbackPlacements array ['top', 'right', 'bottom', 'left'] Define fallback placements by providing a list of placements in array (in order of preference). For more information refer to Popper's behavior docs
boundary string | element 'clippingParents' Overflow constraint boundary of the popover (applies only to Popper's preventOverflow modifier). By default it's 'clippingParents' and can accept an HTMLElement reference (via JavaScript only). For more information refer to Popper's detectOverflow docs.
customClass string | function ''

Add classes to the popover when it is shown. Note that these classes will be added in addition to any classes specified in the template. To add multiple classes, separate them with spaces: 'class-1 class-2'.

You can also pass a function that should return a single string containing additional class names.

sanitize boolean true Enable or disable the sanitization. If activated 'template', 'content' and 'title' options will be sanitized. See the sanitizer section in our JavaScript documentation.
allowList object Default value Object which contains allowed attributes and tags
sanitizeFn null | function null Here you can supply your own sanitize function. This can be useful if you prefer to use a dedicated library to perform sanitization.
offset array | string | function [0, 8]

Offset of the popover relative to its target. You can pass a string in data attributes with comma separated values like: data-bs-offset="10,20"

When a function is used to determine the offset, it is called with an object containing the popper placement, the reference, and popper rects as its first argument. The triggering element DOM node is passed as the second argument. The function must return an array with two numbers: [skidding, distance].

For more information refer to Popper's offset docs.

popperConfig null | object | function null

To change Bootstrap's default Popper config, see Popper's configuration.

When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. It helps you use and merge the default with your own configuration. The function must return a configuration object for Popper.

Data attributes for individual popovers

Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.

Using function with popperConfig

var popover = new bootstrap.Popover(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Methods

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

See our JavaScript documentation for more information.

show

Reveals an element’s popover. Returns to the caller before the popover has actually been shown (i.e. before the shown.bs.popover event occurs). This is considered a “manual” triggering of the popover. Popovers whose title and content are both zero-length are never displayed.

myPopover.show()

hide

Hides an element’s popover. Returns to the caller before the popover has actually been hidden (i.e. before the hidden.bs.popover event occurs). This is considered a “manual” triggering of the popover.

myPopover.hide()

toggle

Toggles an element’s popover. Returns to the caller before the popover has actually been shown or hidden (i.e. before the shown.bs.popover or hidden.bs.popover event occurs). This is considered a “manual” triggering of the popover.

myPopover.toggle()

dispose

Hides and destroys an element’s popover (Removes stored data on the DOM element). Popovers that use delegation (which are created using the selector option) cannot be individually destroyed on descendant trigger elements.

myPopover.dispose()

enable

Gives an element’s popover the ability to be shown. Popovers are enabled by default.

myPopover.enable()

disable

Removes the ability for an element’s popover to be shown. The popover will only be able to be shown if it is re-enabled.

myPopover.disable()

toggleEnabled

Toggles the ability for an element’s popover to be shown or hidden.

myPopover.toggleEnabled()

update

Updates the position of an element’s popover.

myPopover.update()

getInstance

Static method which allows you to get the popover instance associated with a DOM element

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

getOrCreateInstance

Static method which allows you to get the popover instance associated with a DOM element, or create a new one in case it wasn’t initialised

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

Events

Event type Description
show.bs.popover This event fires immediately when the show instance method is called.
shown.bs.popover This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.popover This event is fired immediately when the hide instance method has been called.
hidden.bs.popover This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).
inserted.bs.popover This event is fired after the show.bs.popover event when the popover template has been added to the DOM.
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})