in English

Suggerimenti

Documentazione ed esempi per l'aggiunta di suggerimenti Bootstrap personalizzati con CSS e JavaScript utilizzando CSS3 per animazioni e attributi di dati per l'archiviazione del titolo locale.

Panoramica

Cose da sapere quando si utilizza il plug-in tooltip:

  • Le descrizioni comandi si basano sulla libreria di terze parti Popper per il posizionamento. Devi includere popper.min.js prima di bootstrap.js o utilizzare bootstrap.bundle.min.js/ bootstrap.bundle.jsche contiene Popper affinché i suggerimenti funzionino!
  • Se stai creando il nostro JavaScript dal sorgente, richiedeutil.js .
  • Le descrizioni comandi sono attivabili per motivi di prestazioni, quindi devi inizializzarle tu stesso .
  • Le descrizioni comandi con titoli di lunghezza zero non vengono mai visualizzate.
  • Specificare container: 'body'per evitare problemi di rendering in componenti più complessi (come i nostri gruppi di input, gruppi di pulsanti, ecc.).
  • L'attivazione dei suggerimenti sugli elementi nascosti non funzionerà.
  • I suggerimenti per gli elementi .disabledo disableddevono essere attivati ​​su un elemento wrapper.
  • Quando vengono attivati ​​da collegamenti ipertestuali che si estendono su più righe, i suggerimenti vengono centrati. Usa white-space: nowrap;sui tuoi <a>messaggi di posta elettronica per evitare questo comportamento.
  • I suggerimenti devono essere nascosti prima che gli elementi corrispondenti siano stati rimossi dal DOM.
  • I tooltip possono essere attivati ​​grazie a un elemento all'interno di un DOM ombra.
Per impostazione predefinita, questo componente utilizza il disinfettante di contenuto integrato, che elimina tutti gli elementi HTML non esplicitamente consentiti. Vedere la sezione disinfettante nella nostra documentazione JavaScript per maggiori dettagli.
L'effetto di animazione di questo componente dipende dalla prefers-reduced-motionmedia query. Vedi la sezione movimento ridotto della nostra documentazione sull'accessibilità .

Hai tutto questo? Ottimo, vediamo come funzionano con alcuni esempi.

Esempio: abilita i suggerimenti ovunque

Un modo per inizializzare tutti i suggerimenti su una pagina sarebbe selezionarli in base al loro data-toggleattributo:

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

Esempi

Passa il mouse sui link sottostanti per vedere i suggerimenti:

Testo segnaposto per mostrare alcuni collegamenti in linea con suggerimenti. Questo ora è solo riempitivo, nessun killer. Contenuto inserito qui solo per simulare la presenza di testo reale . E tutto questo solo per darti un'idea di come apparirebbero i suggerimenti quando usati in situazioni del mondo reale. Quindi si spera che ora tu abbia visto come questi suggerimenti sui collegamenti possono funzionare nella pratica, una volta che li usi sul tuo sito o progetto.

Passa il mouse sopra i pulsanti sottostanti per vedere le quattro direzioni dei suggerimenti: in alto, a destra, in basso e a sinistra.

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

E con l'aggiunta di HTML personalizzato:

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

Utilizzo

Il plug-in tooltip genera contenuto e markup su richiesta e, per impostazione predefinita, posiziona i suggerimenti dopo il loro elemento di attivazione.

Attiva il suggerimento tramite JavaScript:

$('#example').tooltip(options)
Troppo pieno autoescroll

La posizione della descrizione comando tenta di cambiare automaticamente quando un contenitore padre ha overflow: autoo overflow: scrollcome il nostro .table-responsive, ma mantiene comunque il posizionamento del posizionamento originale. Per risolvere, imposta l' boundaryopzione su un valore diverso dal valore predefinito 'scrollParent', ad esempio 'window':

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

Marcatura

Il markup richiesto per un suggerimento è solo un dataattributo e titlesull'elemento HTML desideri avere un suggerimento. Il markup generato di un tooltip è piuttosto semplice, sebbene richieda una posizione (per impostazione predefinita, impostata topdal plug-in).

Fare in modo che le descrizioni comandi funzionino per gli utenti di tastiere e tecnologie assistive

Dovresti aggiungere suggerimenti solo agli elementi HTML che sono tradizionalmente attivabili da tastiera e interattivi (come collegamenti o controlli modulo). Sebbene elementi HTML arbitrari (come <span>s) possano essere resi attivabili aggiungendo l' tabindex="0"attributo, ciò aggiungerà tabulazioni potenzialmente fastidiose e confuse su elementi non interattivi per gli utenti della tastiera e la maggior parte delle tecnologie assistive attualmente non annuncia il suggerimento in questa situazione. Inoltre, non fare affidamento solo su hovercome trigger per la tua descrizione comando, poiché ciò renderà impossibile attivare le tue descrizioni comando per gli utenti della tastiera.

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

Elementi disabilitati

Gli elementi con l' disabledattributo non sono interattivi, il che significa che gli utenti non possono concentrarsi, passare il mouse o fare clic su di essi per attivare una descrizione comando (o popover). Come soluzione alternativa, ti consigliamo di attivare la descrizione comando da un wrapper <div>o <span>, idealmente reso attivabile dalla tastiera utilizzando tabindex="0", e sovrascrivere l' pointer-eventselemento disabilitato.

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

Opzioni

Le opzioni possono essere passate tramite attributi di dati o JavaScript. Per gli attributi dei dati, aggiungere il nome dell'opzione a data-, come in data-animation="".

Si noti che per motivi di sicurezza le opzioni sanitize, sanitizeFne whiteListnon possono essere fornite utilizzando gli attributi dei dati.
Nome Tipo Predefinito Descrizione
animazione booleano VERO Applica una transizione di dissolvenza CSS alla descrizione comando
contenitore stringa | elemento | falso falso

Aggiunge la descrizione comando a un elemento specifico. Esempio: container: 'body'. Questa opzione è particolarmente utile in quanto consente di posizionare la descrizione comando nel flusso del documento vicino all'elemento di attivazione, impedendo che la descrizione comando si allontani dall'elemento di attivazione durante il ridimensionamento della finestra.
ritardo numero | oggetto 0

Ritardo che mostra e nasconde la descrizione comando (ms) - non si applica al tipo di trigger manuale

Se viene fornito un numero, il ritardo viene applicato a entrambi nascondi/mostra

La struttura dell'oggetto è:delay: { "show": 500, "hide": 100 }
html booleano falso

Consenti HTML nella descrizione comando.

Se true, i tag HTML nella descrizione comando titleverranno visualizzati nella descrizione comando. Se false, il textmetodo di jQuery verrà utilizzato per inserire contenuto nel DOM.

Usa il testo se sei preoccupato per gli attacchi XSS.
posizionamento stringa | funzione 'superiore'

Come posizionare la descrizione comando - auto | in alto | in basso | sinistra | Giusto.
Quando autoè specificato, riorienterà dinamicamente la descrizione comando.

Quando una funzione viene utilizzata per determinare il posizionamento, viene chiamata con il nodo DOM della descrizione comando come primo argomento e il nodo DOM dell'elemento di attivazione come secondo. Il thiscontesto è impostato sull'istanza della descrizione comando.
selettore stringa | falso falso Se viene fornito un selettore, gli oggetti tooltip verranno delegati alle destinazioni specificate. In pratica, questo viene utilizzato anche per applicare i suggerimenti agli elementi DOM aggiunti dinamicamente ( jQuery.onsupporto). Vedi questo e un esempio informativo .
modello corda '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML di base da utilizzare durante la creazione del suggerimento.

I suggerimenti titleverranno inseriti nel file .tooltip-inner.

.arrowdiventerà la freccia del suggerimento.

L'elemento wrapper più esterno dovrebbe avere la .tooltipclasse e role="tooltip".
titolo stringa | elemento | funzione ''

Valore del titolo predefinito se titlel'attributo non è presente.

Se viene fornita una funzione, verrà chiamata con il suo thisset di riferimento all'elemento a cui è allegata la descrizione comando.
grilletto corda "messa a fuoco al passaggio del mouse"

Come viene attivata la descrizione comando: fare clic su | passa il mouse | messa a fuoco | Manuale. Puoi passare più trigger; separali con uno spazio.

'manual'indica che la descrizione comando verrà attivata a livello di codice tramite i metodi .tooltip('show'), .tooltip('hide')e ; .tooltip('toggle')questo valore non può essere combinato con nessun altro trigger.

'hover'di per sé si tradurrà in suggerimenti che non possono essere attivati ​​tramite la tastiera e dovrebbero essere utilizzati solo se sono presenti metodi alternativi per trasmettere le stesse informazioni agli utenti della tastiera.
compensare numero | stringa | funzione 0

Offset della descrizione comando rispetto alla sua destinazione.

Quando una funzione viene utilizzata per determinare l'offset, viene chiamata con un oggetto contenente i dati dell'offset come primo argomento. La funzione deve restituire un oggetto con la stessa struttura. Il nodo DOM dell'elemento di attivazione viene passato come secondo argomento.

Per ulteriori informazioni, fare riferimento ai documenti di offset di Popper .
posizionamento di fallback stringa | Vettore 'Flip' Consenti di specificare quale posizione utilizzerà Popper in fallback. Per ulteriori informazioni, fare riferimento ai documenti sul comportamento di Popper
customClass stringa | funzione ''

Aggiungi classi alla descrizione comando quando viene visualizzata. Tieni presente che queste classi verranno aggiunte in aggiunta a tutte le classi specificate nel modello. Per aggiungere più classi, separale con spazi: 'a b'.

Puoi anche passare una funzione che dovrebbe restituire una singola stringa contenente nomi di classi aggiuntivi.
confine stringa | elemento 'scorri Genitore' Limite del vincolo di overflow della descrizione comando. Accetta i valori di 'viewport', 'window', 'scrollParent'o un riferimento HTMLElement (solo JavaScript). Per ulteriori informazioni, fare riferimento ai documenti preventOverflow di Popper .
sanificare booleano VERO Abilita o disabilita la sanificazione. Se attivato 'template'e 'title'le opzioni verranno sanificate. Vedi la sezione disinfettante nella nostra documentazione JavaScript .
lista bianca oggetto Valore di default Oggetto che contiene attributi e tag consentiti
igienizzaFn nullo | funzione nullo Qui puoi fornire la tua funzione di sanificazione. Questo può essere utile se si preferisce utilizzare una libreria dedicata per eseguire la sanificazione.
popperConfig nullo | oggetto nullo Per modificare la configurazione di Popper predefinita di Bootstrap, vedere la configurazione di Popper

Attributi dei dati per i singoli suggerimenti

Le opzioni per i singoli suggerimenti possono essere specificati in alternativa tramite l'uso degli attributi dei dati, come spiegato sopra.

Metodi

Metodi e transizioni asincrone

Tutti i metodi API sono asincroni e avviano una transizione . Ritornano al chiamante non appena la transizione è iniziata ma prima che termini . Inoltre, una chiamata al metodo su un componente in transizione verrà ignorata .

Consulta la nostra documentazione JavaScript per ulteriori informazioni .

$().tooltip(options)

Allega un gestore di descrizione comando a una raccolta di elementi.

.tooltip('show')

Rivela il suggerimento di un elemento. Ritorna al chiamante prima che il suggerimento sia stato effettivamente mostrato (cioè prima shown.bs.tooltipche si verifichi l'evento). Questo è considerato un'attivazione "manuale" del suggerimento. Le descrizioni comandi con titoli di lunghezza zero non vengono mai visualizzate.

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

.tooltip('hide')

Nasconde la descrizione comando di un elemento. Ritorna al chiamante prima che il suggerimento sia stato effettivamente nascosto (cioè prima hidden.bs.tooltipche si verifichi l'evento). Questo è considerato un'attivazione "manuale" del suggerimento.

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

.tooltip('toggle')

Attiva o disattiva la descrizione comando di un elemento. Ritorna al chiamante prima che il suggerimento sia stato effettivamente mostrato o nascosto (cioè prima che si verifichi l' evento shown.bs.tooltipo hidden.bs.tooltip). Questo è considerato un'attivazione "manuale" del suggerimento.

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

.tooltip('dispose')

Nasconde e distrugge il suggerimento di un elemento. Le descrizioni comandi che utilizzano la delega (che vengono create utilizzando l' selectoropzione ) non possono essere distrutte individualmente sugli elementi trigger discendenti.

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

.tooltip('enable')

Dà alla descrizione comando di un elemento la possibilità di essere mostrata. Le descrizioni comandi sono abilitate per impostazione predefinita.

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

.tooltip('disable')

Rimuove la possibilità di mostrare la descrizione comando di un elemento. La descrizione comando potrà essere visualizzata solo se riattivata.

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

.tooltip('toggleEnabled')

Attiva o disattiva la possibilità di mostrare o nascondere la descrizione comando di un elemento.

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

.tooltip('update')

Aggiorna la posizione della descrizione comando di un elemento.

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

Eventi

Tipo di evento Descrizione
mostra.bs.descrizione comando Questo evento viene attivato immediatamente quando showviene chiamato il metodo dell'istanza.
descrizione comando.bs. mostrata Questo evento viene attivato quando la descrizione comando è stata resa visibile all'utente (attenderà il completamento delle transizioni CSS).
descrizione comando nascondi.bs Questo evento viene generato immediatamente quando hideviene chiamato il metodo dell'istanza.
descrizione comando.bs.nascosta Questo evento viene attivato quando la descrizione comando ha finito di essere nascosta all'utente (attenderà il completamento delle transizioni CSS).
descrizione comando.bs.inserita Questo evento viene attivato dopo l' show.bs.tooltipevento quando il modello di descrizione comando è stato aggiunto al DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})