Συμβουλές εργαλείων
Τεκμηρίωση και παραδείγματα για την προσθήκη προσαρμοσμένων συμβουλών εργαλείων Bootstrap με CSS και JavaScript χρησιμοποιώντας CSS3 για κινούμενα σχέδια και χαρακτηριστικά data-bs για τοπική αποθήκευση τίτλων.
ΣΦΑΙΡΙΚΗ ΕΙΚΟΝΑ
Πράγματα που πρέπει να γνωρίζετε όταν χρησιμοποιείτε την προσθήκη συμβουλής εργαλείου:
- Οι συμβουλές εργαλείων βασίζονται στη βιβλιοθήκη Popper τρίτου μέρους για την τοποθέτηση. Πρέπει να συμπεριλάβετε το popper.min.js πριν από το bootstrap.js ή να χρησιμοποιήσετε το
bootstrap.bundle.min.js
/bootstrap.bundle.js
που περιέχει Popper για να λειτουργήσουν οι συμβουλές εργαλείων! - Οι συμβουλές εργαλείων είναι επιλέξιμες για λόγους απόδοσης, επομένως πρέπει να τις αρχικοποιήσετε μόνοι σας .
- Επεξηγήσεις εργαλείων με τίτλους μηδενικού μήκους δεν εμφανίζονται ποτέ.
- Καθορίστε
container: 'body'
για να αποφύγετε την απόδοση προβλημάτων σε πιο σύνθετα στοιχεία (όπως οι ομάδες εισόδου, οι ομάδες κουμπιών κ.λπ.). - Η ενεργοποίηση συμβουλών εργαλείων σε κρυφά στοιχεία δεν θα λειτουργήσει.
- Επεξηγήσεις εργαλείων για
.disabled
ήdisabled
στοιχεία πρέπει να ενεργοποιούνται σε ένα στοιχείο περιτυλίγματος. - Όταν ενεργοποιούνται από υπερσυνδέσμους που εκτείνονται σε πολλές γραμμές, οι συμβουλές εργαλείων θα είναι κεντραρισμένες. Χρησιμοποιήστε
white-space: nowrap;
το στο<a>
s σας για να αποφύγετε αυτήν τη συμπεριφορά. - Οι συμβουλές εργαλείων πρέπει να είναι κρυφές πριν αφαιρεθούν τα αντίστοιχα στοιχεία τους από το DOM.
- Οι συμβουλές εργαλείων μπορούν να ενεργοποιηθούν χάρη σε ένα στοιχείο μέσα σε ένα σκιερό DOM.
prefers-reduced-motion
ερώτημα πολυμέσων. Δείτε την ενότητα
μειωμένης κίνησης της τεκμηρίωσης προσβασιμότητας .
Τα έχεις όλα αυτά; Ωραία, ας δούμε πώς λειτουργούν με μερικά παραδείγματα.
Παράδειγμα: Ενεργοποιήστε τις συμβουλές εργαλείων παντού
Ένας τρόπος για να αρχικοποιήσετε όλες τις συμβουλές εργαλείων σε μια σελίδα θα ήταν να τις επιλέξετε με βάση το data-bs-toggle
χαρακτηριστικό τους:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
Παραδείγματα
Τοποθετήστε το δείκτη του ποντικιού στους παρακάτω συνδέσμους για να δείτε συμβουλές εργαλείων:
Κείμενο placeholder για την επίδειξη ορισμένων ενσωματωμένων συνδέσμων με συμβουλές εργαλείων. Αυτό είναι τώρα απλώς πλήρωση, όχι δολοφόνος. Περιεχόμενο που τοποθετείται εδώ για να μιμηθεί την παρουσία πραγματικού κειμένου . Και όλα αυτά για να σας δώσουμε μια ιδέα για το πώς θα φαίνονται οι συμβουλές εργαλείων όταν χρησιμοποιούνται σε πραγματικές καταστάσεις. Ελπίζουμε λοιπόν να έχετε δει τώρα πώς αυτές οι συμβουλές εργαλείων σε συνδέσμους μπορούν να λειτουργήσουν στην πράξη, αφού τις χρησιμοποιήσετε στον δικό σας ιστότοπο ή έργο.
Τοποθετήστε το δείκτη του ποντικιού πάνω από τα κουμπιά παρακάτω για να δείτε τις τέσσερις οδηγίες εργαλείων: επάνω, δεξιά, κάτω και αριστερά. Οι οδηγίες αντικατοπτρίζονται όταν χρησιμοποιείτε το Bootstrap στο RTL.
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip on right">
Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip on left">
Tooltip on left
</button>
Και με την προσθήκη προσαρμοσμένου HTML:
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
Tooltip with HTML
</button>
Με SVG:
Sass
Μεταβλητές
$tooltip-font-size: $font-size-sm;
$tooltip-max-width: 200px;
$tooltip-color: $white;
$tooltip-bg: $black;
$tooltip-border-radius: $border-radius;
$tooltip-opacity: .9;
$tooltip-padding-y: $spacer * .25;
$tooltip-padding-x: $spacer * .5;
$tooltip-margin: 0;
$tooltip-arrow-width: .8rem;
$tooltip-arrow-height: .4rem;
$tooltip-arrow-color: $tooltip-bg;
Χρήση
Η προσθήκη συμβουλής εργαλείου δημιουργεί περιεχόμενο και σήμανση κατά απαίτηση και από προεπιλογή τοποθετεί τις συμβουλές εργαλείου μετά το στοιχείο ενεργοποίησης τους.
Ενεργοποιήστε την επεξήγηση εργαλείου μέσω JavaScript:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Υπερχείλιση auto
καιscroll
Η θέση επεξήγησης εργαλείου επιχειρεί να αλλάξει αυτόματα όταν ένα γονικό κοντέινερ έχει overflow: auto
ή overflow: scroll
αρέσει το δικό μας .table-responsive
, αλλά εξακολουθεί να διατηρεί τη θέση της αρχικής τοποθέτησης. Για να επιλύσετε αυτό το πρόβλημα, ορίστε την boundary
επιλογή (για τον τροποποιητή αναστροφής που χρησιμοποιεί την popperConfig
επιλογή) σε οποιοδήποτε HTMLElement για να παρακάμψετε την προεπιλεγμένη τιμή, 'clippingParents'
όπως document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Σήμανση
Η απαιτούμενη σήμανση για μια επεξήγηση εργαλείου είναι μόνο ένα data
χαρακτηριστικό και title
στο στοιχείο HTML θέλετε να έχετε μια επεξήγηση εργαλείου. Η παραγόμενη σήμανση μιας συμβουλής εργαλείου είναι μάλλον απλή, αν και απαιτεί μια θέση (από προεπιλογή, ρυθμισμένη top
από το πρόσθετο).
Κάνοντας τις συμβουλές εργαλείων να λειτουργούν για χρήστες πληκτρολογίου και βοηθητικής τεχνολογίας
Θα πρέπει να προσθέτετε μόνο συμβουλές εργαλείων σε στοιχεία HTML που είναι παραδοσιακά εστιάσιμα στο πληκτρολόγιο και διαδραστικά (όπως συνδέσμους ή στοιχεία ελέγχου φορμών). Παρόλο που τα αυθαίρετα στοιχεία HTML (όπως το <span>
s) μπορούν να γίνουν εστιάσιμα προσθέτοντας το tabindex="0"
χαρακτηριστικό, αυτό θα προσθέσει δυνητικά ενοχλητικές και μπερδεμένες θέσεις καρτελών σε μη αλληλεπιδραστικά στοιχεία για χρήστες πληκτρολογίου και οι περισσότερες υποστηρικτικές τεχνολογίες δεν ανακοινώνουν προς το παρόν την επεξήγηση εργαλείου σε αυτήν την περίπτωση. Επιπλέον, μην βασίζεστε αποκλειστικά hover
ως το έναυσμα για την επεξήγηση εργαλείου σας, καθώς αυτό θα καταστήσει αδύνατο να ενεργοποιηθούν οι συμβουλές εργαλείων σας για χρήστες πληκτρολογίου.
<!-- HTML to write -->
<a href="#" data-bs-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="tooltip-arrow"></div>
<div class="tooltip-inner">
Some tooltip text!
</div>
</div>
Απενεργοποιημένα στοιχεία
Τα στοιχεία με το disabled
χαρακτηριστικό δεν είναι διαδραστικά, πράγμα που σημαίνει ότι οι χρήστες δεν μπορούν να εστιάσουν, να τοποθετήσουν τον δείκτη του ποντικιού ή να κάνουν κλικ σε αυτά για να ενεργοποιήσουν μια επεξήγηση εργαλείου (ή το popover). Ως λύση, θα θελήσετε να ενεργοποιήσετε την επεξήγηση εργαλείου από ένα περιτύλιγμα <div>
ή <span>
ιδανικά κατασκευασμένο με δυνατότητα εστίασης στο πληκτρολόγιο χρησιμοποιώντας tabindex="0"
.
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Disabled tooltip">
<button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>
Επιλογές
Οι επιλογές μπορούν να μεταβιβαστούν μέσω χαρακτηριστικών δεδομένων ή JavaScript. Για τα χαρακτηριστικά δεδομένων, προσθέστε το όνομα της επιλογής στο data-bs-
, όπως στο data-bs-animation=""
. Φροντίστε να αλλάξετε τον τύπο πεζών-κεφαλαίων του ονόματος της επιλογής από camelCase σε kebab-case όταν μεταβιβάζετε τις επιλογές μέσω των χαρακτηριστικών δεδομένων. Για παράδειγμα, αντί να χρησιμοποιήσετε data-bs-customClass="beautifier"
, χρησιμοποιήστε data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
, και
allowList
δεν μπορούν να παρασχεθούν χρησιμοποιώντας χαρακτηριστικά δεδομένων.
Ονομα | Τύπος | Προκαθορισμένο | Περιγραφή |
---|---|---|---|
animation |
boolean | true |
Εφαρμόστε μια μετάβαση εξαφάνισης CSS στην επεξήγηση εργαλείου |
container |
χορδή | στοιχείο | ψευδής | false |
Προσθέτει την επεξήγηση εργαλείου σε ένα συγκεκριμένο στοιχείο. Παράδειγμα: |
delay |
αριθμός | αντικείμενο | 0 |
Καθυστέρηση εμφάνισης και απόκρυψης της επεξήγησης εργαλείου (ms) - δεν ισχύει για τον τύπο χειροκίνητης σκανδάλης Εάν παρέχεται ένας αριθμός, εφαρμόζεται καθυστέρηση και για την απόκρυψη/εμφάνιση Η δομή του αντικειμένου είναι: |
html |
boolean | false |
Να επιτρέπεται η HTML στην επεξήγηση εργαλείου. Εάν είναι αληθές, οι ετικέτες HTML στην επεξήγηση εργαλείου Χρησιμοποιήστε κείμενο εάν ανησυχείτε για επιθέσεις XSS. |
placement |
χορδή | λειτουργία | 'top' |
Πώς να τοποθετήσετε την επεξήγηση εργαλείου - αυτόματη | κορυφή | κάτω | αριστερά | σωστά. Όταν μια συνάρτηση χρησιμοποιείται για τον προσδιορισμό της τοποθέτησης, καλείται με πρώτο όρισμα τον κόμβο DOM επεξήγησης εργαλείου και δεύτερο τον κόμβο DOM στοιχείο ενεργοποίησης. Το |
selector |
χορδή | ψευδής | false |
Εάν παρέχεται ένας επιλογέας, τα αντικείμενα συμβουλής εργαλείου θα εκχωρηθούν στους καθορισμένους στόχους. Στην πράξη, αυτό χρησιμοποιείται επίσης για την εφαρμογή συμβουλών εργαλείων σε δυναμικά προστιθέμενα στοιχεία DOM ( jQuery.on υποστήριξη). Δείτε αυτό και ένα ενημερωτικό παράδειγμα . |
template |
σειρά | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
Βάση HTML για χρήση κατά τη δημιουργία της επεξήγησης εργαλείου. Η συμβουλή εργαλείου
Το πιο εξωτερικό στοιχείο περιτυλίγματος θα πρέπει να έχει την |
title |
χορδή | στοιχείο | λειτουργία | '' |
Προεπιλεγμένη τιμή τίτλου εάν Εάν δοθεί μια συνάρτηση, θα κληθεί με το |
trigger |
σειρά | 'hover focus' |
Πώς ενεργοποιείται η συμβουλή εργαλείου - κάντε κλικ στο | αιωρούνται | εστίαση | εγχειρίδιο. Μπορείτε να περάσετε πολλαπλούς ερεθισμούς. χωρίστε τα με ένα κενό.
|
fallbackPlacements |
πίνακας | ['top', 'right', 'bottom', 'left'] |
Ορίστε εναλλακτικές τοποθετήσεις παρέχοντας μια λίστα τοποθετήσεων σε πίνακα (με σειρά προτίμησης). Για περισσότερες πληροφορίες, ανατρέξτε στα έγγραφα συμπεριφοράς του Popper |
boundary |
χορδή | στοιχείο | 'clippingParents' |
Όριο περιορισμού υπερχείλισης της επεξήγησης εργαλείου (ισχύει μόνο για τον τροποποιητή preventOverflow του Popper). Από προεπιλογή είναι 'clippingParents' και μπορεί να δεχτεί μια αναφορά HTMLElement (μόνο μέσω JavaScript). Για περισσότερες πληροφορίες, ανατρέξτε στα έγγραφα του Popper detectOverflow . |
customClass |
χορδή | λειτουργία | '' |
Προσθέστε κλάσεις στην επεξήγηση εργαλείου όταν εμφανίζεται. Λάβετε υπόψη ότι αυτές οι κλάσεις θα προστεθούν επιπλέον των κλάσεων που καθορίζονται στο πρότυπο. Για να προσθέσετε πολλές κλάσεις, διαχωρίστε τις με κενά: Μπορείτε επίσης να περάσετε μια συνάρτηση που θα πρέπει να επιστρέψει μια συμβολοσειρά που περιέχει επιπλέον ονόματα κλάσεων. |
sanitize |
boolean | true |
Ενεργοποιήστε ή απενεργοποιήστε την απολύμανση. Εάν ενεργοποιηθεί 'template' και 'title' οι επιλογές θα απολυμανθούν. Δείτε την ενότητα απολυμαντικού στην τεκμηρίωση JavaScript . |
allowList |
αντικείμενο | Προεπιλεγμένη τιμή | Αντικείμενο που περιέχει επιτρεπόμενα χαρακτηριστικά και ετικέτες |
sanitizeFn |
null | λειτουργία | null |
Εδώ μπορείτε να παρέχετε τη δική σας λειτουργία απολύμανσης. Αυτό μπορεί να είναι χρήσιμο εάν προτιμάτε να χρησιμοποιήσετε μια αποκλειστική βιβλιοθήκη για να πραγματοποιήσετε απολύμανση. |
offset |
συστοιχία | χορδή | λειτουργία | [0, 0] |
Μετατόπιση της επεξήγησης εργαλείου σε σχέση με τον στόχο της. Μπορείτε να περάσετε μια συμβολοσειρά σε χαρακτηριστικά δεδομένων με τιμές διαχωρισμένες με κόμμα, όπως: Όταν μια συνάρτηση χρησιμοποιείται για τον προσδιορισμό της μετατόπισης, καλείται με ένα αντικείμενο που περιέχει την τοποθέτηση popper, την αναφορά και το popper rects ως πρώτο όρισμα. Ο κόμβος DOM του στοιχείου ενεργοποίησης μεταβιβάζεται ως δεύτερο όρισμα. Η συνάρτηση πρέπει να επιστρέψει έναν πίνακα με δύο αριθμούς: . Για περισσότερες πληροφορίες, ανατρέξτε στα έγγραφα μετατόπισης του Popper . |
popperConfig |
null | αντικείμενο | λειτουργία | null |
Για να αλλάξετε την προεπιλεγμένη διαμόρφωση Popper του Bootstrap, ανατρέξτε στη διαμόρφωση του Popper . Όταν μια συνάρτηση χρησιμοποιείται για τη δημιουργία της διαμόρφωσης Popper, καλείται με ένα αντικείμενο που περιέχει την προεπιλεγμένη διαμόρφωση Popper του Bootstrap. Σας βοηθά να χρησιμοποιήσετε και να συγχωνεύσετε την προεπιλογή με τη δική σας διαμόρφωση. Η συνάρτηση πρέπει να επιστρέψει ένα αντικείμενο διαμόρφωσης για το Popper. |
Χαρακτηριστικά δεδομένων για μεμονωμένες συμβουλές εργαλείων
Επιλογές για μεμονωμένες συμβουλές εργαλείων μπορούν εναλλακτικά να καθοριστούν μέσω της χρήσης χαρακτηριστικών δεδομένων, όπως εξηγήθηκε παραπάνω.
Χρήση της λειτουργίας μεpopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
Μέθοδοι
Ασύγχρονες μέθοδοι και μεταβάσεις
Όλες οι μέθοδοι API είναι ασύγχρονες και ξεκινούν μια μετάβαση . Επιστρέφουν στον καλούντα μόλις ξεκινήσει η μετάβαση αλλά πριν τελειώσει . Επιπλέον, μια κλήση μεθόδου σε ένα στοιχείο μετάβασης θα αγνοηθεί .
Δείτε την τεκμηρίωση JavaScript για περισσότερες πληροφορίες .
προβολή
Αποκαλύπτει την επεξήγηση εργαλείου ενός στοιχείου. Επιστρέφει στον καλούντα πριν εμφανιστεί πραγματικά η συμβουλή εργαλείου (δηλαδή πριν συμβεί το shown.bs.tooltip
συμβάν). Αυτό θεωρείται ως «χειροκίνητη» ενεργοποίηση της συμβουλής εργαλείου. Επεξηγήσεις εργαλείων με τίτλους μηδενικού μήκους δεν εμφανίζονται ποτέ.
tooltip.show()
κρύβω
Κρύβει την επεξήγηση εργαλείου ενός στοιχείου. Επιστρέφει στον καλούντα προτού η επεξήγηση εργαλείου έχει πραγματικά κρυφτεί (δηλαδή πριν συμβεί το hidden.bs.tooltip
συμβάν). Αυτό θεωρείται ως «χειροκίνητη» ενεργοποίηση της συμβουλής εργαλείου.
tooltip.hide()
μεταβάλλω
Εναλλάσσει την επεξήγηση εργαλείου ενός στοιχείου. Επιστρέφει στον καλούντα πριν εμφανιστεί ή κρυφτεί πραγματικά η συμβουλή εργαλείου (δηλαδή πριν συμβεί το shown.bs.tooltip
ή το hidden.bs.tooltip
συμβάν). Αυτό θεωρείται ως «χειροκίνητη» ενεργοποίηση της συμβουλής εργαλείου.
tooltip.toggle()
διαθέτω
Αποκρύπτει και καταστρέφει την επεξήγηση εργαλείου ενός στοιχείου (Καταργεί τα αποθηκευμένα δεδομένα στο στοιχείο DOM). Οι επεξηγήσεις εργαλείων που χρησιμοποιούν ανάθεση (οι οποίες δημιουργούνται χρησιμοποιώντας την selector
επιλογή ) δεν μπορούν να καταστραφούν μεμονωμένα σε στοιχεία ενεργοποίησης καταγωγής.
tooltip.dispose()
επιτρέπω
Δίνει στην επεξήγηση εργαλείου ενός στοιχείου τη δυνατότητα να εμφανίζεται. Οι συμβουλές εργαλείων είναι ενεργοποιημένες από προεπιλογή.
tooltip.enable()
καθιστώ ανίκανο
Καταργεί τη δυνατότητα εμφάνισης της επεξήγησης εργαλείου ενός στοιχείου. Η συμβουλή εργαλείου θα μπορεί να εμφανιστεί μόνο εάν ενεργοποιηθεί ξανά.
tooltip.disable()
toggleEnabled
Εναλλάσσει τη δυνατότητα εμφάνισης ή απόκρυψης της επεξήγησης εργαλείου ενός στοιχείου.
tooltip.toggleEnabled()
εκσυγχρονίζω
Ενημερώνει τη θέση της επεξήγησης εργαλείου ενός στοιχείου.
tooltip.update()
getInstance
Στατική μέθοδος που σας επιτρέπει να λάβετε την παρουσία συμβουλής εργαλείου που σχετίζεται με ένα στοιχείο DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Στατική μέθοδος που σας επιτρέπει να λάβετε την παρουσία συμβουλής εργαλείου που σχετίζεται με ένα στοιχείο DOM ή να δημιουργήσετε μια νέα σε περίπτωση που δεν είχε αρχικοποιηθεί
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
Εκδηλώσεις
Τύπος συμβάντος | Περιγραφή |
---|---|
show.bs.tooltip |
Αυτό το συμβάν ενεργοποιείται αμέσως όταν show καλείται η μέθοδος παρουσίας. |
shown.bs.tooltip |
Αυτό το συμβάν ενεργοποιείται όταν η επεξήγηση εργαλείου έχει γίνει ορατή στον χρήστη (θα περιμένει να ολοκληρωθούν οι μεταβάσεις CSS). |
hide.bs.tooltip |
Αυτό το συμβάν ενεργοποιείται αμέσως μετά την hide κλήση της μεθόδου παρουσίας. |
hidden.bs.tooltip |
Αυτό το συμβάν ενεργοποιείται όταν ολοκληρωθεί η απόκρυψη της επεξήγησης εργαλείου από τον χρήστη (θα περιμένει να ολοκληρωθούν οι μεταβάσεις CSS). |
inserted.bs.tooltip |
Αυτό το συμβάν ενεργοποιείται μετά το show.bs.tooltip συμβάν όταν το πρότυπο συμβουλής εργαλείου έχει προστεθεί στο DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()