Keterangan alat
Dokumentasi dan contoh untuk menambahkan tooltips Bootstrap kustom dengan CSS dan JavaScript menggunakan CSS3 untuk animasi dan atribut data-bs untuk penyimpanan judul lokal.
Ringkasan
Hal-hal yang perlu diketahui saat menggunakan plugin tooltip:
- Tooltips mengandalkan perpustakaan pihak ke-3 Popper untuk pemosisian. Anda harus menyertakan popper.min.js sebelum bootstrap.js atau menggunakan
bootstrap.bundle.min.js
/bootstrap.bundle.js
yang berisi Popper agar tooltips berfungsi! - Tooltips disertakan karena alasan kinerja, jadi Anda harus menginisialisasinya sendiri .
- Tooltips dengan judul tanpa panjang tidak pernah ditampilkan.
- Tentukan
container: 'body'
untuk menghindari masalah rendering dalam komponen yang lebih kompleks (seperti grup input, grup tombol, dll.). - Memicu tooltips pada elemen tersembunyi tidak akan berfungsi.
- Tooltips untuk
.disabled
ataudisabled
elemen harus dipicu pada elemen pembungkus. - Saat dipicu dari hyperlink yang menjangkau beberapa baris, tooltips akan dipusatkan. Gunakan
white-space: nowrap;
pada<a>
s Anda untuk menghindari perilaku ini. - Tooltips harus disembunyikan sebelum elemen terkaitnya dihapus dari DOM.
- Tooltips dapat dipicu berkat elemen di dalam shadow DOM.
prefers-reduced-motion
kueri media. Lihat bagian
pengurangan gerakan pada dokumentasi aksesibilitas kami .
Punya semua itu? Bagus, mari kita lihat bagaimana mereka bekerja dengan beberapa contoh.
Contoh: Aktifkan tooltips di mana-mana
Salah satu cara untuk menginisialisasi semua tooltips pada halaman adalah dengan memilihnya berdasarkan data-bs-toggle
atributnya:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
Contoh
Arahkan kursor ke tautan di bawah untuk melihat tooltips:
Teks placeholder untuk mendemonstrasikan beberapa tautan sebaris dengan tooltips. Ini sekarang hanya pengisi, bukan pembunuh. Konten ditempatkan di sini hanya untuk meniru keberadaan teks asli . Dan semua itu hanya untuk memberi Anda gambaran tentang bagaimana tooltips akan terlihat saat digunakan dalam situasi dunia nyata. Jadi semoga Anda sekarang telah melihat bagaimana tooltips pada tautan ini dapat bekerja dalam praktik, setelah Anda menggunakannya di situs atau proyek Anda sendiri .
Arahkan kursor ke tombol di bawah untuk melihat empat arah tooltips: atas, kanan, bawah, dan kiri. Arah dicerminkan saat menggunakan Bootstrap di 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>
Dan dengan HTML khusus ditambahkan:
<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>
Dengan SVG:
Kelancangan
Variabel
$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;
Penggunaan
Plugin tooltip menghasilkan konten dan markup sesuai permintaan, dan secara default menempatkan tooltips setelah elemen pemicunya.
Picu tooltip melalui JavaScript:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Meluap auto
danscroll
Posisi tooltip mencoba untuk berubah secara otomatis ketika wadah induk memiliki overflow: auto
atau overflow: scroll
menyukai .table-responsive
, tetapi tetap mempertahankan posisi penempatan aslinya. Untuk mengatasi ini, atur boundary
opsi (untuk pengubah flip menggunakan popperConfig
opsi) ke HTMLElement apa pun untuk mengganti nilai default, 'clippingParents'
, seperti document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Markup
Markup yang diperlukan untuk tooltip hanyalah data
atribut dan title
pada elemen HTML Anda ingin memiliki tooltip. Markup tooltip yang dihasilkan agak sederhana, meskipun memerlukan posisi (secara default, disetel top
oleh plugin).
Membuat tooltips berfungsi untuk keyboard dan pengguna teknologi bantu
Anda hanya boleh menambahkan tooltips ke elemen HTML yang secara tradisional berfokus pada keyboard dan interaktif (seperti tautan atau kontrol formulir). Meskipun elemen HTML arbitrer (seperti <span>
s) dapat dibuat fokus dengan menambahkan tabindex="0"
atribut, ini akan menambahkan penghentian tab yang berpotensi mengganggu dan membingungkan pada elemen non-interaktif untuk pengguna keyboard, dan sebagian besar teknologi pendukung saat ini tidak mengumumkan tooltip dalam situasi ini. Selain itu, jangan hanya mengandalkan hover
sebagai pemicu untuk tooltip Anda, karena ini akan membuat tooltip Anda tidak mungkin dipicu untuk pengguna keyboard.
<!-- 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>
Elemen yang dinonaktifkan
Elemen dengan disabled
atribut tidak interaktif, artinya pengguna tidak dapat memfokuskan, mengarahkan kursor, atau mengkliknya untuk memicu tooltip (atau popover). Sebagai solusinya, Anda ingin memicu tooltip dari wrapper <div>
atau <span>
, idealnya membuat keyboard-focusable menggunakan 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>
Pilihan
Opsi dapat diteruskan melalui atribut data atau JavaScript. Untuk atribut data, tambahkan nama opsi ke data-bs-
, seperti pada data-bs-animation=""
. Pastikan untuk mengubah jenis kasus dari nama opsi dari camelCase ke kebab-case saat meneruskan opsi melalui atribut data. Misalnya, alih-alih menggunakan data-bs-customClass="beautifier"
, gunakan data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
, dan
allowList
tidak dapat diberikan menggunakan atribut data.
Nama | Jenis | Bawaan | Keterangan |
---|---|---|---|
animation |
boolean | true |
Terapkan transisi fade CSS ke tooltip |
container |
string | elemen | Salah | false |
Menambahkan tooltip ke elemen tertentu. Contoh: |
delay |
nomor | obyek | 0 |
Penundaan menampilkan dan menyembunyikan tooltip (ms) - tidak berlaku untuk tipe pemicu manual Jika nomor diberikan, penundaan diterapkan ke sembunyikan/tampilkan Struktur objek adalah: |
html |
boolean | false |
Izinkan HTML di tooltip. Jika benar, tag HTML di tooltip Gunakan teks jika Anda khawatir tentang serangan XSS. |
placement |
string | fungsi | 'top' |
Bagaimana memposisikan tooltip - otomatis | atas | bawah | kiri | Baik. Ketika sebuah fungsi digunakan untuk menentukan penempatan, itu dipanggil dengan simpul DOM tooltip sebagai argumen pertamanya dan simpul DOM elemen pemicu sebagai yang kedua. Konteks |
selector |
string | Salah | false |
Jika pemilih disediakan, objek tooltip akan didelegasikan ke target yang ditentukan. Dalam praktiknya, ini juga digunakan untuk menerapkan tooltips ke elemen DOM yang ditambahkan secara dinamis ( jQuery.on dukungan). Lihat ini dan contoh yang informatif . |
template |
rangkaian | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
Dasar HTML untuk digunakan saat membuat tooltip. Tooltip
Elemen pembungkus terluar harus memiliki |
title |
string | elemen | fungsi | '' |
Nilai judul default jika Jika suatu fungsi diberikan, itu akan dipanggil dengan |
trigger |
rangkaian | 'hover focus' |
Bagaimana tooltip dipicu - klik | melayang | fokus | manual. Anda dapat melewati beberapa pemicu; pisahkan dengan spasi.
|
fallbackPlacements |
Himpunan | ['top', 'right', 'bottom', 'left'] |
Tentukan penempatan pengganti dengan memberikan daftar penempatan dalam larik (dalam urutan preferensi). Untuk informasi lebih lanjut, lihat dokumen perilaku Popper |
boundary |
string | elemen | 'clippingParents' |
Batas batasan overflow dari tooltip (hanya berlaku untuk pengubah preventOverflow Popper). Secara default itu 'clippingParents' dan dapat menerima referensi HTMLElement (hanya melalui JavaScript). Untuk informasi lebih lanjut, lihat dokumen detectOverflow Popper . |
customClass |
string | fungsi | '' |
Tambahkan kelas ke tooltip saat ditampilkan. Perhatikan bahwa kelas-kelas ini akan ditambahkan sebagai tambahan untuk setiap kelas yang ditentukan dalam template. Untuk menambahkan beberapa kelas, pisahkan dengan spasi: Anda juga dapat melewatkan fungsi yang seharusnya mengembalikan satu string yang berisi nama kelas tambahan. |
sanitize |
boolean | true |
Mengaktifkan atau menonaktifkan sanitasi. Jika diaktifkan 'template' dan 'title' opsi akan dibersihkan. Lihat bagian pembersih dalam dokumentasi JavaScript kami . |
allowList |
obyek | Nilai default | Objek yang berisi atribut dan tag yang diizinkan |
sanitizeFn |
nol | fungsi | null |
Di sini Anda dapat menyediakan fungsi sanitasi Anda sendiri. Ini dapat berguna jika Anda lebih suka menggunakan perpustakaan khusus untuk melakukan sanitasi. |
offset |
susunan | string | fungsi | [0, 0] |
Offset tooltip relatif terhadap targetnya. Anda dapat meneruskan string dalam atribut data dengan nilai yang dipisahkan koma seperti: Ketika sebuah fungsi digunakan untuk menentukan offset, itu dipanggil dengan objek yang berisi penempatan popper, referensi, dan popper rect sebagai argumen pertamanya. Node DOM elemen pemicu dilewatkan sebagai argumen kedua. Fungsi harus mengembalikan array dengan dua angka: |
popperConfig |
nol | objek | fungsi | null |
Untuk mengubah konfigurasi Popper default Bootstrap, lihat Konfigurasi Popper . Ketika sebuah fungsi digunakan untuk membuat konfigurasi Popper, itu dipanggil dengan objek yang berisi konfigurasi Popper default Bootstrap. Ini membantu Anda menggunakan dan menggabungkan default dengan konfigurasi Anda sendiri. Fungsi harus mengembalikan objek konfigurasi untuk Popper. |
Atribut data untuk masing-masing tooltips
Opsi untuk masing-masing tooltip secara alternatif dapat ditentukan melalui penggunaan atribut data, seperti dijelaskan di atas.
Menggunakan fungsi denganpopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
Metode
Metode dan transisi asinkron
Semua metode API tidak sinkron dan memulai transisi . Mereka kembali ke penelepon segera setelah transisi dimulai tetapi sebelum berakhir . Selain itu, pemanggilan metode pada komponen transisi akan diabaikan .
Lihat dokumentasi JavaScript kami untuk informasi lebih lanjut .
menunjukkan
Mengungkapkan tooltip elemen. Kembali ke pemanggil sebelum tooltip benar-benar ditampilkan (yaitu sebelum shown.bs.tooltip
event terjadi). Ini dianggap sebagai pemicu "manual" dari tooltip. Tooltips dengan judul tanpa panjang tidak pernah ditampilkan.
tooltip.show()
bersembunyi
Menyembunyikan tooltip elemen. Kembali ke pemanggil sebelum tooltip benar-benar disembunyikan (yaitu sebelum hidden.bs.tooltip
event terjadi). Ini dianggap sebagai pemicu "manual" dari tooltip.
tooltip.hide()
beralih
Mengalihkan tooltip elemen. Kembali ke pemanggil sebelum tooltip benar-benar ditampilkan atau disembunyikan (yaitu sebelum shown.bs.tooltip
atau hidden.bs.tooltip
peristiwa terjadi). Ini dianggap sebagai pemicu "manual" dari tooltip.
tooltip.toggle()
membuang
Menyembunyikan dan menghancurkan tooltip elemen (Menghapus data yang tersimpan pada elemen DOM). Tooltips yang menggunakan delegasi (yang dibuat menggunakan opsi selector
) tidak dapat dimusnahkan satu per satu pada elemen pemicu turunan.
tooltip.dispose()
memungkinkan
Memberikan tooltip elemen kemampuan untuk ditampilkan. Tooltips diaktifkan secara default.
tooltip.enable()
cacat
Menghapus kemampuan tooltip elemen untuk ditampilkan. Tooltip hanya akan dapat ditampilkan jika diaktifkan kembali.
tooltip.disable()
toggleDiaktifkan
Mengalihkan kemampuan tooltip elemen untuk ditampilkan atau disembunyikan.
tooltip.toggleEnabled()
memperbarui
Memperbarui posisi tooltip elemen.
tooltip.update()
dapatkan Instance
Metode statis yang memungkinkan Anda untuk mendapatkan contoh tooltip yang terkait dengan elemen DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Metode statis yang memungkinkan Anda mendapatkan instance tooltip yang terkait dengan elemen DOM, atau membuat yang baru jika tidak diinisialisasi
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
Acara
Jenis acara | Keterangan |
---|---|
show.bs.tooltip |
Acara ini langsung aktif ketika show metode instance dipanggil. |
shown.bs.tooltip |
Peristiwa ini dipicu ketika tooltip telah dibuat terlihat oleh pengguna (akan menunggu transisi CSS selesai). |
hide.bs.tooltip |
Acara ini dipecat segera ketika hide metode instance telah dipanggil. |
hidden.bs.tooltip |
Acara ini dipicu ketika tooltip telah selesai disembunyikan dari pengguna (akan menunggu transisi CSS selesai). |
inserted.bs.tooltip |
Peristiwa ini dipicu setelah show.bs.tooltip peristiwa ketika template tooltip telah ditambahkan ke DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()