in English

Popovery

Dokumentacja i przykłady dodawania popoverów Bootstrap, takich jak te znalezione w iOS, do dowolnego elementu w witrynie.

Przegląd

Co należy wiedzieć podczas korzystania z wtyczki popover:

  • Popovery polegają na zewnętrznej bibliotece Popper do pozycjonowania. Musisz dołączyć popper.min.js przed bootstrap.js lub użyć bootstrap.bundle.min.js/ bootstrap.bundle.jsktóry zawiera Poppera, aby popovery działały!
  • Popovery wymagają wtyczki podpowiedzi jako zależności.
  • Jeśli budujesz nasz JavaScript ze źródeł, wymagautil.js to .
  • Popovery są włączane ze względu na wydajność, więc musisz je zainicjować samodzielnie .
  • Zerowa długość titlei contentwartości nigdy nie pokażą popovera.
  • Określ container: 'body', aby uniknąć problemów z renderowaniem w bardziej złożonych komponentach (takich jak nasze grupy wejściowe, grupy przycisków itp.).
  • Wyzwalanie okienek popover na ukrytych elementach nie będzie działać.
  • Wyskakujące okienka dla .disabledlub disabledelementy muszą być wyzwalane na elemencie opakowania.
  • Po uruchomieniu z kotwic, które zawijają się w wielu liniach, popovery będą wyśrodkowane między całkowitą szerokością kotwic. Użyj .text-nowrapna swoim <a>s, aby uniknąć tego zachowania.
  • Popovery muszą być ukryte, zanim odpowiadające im elementy zostaną usunięte z DOM.
  • Popovery mogą być wyzwalane dzięki elementowi wewnątrz cienia DOM.
Domyślnie ten składnik używa wbudowanego narzędzia do oczyszczania treści, które usuwa wszystkie elementy HTML, które nie są wyraźnie dozwolone. Zobacz sekcję odkażania w naszej dokumentacji JavaScript, aby uzyskać więcej informacji.
Efekt animacji tego komponentu zależy od prefers-reduced-motionzapytania o media. Zobacz zmniejszoną sekcję ruchu w naszej dokumentacji ułatwień dostępu .

Czytaj dalej, aby zobaczyć, jak działają popovery na kilku przykładach.

Przykład: Włącz popovery wszędzie

Jednym ze sposobów na zainicjowanie wszystkich okienek popover na stronie byłoby wybranie ich według ich data-toggleatrybutów:

$(function () {
  $('[data-toggle="popover"]').popover()
})

Przykład: Korzystanie z containeropcji

Jeśli masz jakieś style w elemencie nadrzędnym, które kolidują z popoverem, będziesz chciał określić niestandardowy container, aby zamiast tego pojawiał się kod HTML popovera w tym elemencie.

$(function () {
  $('.example-popover').popover({
    container: 'body'
  })
})

Przykład

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

Cztery kierunki

Dostępne są cztery opcje: wyrównanie do góry, do prawej, do dołu i do lewej.

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Left popover">
  Popover on left
</button>

Odrzuć przy następnym kliknięciu

Użyj focuswyzwalacza, aby odrzucić okienka popover przy następnym kliknięciu przez użytkownika innego elementu niż element przełączania.

Konkretne znaczniki wymagane do odrzucenia przy następnym kliknięciu

Aby zapewnić prawidłowe działanie w różnych przeglądarkach i na różnych platformach, należy użyć <a>tagu, a nie<button> tagu, a także dołączyć tabindexatrybut.

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

Elementy niepełnosprawne

Elementy z disabledatrybutem nie są interaktywne, co oznacza, że ​​użytkownicy nie mogą na nich najeżdżać ani klikać, aby wywołać okienko wyskakujące (lub podpowiedź). Jako obejście, będziesz chciał wyzwolić popover z opakowania <div>lub <span>nadpisać pointer-eventsna wyłączonym elemencie.

W przypadku wyłączonych wyzwalaczy okienek popover możesz również preferować data-trigger="hover"wyświetlanie okienka popover jako natychmiastowej wizualnej informacji zwrotnej dla użytkowników, ponieważ mogą oni nie oczekiwać kliknięcia wyłączonego elementu.

<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

Stosowanie

Włącz popovery przez JavaScript:

$('#example').popover(options)
Akceleracja GPU

Popovery czasami wydają się rozmyte na urządzeniach z systemem Windows 10 z powodu akceleracji GPU i zmodyfikowanego DPI systemu. Rozwiązaniem tego problemu w wersji v4 jest wyłączenie akceleracji GPU w razie potrzeby w popoverach.

Sugerowana poprawka:

Popper.Defaults.modifiers.computeStyle.gpuAcceleration = !(window.devicePixelRatio < 1.5 && /Win/.test(navigator.platform))

Sprawianie, że popovery działają dla użytkowników klawiatury i technologii wspomagających

Aby umożliwić użytkownikom klawiatury aktywowanie wyskakujących okienek, należy dodawać je tylko do elementów HTML, które tradycyjnie można uruchamiać za pomocą klawiatury i które są interaktywne (takich jak łącza lub kontrolki formularzy). Chociaż można skupić się na dowolnych elementach HTML (takich jak <span>s) przez dodanie tabindex="0"atrybutu, doda to potencjalnie denerwujące i mylące tabulatory na nieinteraktywnych elementach dla użytkowników klawiatury, a większość technologii wspomagających obecnie nie ogłasza zawartości popover w tej sytuacji . Ponadto nie należy polegać wyłącznie na hoverwyzwalaczu popoverów, ponieważ uniemożliwi to ich wyzwalanie użytkownikom klawiatury.

Chociaż możesz wstawiać sformatowany, ustrukturyzowany kod HTML w popoverach za pomocą tej htmlopcji, zdecydowanie zalecamy unikanie dodawania nadmiernej ilości treści. Sposób, w jaki obecnie działają popovery, polega na tym, że po wyświetleniu ich zawartość jest powiązana z elementem wyzwalającym z aria-describedbyatrybutem. W rezultacie cała zawartość popovera zostanie ogłoszona użytkownikom technologii wspomagających jako jeden długi, nieprzerwany strumień.

Dodatkowo, chociaż możliwe jest również uwzględnienie interaktywnych kontrolek (takich jak elementy formularza lub linki) w popoverze (poprzez dodanie tych elementów do whiteListlub dozwolonych atrybutów i tagów), należy pamiętać, że obecnie popover nie zarządza kolejnością fokusów klawiatury. Gdy użytkownik klawiatury otworzy okienko popover, fokus pozostaje na elemencie wyzwalającym, a ponieważ okienko popover zwykle nie następuje bezpośrednio za wyzwalaczem w strukturze dokumentu, nie ma gwarancji, że przejście do przodu/naciśnięcieTABprzeniesie użytkownika klawiatury do samego popovera. Krótko mówiąc, zwykłe dodanie interaktywnych kontrolek do popovera może sprawić, że te kontrolki będą nieosiągalne/nieużyteczne dla użytkowników klawiatury i użytkowników technologii wspomagających, lub przynajmniej spowoduje nielogiczną ogólną kolejność fokusów. W takich przypadkach rozważ użycie modalnego okna dialogowego.

Opcje

Opcje można przekazywać za pomocą atrybutów danych lub kodu JavaScript. W przypadku atrybutów danych dołącz nazwę opcji do data-, jak w data-animation="".

Należy zauważyć, że ze względów bezpieczeństwa sanitizeopcji sanitizeFni whiteListnie można podać przy użyciu atrybutów danych.
Nazwa Rodzaj Domyślna Opis
animacja logiczne PRAWDA Zastosuj zanikające przejście CSS do popover
pojemnik ciąg | element | fałszywy fałszywy

Dołącza popover do określonego elementu. Przykład: container: 'body'. Ta opcja jest szczególnie przydatna, ponieważ pozwala umieścić okienko popover w przepływie dokumentu w pobliżu elementu wyzwalającego — co zapobiegnie oddalaniu się okienka popover od elementu wyzwalającego podczas zmiany rozmiaru okna.

zawartość ciąg | element | funkcjonować ''

Domyślna wartość treści, jeśli data-contentatrybut nie jest obecny.

Jeśli podana zostanie funkcja, zostanie wywołana z thisreferencją ustawioną na element, do którego dołączony jest popover.

opóźnienie numer | obiekt 0

Opóźnienie pokazywania i ukrywania popovera (ms) - nie dotyczy wyzwalania ręcznego

Jeśli podano numer, opóźnienie jest stosowane zarówno do ukrywania, jak i pokazywania

Struktura obiektu to:delay: { "show": 500, "hide": 100 }

html logiczne fałszywy Wstaw kod HTML do popovera. Jeśli false, metoda jQuery textzostanie użyta do wstawienia treści do DOM. Użyj tekstu, jeśli martwisz się atakami XSS.
umieszczenie ciąg | funkcjonować 'prawo'

Jak ustawić popover - auto | góra | dół | lewo | prawo.
Gdy autojest określony, dynamicznie zmieni orientację popovera.

Gdy funkcja jest używana do określenia położenia, jest wywoływana z węzłem DOM popover jako pierwszym argumentem i węzłem DOM elementu wyzwalającego jako drugim. Kontekst thisjest ustawiony na instancję popover.

selektor ciąg | fałszywy fałszywy Jeśli podano selektor, obiekty popover zostaną delegowane do określonych celów. W praktyce służy to umożliwieniu dynamicznej zawartości HTML dodawania okienek popover. Zobacz to i przykład informacyjny .
szablon strunowy '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

Podstawowy kod HTML do użycia podczas tworzenia popovera.

Popover titlezostanie wstrzyknięty do .popover-header.

Popover contentzostanie wstrzyknięty do .popover-body.

.arrowstanie się strzałką popovera.

Najbardziej zewnętrzny element opakowania powinien mieć .popoverklasę.

tytuł ciąg | element | funkcjonować ''

Domyślna wartość tytułu, jeśli titleatrybut nie jest obecny.

Jeśli podana zostanie funkcja, zostanie wywołana z thisreferencją ustawioną na element, do którego dołączony jest popover.

cyngiel strunowy 'Kliknij' Jak uruchamia się popover - kliknij | najedź | skupić | podręcznik. Możesz przekazać wiele wyzwalaczy; oddziel je spacją. manualnie można łączyć z żadnym innym wyzwalaczem.
zrównoważyć numer | strunowy 0 Przesunięcie popovera względem jego celu. Więcej informacji można znaleźć w dokumentacji offsetowej Poppera .
powrótMiejsce docelowe ciąg | szyk 'trzepnięcie' Zezwalaj na określenie, której pozycji Popper użyje w przypadku powrotu. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dotyczącą zachowania Poppera
klasa niestandardowa ciąg | funkcjonować ''

Dodaj klasy do wyskakującego okienka, gdy jest ono wyświetlane. Pamiętaj, że te klasy zostaną dodane do wszystkich klas określonych w szablonie. Aby dodać wiele klas, oddziel je spacjami: 'a b'.

Możesz także przekazać funkcję, która powinna zwrócić pojedynczy ciąg zawierający dodatkowe nazwy klas.

granica ciąg | element 'przewiń Rodzic' Granica ograniczenia przepełnienia popovera. Akceptuje wartości 'viewport', 'window', 'scrollParent'lub odwołania HTMLElement (tylko JavaScript). Aby uzyskać więcej informacji, zapoznaj się z dokumentacją PreventOverflow Poppera .
odkazić logiczne PRAWDA Włącz lub wyłącz sanityzację. 'template'W przypadku aktywacji opcje 'content'zostaną 'title'oczyszczone. Zobacz sekcję odkażania w naszej dokumentacji JavaScript .
biała lista obiekt Domyślna wartość Obiekt zawierający dozwolone atrybuty i tagi
odkażaćFn zero | funkcjonować zero Tutaj możesz podać własną funkcję odkażania. Może to być przydatne, jeśli wolisz korzystać z dedykowanej biblioteki do przeprowadzania sanityzacji.
popperConfig zero | obiekt zero Aby zmienić domyślną konfigurację Poppera Bootstrapa, zobacz Konfiguracja Poppera

Atrybuty danych dla poszczególnych okienek popover

Opcje dla poszczególnych okienek popover można alternatywnie określić za pomocą atrybutów danych, jak wyjaśniono powyżej.

Metody

Metody asynchroniczne i przejścia

Wszystkie metody API są asynchroniczne i rozpoczynają przejście . Wracają do rozmówcy zaraz po rozpoczęciu przejścia, ale przed jego zakończeniem . Ponadto wywołanie metody na składniku przechodzącym zostanie zignorowane .

Zobacz naszą dokumentację JavaScript, aby uzyskać więcej informacji .

$().popover(options)

Inicjuje popovery dla kolekcji elementów.

.popover('show')

Ujawnia popover elementu. Wraca do dzwoniącego przed faktycznym wyświetleniem popovera (tj. przed shown.bs.popoverwystąpieniem zdarzenia). Jest to uważane za „ręczne” wyzwalanie popover. Popovery, których tytuł i treść mają zerową długość, nigdy nie są wyświetlane.

$('#element').popover('show')

.popover('hide')

Ukrywa popover elementu. Powraca do dzwoniącego, zanim popover został faktycznie ukryty (tj. przed hidden.bs.popoverwystąpieniem zdarzenia). Jest to uważane za „ręczne” wyzwalanie popover.

$('#element').popover('hide')

.popover('toggle')

Przełącza popover elementu. Powraca do dzwoniącego, zanim popover został faktycznie wyświetlony lub ukryty (tj. przed wystąpieniem zdarzenia shown.bs.popoverlub ). hidden.bs.popoverJest to uważane za „ręczne” wyzwalanie popover.

$('#element').popover('toggle')

.popover('dispose')

Ukrywa i niszczy popover elementu. Popovery korzystające z delegowania (utworzone za pomocą opcji selector) nie mogą być indywidualnie niszczone w potomnych elementach wyzwalających.

$('#element').popover('dispose')

.popover('enable')

Daje możliwość pokazania popoverowi elementu. Popovery są domyślnie włączone.

$('#element').popover('enable')

.popover('disable')

Usuwa możliwość wyświetlania popovera elementu. Popover będzie można wyświetlić tylko wtedy, gdy zostanie ponownie włączony.

$('#element').popover('disable')

.popover('toggleEnabled')

Przełącza możliwość pokazywania lub ukrywania popover elementu.

$('#element').popover('toggleEnabled')

.popover('update')

Aktualizuje pozycję popovera elementu.

$('#element').popover('update')

Wydarzenia

Typ wydarzenia Opis
pokaż.bs.popover To zdarzenie jest wyzwalane natychmiast po showwywołaniu metody wystąpienia.
pokazano.bs.popover To zdarzenie jest uruchamiane, gdy popover jest widoczny dla użytkownika (poczeka na zakończenie przejścia CSS).
ukryj.bs.popover To zdarzenie jest wywoływane natychmiast po hidewywołaniu metody wystąpienia.
ukryta.bs.popover To zdarzenie jest uruchamiane po zakończeniu ukrywania popovera przed użytkownikiem (poczeka na zakończenie przejścia CSS).
wstawiony.bs.popover To zdarzenie jest wywoływane po show.bs.popoverzdarzeniu, gdy szablon popover został dodany do DOM.
$('#myPopover').on('hidden.bs.popover', function () {
  // do something...
})