Podpowiedzi
Dokumentacja i przykłady dodawania niestandardowych podpowiedzi Bootstrap z CSS i JavaScript przy użyciu CSS3 do animacji i atrybutów danych do lokalnego przechowywania tytułów.
Przegląd
Co należy wiedzieć podczas korzystania z wtyczki podpowiedzi:
- Podpowiedzi do pozycjonowania opierają się na zewnętrznej bibliotece Popper . Musisz dołączyć popper.min.js przed bootstrap.js lub użyć
bootstrap.bundle.min.js
/bootstrap.bundle.js
który zawiera Poppera, aby podpowiedzi działały! - Jeśli budujesz nasz JavaScript ze źródeł, wymaga
util.js
to . - Etykietki narzędzi są dostępne ze względu na wydajność, więc musisz je zainicjować samodzielnie .
- Etykietki narzędzi z tytułami o zerowej długości nigdy nie są wyświetlane.
- 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 podpowiedzi na ukrytych elementach nie będzie działać.
- Etykietki narzędzi dla elementów
.disabled
lubdisabled
muszą być wyzwalane w elemencie opakowania. - Po uruchomieniu z hiperłączy, które obejmują wiele linii, podpowiedzi zostaną wyśrodkowane. Użyj
white-space: nowrap;
na swoim<a>
s, aby uniknąć tego zachowania. - Etykietki narzędzi muszą być ukryte, zanim odpowiadające im elementy zostaną usunięte z DOM.
- Podpowiedzi mogą być wyzwalane dzięki elementowi wewnątrz cienia DOM.
prefers-reduced-motion
zapytania o media. Zobacz
zmniejszoną sekcję ruchu w naszej dokumentacji ułatwień dostępu .
Masz to wszystko? Świetnie, zobaczmy, jak działają na kilku przykładach.
Przykład: Włącz podpowiedzi wszędzie
Jednym ze sposobów na zainicjowanie wszystkich podpowiedzi na stronie byłoby wybranie ich według ich data-toggle
atrybutów:
$(function () {
$('[data-toggle="tooltip"]').tooltip()
})
Przykłady
Najedź na poniższe linki, aby zobaczyć podpowiedzi:
Tekst zastępczy przedstawiający niektóre łącza w tekście z podpowiedziami. To jest teraz tylko wypełniacz, nie zabójca. Treść umieszczona tutaj tylko po to, by naśladować obecność prawdziwego tekstu . A wszystko po to, aby dać ci wyobrażenie o tym, jak będą wyglądać podpowiedzi używane w rzeczywistych sytuacjach. Miejmy więc nadzieję, że wiesz już, jak te podpowiedzi dotyczące linków mogą działać w praktyce, gdy użyjesz ich we własnej witrynie lub projekcie.
Najedź kursorem na poniższe przyciski, aby zobaczyć cztery wskazówki podpowiedzi: góra, prawo, dół i lewo.
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
Tooltip on left
</button>
A z dodanym niestandardowym kodem HTML:
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
Tooltip with HTML
</button>
Stosowanie
Wtyczka podpowiedzi generuje treść i znaczniki na żądanie i domyślnie umieszcza podpowiedzi po elemencie wyzwalającym.
Uruchom podpowiedź za pomocą JavaScript:
$('#example').tooltip(options)
Przepełnienie auto
iscroll
Pozycja etykietki próbuje automatycznie zmienić się, gdy kontener nadrzędny ma overflow: auto
lub jest overflow: scroll
podobny do naszego .table-responsive
, ale nadal zachowuje oryginalne położenie miejsca docelowego. Aby rozwiązać ten problem, ustaw boundary
opcję na wartość inną niż domyślna 'scrollParent'
, na przykład 'window'
:
$('#example').tooltip({ boundary: 'window' })
Narzut
Wymagane znaczniki podpowiedzi to tylko data
atrybut i title
element HTML, który chcesz mieć podpowiedź. Wygenerowany znacznik podpowiedzi jest dość prosty, chociaż wymaga pozycji (domyślnie ustawionej top
przez wtyczkę).
Tworzenie podpowiedzi dla użytkowników klawiatury i technologii wspomagających
Etykietki narzędzi należy dodawać tylko do elementów HTML, które tradycyjnie można skoncentrować na klawiaturze i które są interaktywne (takie jak łącza lub kontrolki formularzy). Chociaż można ustawić ostrość na dowolnych elementach HTML (takich jak <span>
s), dodając tabindex="0"
atrybut, 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 wyświetla podpowiedzi w tej sytuacji. Ponadto nie polegaj wyłącznie na hover
wyzwalaczu podpowiedzi, ponieważ uniemożliwi to wyzwalanie podpowiedzi dla użytkowników klawiatury.
<!-- HTML to write -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>
<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
<div class="arrow"></div>
<div class="tooltip-inner">
Some tooltip text!
</div>
</div>
Elementy niepełnosprawne
Elementy z disabled
atrybutem nie są interaktywne, co oznacza, że użytkownicy nie mogą się na nich skoncentrować, najechać kursorem ani kliknąć ich, aby wywołać podpowiedź (lub popover). Jako obejście, będziesz chciał wyzwolić podpowiedź z otoki <div>
lub <span>
, najlepiej, aby można było skoncentrować się na klawiaturze za pomocą tabindex="0"
, i przesłonić pointer-events
wyłączony element.
<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>
Opcje
Opcje można przekazywać za pomocą atrybutów danych lub JavaScript. W przypadku atrybutów danych dołącz nazwę opcji do data-
, jak w data-animation=""
.
sanitize
opcji
sanitizeFn
i
whiteList
nie można podać przy użyciu atrybutów danych.
Nazwa | Rodzaj | Domyślna | Opis |
---|---|---|---|
animacja | logiczne | PRAWDA | Zastosuj zanikające przejście CSS do podpowiedzi |
pojemnik | ciąg | element | fałszywy | fałszywy | Dołącza podpowiedź do określonego elementu. Przykład: |
opóźnienie | numer | obiekt | 0 | Opóźnienie pokazywania i ukrywania podpowiedzi (ms) – nie dotyczy wyzwalania ręcznego Jeśli podano numer, opóźnienie jest stosowane zarówno do ukrywania, jak i pokazywania Struktura obiektu to: |
html | logiczne | fałszywy | Zezwalaj na HTML w podpowiedzi. Jeśli prawda, znaczniki HTML w podpowiedzi Użyj tekstu, jeśli martwisz się atakami XSS. |
umieszczenie | ciąg | funkcjonować | 'Top' | Jak ustawić podpowiedź - auto | góra | dół | lewo | prawo. Gdy funkcja jest używana do określenia położenia, jest wywoływana z węzłem DOM podpowiedzi jako pierwszym argumentem i węzłem DOM elementu wyzwalającego jako drugim. Kontekst |
selektor | ciąg | fałszywy | fałszywy | Jeśli podano selektor, obiekty etykietek narzędzi zostaną delegowane do określonych celów. W praktyce służy to również do zastosowania podpowiedzi do dynamicznie dodawanych elementów DOM ( jQuery.on obsługa). Zobacz to i przykład informacyjny . |
szablon | strunowy | '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>' |
Podstawowy kod HTML do użycia podczas tworzenia podpowiedzi. Etykietka
Najbardziej zewnętrzny element opakowania powinien mieć |
tytuł | ciąg | element | funkcjonować | '' | Domyślna wartość tytułu, jeśli Jeśli podana zostanie funkcja, zostanie wywołana z |
cyngiel | strunowy | „skup się na najechaniu” | Jak uruchamia się podpowiedź - kliknij | najedź | skupić | podręcznik. Możesz przekazać wiele wyzwalaczy; oddziel je spacją.
|
zrównoważyć | numer | ciąg | funkcjonować | 0 | Przesunięcie podpowiedzi względem celu. Gdy funkcja jest używana do określenia przesunięcia, jest wywoływana z obiektem zawierającym dane przesunięcia jako pierwszym argumentem. Funkcja musi zwrócić obiekt o tej samej strukturze. Węzeł DOM elementu wyzwalającego jest przekazywany jako drugi argument. 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 podpowiedzi, gdy jest wyświetlana. Pamiętaj, że te klasy zostaną dodane do wszystkich klas określonych w szablonie. Aby dodać wiele klas, oddziel je spacjami: 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' | Obwiednia przepełnienia etykiety narzędzi. 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ę. Jeśli zostanie aktywowany 'template' , 'title' opcje zostaną 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 | null | 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 | null | obiekt | zero | Aby zmienić domyślną konfigurację Poppera Bootstrapa, zobacz Konfiguracja Poppera |
Atrybuty danych dla poszczególnych podpowiedzi
Opcje dla poszczególnych podpowiedzi 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 .
$().tooltip(options)
Dołącza obsługę podpowiedzi do kolekcji elementów.
.tooltip('show')
Odsłania opis elementu. Wraca do wywołującego przed wyświetleniem podpowiedzi (tj. przed shown.bs.tooltip
wystąpieniem zdarzenia). Jest to uważane za „ręczne” wyzwalanie podpowiedzi. Etykietki narzędzi z tytułami o zerowej długości nigdy nie są wyświetlane.
$('#element').tooltip('show')
.tooltip('hide')
Ukrywa podpowiedź elementu. Wraca do wywołującego, zanim podpowiedź została faktycznie ukryta (tj. przed hidden.bs.tooltip
wystąpieniem zdarzenia). Jest to uważane za „ręczne” wyzwalanie podpowiedzi.
$('#element').tooltip('hide')
.tooltip('toggle')
Przełącza podpowiedź elementu. Powraca do wywołującego, zanim podpowiedź została faktycznie pokazana lub ukryta (tj. przed wystąpieniem zdarzenia shown.bs.tooltip
lub ). hidden.bs.tooltip
Jest to uważane za „ręczne” wyzwalanie podpowiedzi.
$('#element').tooltip('toggle')
.tooltip('dispose')
Ukrywa i niszczy opis elementu. Etykietki narzędzi korzystające z delegowania (utworzone za pomocą opcji selector
) nie mogą być indywidualnie niszczone w podrzędnych elementach wyzwalających.
$('#element').tooltip('dispose')
.tooltip('enable')
Daje opisowi elementu możliwość pokazania. Etykietki narzędzi są domyślnie włączone.
$('#element').tooltip('enable')
.tooltip('disable')
Usuwa możliwość wyświetlania podpowiedzi elementu. Etykietka będzie widoczna tylko wtedy, gdy zostanie ponownie włączona.
$('#element').tooltip('disable')
.tooltip('toggleEnabled')
Przełącza możliwość pokazywania lub ukrywania podpowiedzi elementu.
$('#element').tooltip('toggleEnabled')
.tooltip('update')
Aktualizuje pozycję podpowiedzi elementu.
$('#element').tooltip('update')
Wydarzenia
Typ wydarzenia | Opis |
---|---|
pokaż.bs.podpowiedź | To zdarzenie jest wyzwalane natychmiast po show wywołaniu metody wystąpienia. |
pokazana.bs.podpowiedź | To zdarzenie jest wywoływane, gdy etykietka narzędzi jest widoczna dla użytkownika (poczeka na zakończenie przejścia CSS). |
ukryj.bs.podpowiedź | To zdarzenie jest wywoływane natychmiast po hide wywołaniu metody wystąpienia. |
ukryta.bs.podpowiedź | To zdarzenie jest wywoływane po zakończeniu ukrywania podpowiedzi przed użytkownikiem (poczeka na zakończenie przejścia CSS). |
wstawiono.bs.podpowiedź | To zdarzenie jest uruchamiane po show.bs.tooltip zdarzeniu, gdy szablon podpowiedzi został dodany do DOM. |
$('#myTooltip').on('hidden.bs.tooltip', function () {
// do something...
})