Συμβουλές εργαλείων
Τεκμηρίωση και παραδείγματα για την προσθήκη προσαρμοσμένων συμβουλών εργαλείων εκκίνησης με CSS και JavaScript χρησιμοποιώντας CSS3 για κινούμενα σχέδια και χαρακτηριστικά δεδομένων για τοπική αποθήκευση τίτλων.
ΣΦΑΙΡΙΚΗ ΕΙΚΟΝΑ
Πράγματα που πρέπει να γνωρίζετε όταν χρησιμοποιείτε την προσθήκη συμβουλής εργαλείου:
- Οι συμβουλές εργαλείων βασίζονται στη βιβλιοθήκη Popper τρίτου μέρους για την τοποθέτηση. Πρέπει να συμπεριλάβετε το popper.min.js πριν από το bootstrap.js ή να χρησιμοποιήσετε το
bootstrap.bundle.min.js
/bootstrap.bundle.js
που περιέχει Popper για να λειτουργήσουν οι συμβουλές εργαλείων! - Εάν δημιουργείτε το JavaScript μας από την πηγή, απαιτεί
util.js
. - Οι συμβουλές εργαλείων είναι επιλέξιμες για λόγους απόδοσης, επομένως πρέπει να τις αρχικοποιήσετε μόνοι σας .
- Επεξηγήσεις εργαλείων με τίτλους μηδενικού μήκους δεν εμφανίζονται ποτέ.
- Καθορίστε
container: 'body'
για να αποφύγετε την απόδοση προβλημάτων σε πιο σύνθετα στοιχεία (όπως οι ομάδες εισόδου, οι ομάδες κουμπιών κ.λπ.). - Η ενεργοποίηση συμβουλών εργαλείων σε κρυφά στοιχεία δεν θα λειτουργήσει.
- Επεξηγήσεις εργαλείων για
.disabled
ήdisabled
στοιχεία πρέπει να ενεργοποιούνται σε ένα στοιχείο περιτυλίγματος. - Όταν ενεργοποιούνται από υπερσυνδέσμους που εκτείνονται σε πολλές γραμμές, οι συμβουλές εργαλείων θα είναι κεντραρισμένες. Χρησιμοποιήστε
white-space: nowrap;
το στο<a>
s σας για να αποφύγετε αυτήν τη συμπεριφορά. - Οι συμβουλές εργαλείων πρέπει να είναι κρυφές πριν αφαιρεθούν τα αντίστοιχα στοιχεία τους από το DOM.
- Οι συμβουλές εργαλείων μπορούν να ενεργοποιηθούν χάρη σε ένα στοιχείο μέσα σε ένα σκιερό DOM.
prefers-reduced-motion
ερώτημα πολυμέσων. Δείτε την ενότητα
μειωμένης κίνησης της τεκμηρίωσης προσβασιμότητας .
Τα έχεις όλα αυτά; Ωραία, ας δούμε πώς λειτουργούν με μερικά παραδείγματα.
Παράδειγμα: Ενεργοποιήστε τις συμβουλές εργαλείων παντού
Ένας τρόπος για να αρχικοποιήσετε όλες τις συμβουλές εργαλείων σε μια σελίδα θα ήταν να τις επιλέξετε με βάση το data-toggle
χαρακτηριστικό τους:
$(function () {
$('[data-toggle="tooltip"]').tooltip()
})
Παραδείγματα
Τοποθετήστε το δείκτη του ποντικιού στους παρακάτω συνδέσμους για να δείτε συμβουλές εργαλείων:
Κείμενο placeholder για την επίδειξη ορισμένων ενσωματωμένων συνδέσμων με συμβουλές εργαλείων. Αυτό είναι τώρα απλώς πλήρωση, όχι δολοφόνος. Περιεχόμενο που τοποθετείται εδώ για να μιμηθεί την παρουσία πραγματικού κειμένου . Και όλα αυτά για να σας δώσουμε μια ιδέα για το πώς θα φαίνονται οι συμβουλές εργαλείων όταν χρησιμοποιούνται σε πραγματικές καταστάσεις. Ελπίζουμε λοιπόν να έχετε δει τώρα πώς αυτές οι συμβουλές εργαλείων σε συνδέσμους μπορούν να λειτουργήσουν στην πράξη, αφού τις χρησιμοποιήσετε στον δικό σας ιστότοπο ή έργο.
Τοποθετήστε το δείκτη του ποντικιού πάνω από τα κουμπιά παρακάτω για να δείτε τις τέσσερις οδηγίες εργαλείων: επάνω, δεξιά, κάτω και αριστερά.
<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>
Και με την προσθήκη προσαρμοσμένου 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>
Χρήση
Η προσθήκη συμβουλής εργαλείου δημιουργεί περιεχόμενο και σήμανση κατά απαίτηση και από προεπιλογή τοποθετεί τις συμβουλές εργαλείου μετά το στοιχείο ενεργοποίησης τους.
Ενεργοποιήστε την επεξήγηση εργαλείου μέσω JavaScript:
$('#example').tooltip(options)
Υπερχείλιση auto
καιscroll
Η θέση επεξήγησης εργαλείου επιχειρεί να αλλάξει αυτόματα όταν ένα γονικό κοντέινερ έχει overflow: auto
ή overflow: scroll
αρέσει το δικό μας .table-responsive
, αλλά εξακολουθεί να διατηρεί τη θέση της αρχικής τοποθέτησης. Για επίλυση, ορίστε την boundary
επιλογή σε οτιδήποτε άλλο εκτός από την προεπιλεγμένη τιμή, 'scrollParent'
όπως 'window'
:
$('#example').tooltip({ boundary: 'window' })
Σήμανση
Η απαιτούμενη σήμανση για μια επεξήγηση εργαλείου είναι μόνο ένα data
χαρακτηριστικό και title
στο στοιχείο HTML θέλετε να έχετε μια επεξήγηση εργαλείου. Η παραγόμενη σήμανση μιας συμβουλής εργαλείου είναι μάλλον απλή, αν και απαιτεί μια θέση (από προεπιλογή, ρυθμισμένη top
από το πρόσθετο).
Κάνοντας τις συμβουλές εργαλείων να λειτουργούν για χρήστες πληκτρολογίου και βοηθητικής τεχνολογίας
Θα πρέπει να προσθέτετε μόνο συμβουλές εργαλείων σε στοιχεία HTML που είναι παραδοσιακά εστιάσιμα στο πληκτρολόγιο και διαδραστικά (όπως συνδέσμους ή στοιχεία ελέγχου φορμών). Αν και τα αυθαίρετα στοιχεία HTML (όπως το <span>
s) μπορούν να γίνουν εστιάσιμα προσθέτοντας το tabindex="0"
χαρακτηριστικό, αυτό θα προσθέσει δυνητικά ενοχλητικές και μπερδεμένες θέσεις καρτελών σε μη διαδραστικά στοιχεία για χρήστες πληκτρολογίου και οι περισσότερες υποστηρικτικές τεχνολογίες προς το παρόν δεν ανακοινώνουν την επεξήγηση εργαλείου σε αυτήν την περίπτωση. Επιπλέον, μην βασίζεστε αποκλειστικά hover
ως το έναυσμα για την επεξήγηση εργαλείου σας, καθώς αυτό θα καταστήσει αδύνατο να ενεργοποιηθούν οι συμβουλές εργαλείων σας για χρήστες πληκτρολογίου.
<!-- 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>
Απενεργοποιημένα στοιχεία
Τα στοιχεία με το disabled
χαρακτηριστικό δεν είναι διαδραστικά, πράγμα που σημαίνει ότι οι χρήστες δεν μπορούν να εστιάσουν, να τοποθετήσουν τον δείκτη του ποντικιού ή να κάνουν κλικ σε αυτά για να ενεργοποιήσουν μια επεξήγηση εργαλείου (ή το popover). Ως λύση, θα θελήσετε να ενεργοποιήσετε την επεξήγηση εργαλείου από ένα περιτύλιγμα <div>
ή <span>
ιδανικά κατασκευασμένο με δυνατότητα εστίασης στο πληκτρολόγιο χρησιμοποιώντας tabindex="0"
και να παρακάμψετε το pointer-events
στοιχείο στο απενεργοποιημένο στοιχείο.
<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>
Επιλογές
Οι επιλογές μπορούν να μεταβιβαστούν μέσω χαρακτηριστικών δεδομένων ή JavaScript. Για τα χαρακτηριστικά δεδομένων, προσθέστε το όνομα της επιλογής στο data-
, όπως στο data-animation=""
.
sanitize
,
sanitizeFn
και
whiteList
δεν μπορούν να παρασχεθούν χρησιμοποιώντας χαρακτηριστικά δεδομένων.
Ονομα | Τύπος | Προκαθορισμένο | Περιγραφή |
---|---|---|---|
κινουμένων σχεδίων | boolean | αληθής | Εφαρμόστε μια μετάβαση εξαφάνισης CSS στην επεξήγηση εργαλείου |
δοχείο | χορδή | στοιχείο | ψευδής | ψευδής | Προσθέτει την επεξήγηση εργαλείου σε ένα συγκεκριμένο στοιχείο. Παράδειγμα: |
καθυστέρηση | αριθμός | αντικείμενο | 0 | Καθυστέρηση εμφάνισης και απόκρυψης της επεξήγησης εργαλείου (ms) - δεν ισχύει για τον τύπο χειροκίνητης σκανδάλης Εάν παρέχεται ένας αριθμός, εφαρμόζεται καθυστέρηση και για την απόκρυψη/εμφάνιση Η δομή του αντικειμένου είναι: |
html | boolean | ψευδής | Να επιτρέπεται η HTML στην επεξήγηση εργαλείου. Εάν είναι αληθές, οι ετικέτες HTML στην επεξήγηση εργαλείου Χρησιμοποιήστε κείμενο εάν ανησυχείτε για επιθέσεις XSS. |
τοποθέτηση | χορδή | λειτουργία | 'μπλουζα' | Πώς να τοποθετήσετε την επεξήγηση εργαλείου - αυτόματη | κορυφή | κάτω | αριστερά | σωστά. Όταν μια συνάρτηση χρησιμοποιείται για τον προσδιορισμό της τοποθέτησης, καλείται με πρώτο όρισμα τον κόμβο DOM επεξήγησης εργαλείου και δεύτερο τον κόμβο DOM στοιχείο ενεργοποίησης. Το |
εκλέκτορας | χορδή | ψευδής | ψευδής | Εάν παρέχεται ένας επιλογέας, τα αντικείμενα συμβουλής εργαλείου θα εκχωρηθούν στους καθορισμένους στόχους. Στην πράξη, αυτό χρησιμοποιείται επίσης για την εφαρμογή συμβουλών εργαλείων σε δυναμικά προστιθέμενα στοιχεία DOM ( jQuery.on υποστήριξη). Δείτε αυτό και ένα ενημερωτικό παράδειγμα . |
πρότυπο | σειρά | '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>' |
Βάση HTML για χρήση κατά τη δημιουργία της επεξήγησης εργαλείου. Η συμβουλή εργαλείου
Το πιο εξωτερικό στοιχείο περιτυλίγματος θα πρέπει να έχει την |
τίτλος | χορδή | στοιχείο | λειτουργία | '' | Προεπιλεγμένη τιμή τίτλου εάν Εάν δοθεί μια συνάρτηση, θα κληθεί με το |
δώσει το έναυσμα για | σειρά | "εστίαση αιώρησης" | Πώς ενεργοποιείται η συμβουλή εργαλείου - κάντε κλικ στο | αιωρούνται | εστίαση | εγχειρίδιο. Μπορείτε να περάσετε πολλαπλούς ερεθισμούς. χωρίστε τα με ένα κενό.
|
αντισταθμίζεται | αριθμός | χορδή | λειτουργία | 0 | Μετατόπιση της επεξήγησης εργαλείου σε σχέση με τον στόχο της. Όταν μια συνάρτηση χρησιμοποιείται για τον προσδιορισμό της μετατόπισης, καλείται με ένα αντικείμενο που περιέχει τα δεδομένα μετατόπισης ως πρώτο όρισμα. Η συνάρτηση πρέπει να επιστρέψει ένα αντικείμενο με την ίδια δομή. Ο κόμβος DOM του στοιχείου ενεργοποίησης μεταβιβάζεται ως δεύτερο όρισμα. Για περισσότερες πληροφορίες, ανατρέξτε στα έγγραφα μετατόπισης του Popper . |
εναλλακτική τοποθέτηση | χορδή | πίνακας | 'αναρρίπτω' | Επιτρέψτε να καθορίσετε ποια θέση θα χρησιμοποιήσει ο Popper στην εναλλακτική. Για περισσότερες πληροφορίες, ανατρέξτε στα έγγραφα συμπεριφοράς του Popper |
customClass | χορδή | λειτουργία | '' | Προσθέστε κλάσεις στην επεξήγηση εργαλείου όταν εμφανίζεται. Λάβετε υπόψη ότι αυτές οι κλάσεις θα προστεθούν επιπλέον των κλάσεων που καθορίζονται στο πρότυπο. Για να προσθέσετε πολλές κλάσεις, διαχωρίστε τις με κενά: Μπορείτε επίσης να περάσετε μια συνάρτηση που θα πρέπει να επιστρέψει μια συμβολοσειρά που περιέχει επιπλέον ονόματα κλάσεων. |
Όριο | χορδή | στοιχείο | 'scrollParent' | Όριο περιορισμού υπερχείλισης της επεξήγησης εργαλείου. Αποδέχεται τις τιμές του 'viewport' , 'window' , 'scrollParent' ή μιας αναφοράς HTMLElement (μόνο JavaScript). Για περισσότερες πληροφορίες, ανατρέξτε στα έγγραφα του Popper preventOverflow . |
απολυμάνετε | boolean | αληθής | Ενεργοποιήστε ή απενεργοποιήστε την απολύμανση. Εάν ενεργοποιηθεί 'template' και 'title' οι επιλογές θα απολυμανθούν. Δείτε την ενότητα απολυμαντικού στην τεκμηρίωση JavaScript . |
λευκή λίστα | αντικείμενο | Προεπιλεγμένη τιμή | Αντικείμενο που περιέχει επιτρεπόμενα χαρακτηριστικά και ετικέτες |
sanitizeFn | null | λειτουργία | μηδενικό | Εδώ μπορείτε να παρέχετε τη δική σας λειτουργία απολύμανσης. Αυτό μπορεί να είναι χρήσιμο εάν προτιμάτε να χρησιμοποιήσετε μια αποκλειστική βιβλιοθήκη για να πραγματοποιήσετε απολύμανση. |
popperConfig | null | αντικείμενο | μηδενικό | Για να αλλάξετε την προεπιλεγμένη διαμόρφωση Popper του Bootstrap, δείτε τη διαμόρφωση του Popper |
Χαρακτηριστικά δεδομένων για μεμονωμένες συμβουλές εργαλείων
Επιλογές για μεμονωμένες συμβουλές εργαλείων μπορούν εναλλακτικά να καθοριστούν μέσω της χρήσης χαρακτηριστικών δεδομένων, όπως εξηγήθηκε παραπάνω.
Μέθοδοι
Ασύγχρονες μέθοδοι και μεταβάσεις
Όλες οι μέθοδοι API είναι ασύγχρονες και ξεκινούν μια μετάβαση . Επιστρέφουν στον καλούντα μόλις ξεκινήσει η μετάβαση αλλά πριν τελειώσει . Επιπλέον, μια κλήση μεθόδου σε ένα στοιχείο μετάβασης θα αγνοηθεί .
Δείτε την τεκμηρίωση JavaScript για περισσότερες πληροφορίες .
$().tooltip(options)
Προσαρτά έναν χειριστή συμβουλών εργαλείου σε μια συλλογή στοιχείων.
.tooltip('show')
Αποκαλύπτει την επεξήγηση εργαλείου ενός στοιχείου. Επιστρέφει στον καλούντα πριν εμφανιστεί πραγματικά η συμβουλή εργαλείου (δηλαδή πριν συμβεί το shown.bs.tooltip
συμβάν). Αυτό θεωρείται ως «χειροκίνητη» ενεργοποίηση της συμβουλής εργαλείου. Επεξηγήσεις εργαλείων με τίτλους μηδενικού μήκους δεν εμφανίζονται ποτέ.
$('#element').tooltip('show')
.tooltip('hide')
Κρύβει την επεξήγηση εργαλείου ενός στοιχείου. Επιστρέφει στον καλούντα προτού η επεξήγηση εργαλείου έχει πραγματικά κρυφτεί (δηλαδή πριν συμβεί το hidden.bs.tooltip
συμβάν). Αυτό θεωρείται ως «χειροκίνητη» ενεργοποίηση της συμβουλής εργαλείου.
$('#element').tooltip('hide')
.tooltip('toggle')
Εναλλάσσει την επεξήγηση εργαλείου ενός στοιχείου. Επιστρέφει στον καλούντα πριν εμφανιστεί ή κρυφτεί πραγματικά η συμβουλή εργαλείου (δηλαδή πριν συμβεί το shown.bs.tooltip
ή το hidden.bs.tooltip
συμβάν). Αυτό θεωρείται ως «χειροκίνητη» ενεργοποίηση της συμβουλής εργαλείου.
$('#element').tooltip('toggle')
.tooltip('dispose')
Κρύβει και καταστρέφει την επεξήγηση εργαλείου ενός στοιχείου. Οι επεξηγήσεις εργαλείων που χρησιμοποιούν ανάθεση (οι οποίες δημιουργούνται χρησιμοποιώντας την selector
επιλογή ) δεν μπορούν να καταστραφούν μεμονωμένα σε στοιχεία ενεργοποίησης καταγωγής.
$('#element').tooltip('dispose')
.tooltip('enable')
Δίνει στην επεξήγηση εργαλείου ενός στοιχείου τη δυνατότητα να εμφανίζεται. Οι συμβουλές εργαλείων είναι ενεργοποιημένες από προεπιλογή.
$('#element').tooltip('enable')
.tooltip('disable')
Καταργεί τη δυνατότητα εμφάνισης της επεξήγησης εργαλείου ενός στοιχείου. Η συμβουλή εργαλείου θα μπορεί να εμφανιστεί μόνο εάν ενεργοποιηθεί ξανά.
$('#element').tooltip('disable')
.tooltip('toggleEnabled')
Εναλλάσσει τη δυνατότητα εμφάνισης ή απόκρυψης της επεξήγησης εργαλείου ενός στοιχείου.
$('#element').tooltip('toggleEnabled')
.tooltip('update')
Ενημερώνει τη θέση της επεξήγησης εργαλείου ενός στοιχείου.
$('#element').tooltip('update')
Εκδηλώσεις
Τύπος συμβάντος | Περιγραφή |
---|---|
show.bs.tooltip | Αυτό το συμβάν ενεργοποιείται αμέσως όταν show καλείται η μέθοδος παρουσίας. |
εμφανίζεται.bs.επεξήγηση εργαλείου | Αυτό το συμβάν ενεργοποιείται όταν η επεξήγηση εργαλείου έχει γίνει ορατή στον χρήστη (θα περιμένει να ολοκληρωθούν οι μεταβάσεις CSS). |
απόκρυψη.bs.επεξήγηση εργαλείου | Αυτό το συμβάν ενεργοποιείται αμέσως μετά την hide κλήση της μεθόδου παρουσίας. |
hidden.bs.tooltip | Αυτό το συμβάν ενεργοποιείται όταν ολοκληρωθεί η απόκρυψη της επεξήγησης εργαλείου από τον χρήστη (θα περιμένει να ολοκληρωθούν οι μεταβάσεις CSS). |
εισήχθη.bs.επεξήγηση εργαλείου | Αυτό το συμβάν ενεργοποιείται μετά το show.bs.tooltip συμβάν όταν το πρότυπο συμβουλής εργαλείου έχει προστεθεί στο DOM. |
$('#myTooltip').on('hidden.bs.tooltip', function () {
// do something...
})