in English

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.jsktóry zawiera Poppera, aby podpowiedzi działały!
  • Jeśli budujesz nasz JavaScript ze źródeł, wymagautil.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 .disabledlub disabledmuszą 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.
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 .

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-toggleatrybutó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 autoiscroll

Pozycja etykietki próbuje automatycznie zmienić się, gdy kontener nadrzędny ma overflow: autolub jest overflow: scrollpodobny do naszego .table-responsive, ale nadal zachowuje oryginalne położenie miejsca docelowego. Aby rozwiązać ten problem, ustaw boundaryopcję na wartość inną niż domyślna 'scrollParent', na przykład 'window':

$('#example').tooltip({ boundary: 'window' })

Narzut

Wymagane znaczniki podpowiedzi to tylko dataatrybut i titleelement HTML, który chcesz mieć podpowiedź. Wygenerowany znacznik podpowiedzi jest dość prosty, chociaż wymaga pozycji (domyślnie ustawionej topprzez 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 hoverwyzwalaczu 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 disabledatrybutem 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-eventswyłą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="".

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 podpowiedzi
pojemnik ciąg | element | fałszywy fałszywy

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

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:delay: { "show": 500, "hide": 100 }

html logiczne fałszywy

Zezwalaj na HTML w podpowiedzi.

Jeśli prawda, znaczniki HTML w podpowiedzi titlebędą renderowane w podpowiedzi. 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ć 'Top'

Jak ustawić podpowiedź - auto | góra | dół | lewo | prawo.
Gdy autozostanie określony, dynamicznie zmieni orientację podpowiedzi.

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 thisjest ustawiony na instancję podpowiedzi.

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.onobsł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 titlezostanie wstrzyknięta do .tooltip-inner.

.arrowstanie się strzałką w podpowiedzi.

Najbardziej zewnętrzny element opakowania powinien mieć .tooltipklasę i role="tooltip".

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łączona jest podpowiedź.

cyngiel strunowy „skup się na najechaniu”

Jak uruchamia się podpowiedź - kliknij | najedź | skupić | podręcznik. Możesz przekazać wiele wyzwalaczy; oddziel je spacją.

'manual'wskazuje, że etykietka zostanie wywołana programowo za pomocą metod i .tooltip('show'); tej wartości nie można łączyć z żadnym innym wyzwalaczem..tooltip('hide').tooltip('toggle')

'hover'samo w sobie spowoduje wyświetlenie podpowiedzi, których nie można uruchomić za pomocą klawiatury i należy ich używać tylko wtedy, gdy istnieją alternatywne metody przekazywania tych samych informacji użytkownikom klawiatury.

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: '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' 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.tooltipwystą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.tooltipwystą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.tooltiplub ). hidden.bs.tooltipJest 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 showwywoł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 hidewywoł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.tooltipzdarzeniu, gdy szablon podpowiedzi został dodany do DOM.
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})