in English

Petua alat

Dokumentasi dan contoh untuk menambah petua alat Bootstrap tersuai dengan CSS dan JavaScript menggunakan CSS3 untuk animasi dan atribut data untuk storan tajuk tempatan.

Gambaran keseluruhan

Perkara yang perlu diketahui apabila menggunakan pemalam tooltip:

  • Petua alat bergantung pada pustaka pihak ke-3 Popper untuk kedudukan. Anda mesti menyertakan popper.min.js sebelum bootstrap.js atau gunakan bootstrap.bundle.min.js/ bootstrap.bundle.jsyang mengandungi Popper agar petua alat berfungsi!
  • Jika anda sedang membina JavaScript kami daripada sumber, ia memerlukanutil.js .
  • Petua alat ikut serta atas sebab prestasi, jadi anda mesti memulakannya sendiri .
  • Petua alat dengan tajuk panjang sifar tidak pernah dipaparkan.
  • Tentukan container: 'body'untuk mengelakkan masalah rendering dalam komponen yang lebih kompleks (seperti kumpulan input kami, kumpulan butang, dll).
  • Mencetuskan petua alat pada elemen tersembunyi tidak akan berfungsi.
  • Petua alat untuk .disabledatau disabledelemen mesti dicetuskan pada elemen pembalut.
  • Apabila dicetuskan daripada hiperpautan yang menjangkau berbilang baris, petua alat akan dipusatkan. Gunakan white-space: nowrap;pada <a>s anda untuk mengelakkan tingkah laku ini.
  • Petua alat mesti disembunyikan sebelum elemen yang sepadan dialih keluar daripada DOM.
  • Petua alat boleh dicetuskan terima kasih kepada elemen dalam DOM bayangan.
Secara lalai, komponen ini menggunakan sanitizer kandungan terbina dalam, yang menghilangkan sebarang elemen HTML yang tidak dibenarkan secara jelas. Lihat bahagian sanitizer dalam dokumentasi JavaScript kami untuk mendapatkan butiran lanjut.
Kesan animasi komponen ini bergantung pada prefers-reduced-motionpertanyaan media. Lihat bahagian gerakan yang dikurangkan dalam dokumentasi kebolehaksesan kami .

Dapat semua itu? Hebat, mari lihat cara ia berfungsi dengan beberapa contoh.

Contoh: Dayakan petua alat di mana-mana sahaja

Satu cara untuk memulakan semua petua alat pada halaman ialah memilihnya mengikut data-toggleatributnya:

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

Contoh

Tuding pada pautan di bawah untuk melihat petua alat:

Teks pemegang tempat untuk menunjukkan beberapa pautan sebaris dengan petua alat. Ini kini hanya pengisi, tiada pembunuh. Kandungan diletakkan di sini hanya untuk meniru kehadiran teks sebenar . Dan semua itu hanya untuk memberi anda gambaran tentang rupa petua alat apabila digunakan dalam situasi dunia sebenar. Jadi diharapkan anda kini telah melihat bagaimana petua alat pada pautan ini boleh berfungsi dalam amalan, sebaik sahaja anda menggunakannya di tapak atau projek anda sendiri .

Tuding pada butang di bawah untuk melihat empat arah petua alat: atas, kanan, bawah dan kiri.

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

Dan dengan HTML tersuai ditambahkan:

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

Penggunaan

Pemalam petua alat menjana kandungan dan penanda atas permintaan, dan secara lalai meletakkan petua alat selepas elemen pencetusnya.

Cetuskan petua alat melalui JavaScript:

$('#example').tooltip(options)
Limpahan autodanscroll

Kedudukan petua alat cuba menukar secara automatik apabila bekas induk mempunyai overflow: autoatau overflow: scrollmenyukai kami .table-responsive, tetapi masih mengekalkan kedudukan peletakan asal. Untuk menyelesaikan, tetapkan boundarypilihan kepada apa-apa selain nilai lalai, 'scrollParent', seperti 'window':

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

Penanda

Penanda yang diperlukan untuk petua alat hanyalah dataatribut dan titlepada elemen HTML anda ingin mempunyai petua alat. Penanda yang dijana bagi petua alat agak mudah, walaupun ia memerlukan kedudukan (secara lalai, ditetapkan topoleh pemalam).

Membuat petua alat berfungsi untuk papan kekunci dan pengguna teknologi bantuan

Anda hanya perlu menambah petua alat pada elemen HTML yang secara tradisinya boleh memfokus papan kekunci dan interaktif (seperti pautan atau kawalan borang). Walaupun elemen HTML sewenang-wenangnya (seperti <span>s) boleh dijadikan boleh difokuskan dengan menambahkan tabindex="0"atribut, ini akan menambah hentian tab yang berpotensi menjengkelkan dan mengelirukan pada elemen bukan interaktif untuk pengguna papan kekunci, dan kebanyakan teknologi bantuan pada masa ini tidak mengumumkan petua alat dalam situasi ini. Selain itu, jangan bergantung semata-mata hoversebagai pencetus untuk petua alat anda, kerana ini akan menjadikan petua alat anda mustahil untuk dicetuskan untuk pengguna papan kekunci.

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

Elemen yang dilumpuhkan

Elemen dengan disabledatribut tidak interaktif, bermakna pengguna tidak boleh memfokus, menuding atau mengkliknya untuk mencetuskan petua alat (atau popover). Sebagai penyelesaian, anda perlu mencetuskan petua alat daripada pembalut <div>atau <span>, yang idealnya boleh difokuskan papan kekunci menggunakan tabindex="0", dan mengatasi pointer-eventselemen pada elemen yang dilumpuhkan.

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

Pilihan

Pilihan boleh dihantar melalui atribut data atau JavaScript. Untuk atribut data, tambahkan nama pilihan pada data-, seperti dalam data-animation="".

Ambil perhatian bahawa atas sebab keselamatan sanitize, sanitizeFndan whiteListpilihan tidak boleh dibekalkan menggunakan atribut data.
Nama taip Lalai Penerangan
animasi boolean benar Gunakan peralihan pudar CSS pada petua alat
bekas rentetan | unsur | salah salah

Menambahkan petua alat pada elemen tertentu. Contoh: container: 'body'. Pilihan ini amat berguna kerana ia membolehkan anda meletakkan petua alat dalam aliran dokumen berhampiran elemen pencetus - yang akan menghalang petua alat daripada terapung dari elemen pencetus semasa mengubah saiz tetingkap.
kelewatan nombor | objek 0

Kelewatan menunjukkan dan menyembunyikan petua alat (ms) - tidak digunakan untuk jenis pencetus manual

Jika nombor dibekalkan, kelewatan dikenakan pada kedua-dua sembunyi/tunjukkan

Struktur objek ialah:delay: { "show": 500, "hide": 100 }
html boolean salah

Benarkan HTML dalam petua alat.

Jika benar, teg HTML dalam petua alat titleakan dipaparkan dalam petua alat. Jika palsu, textkaedah jQuery akan digunakan untuk memasukkan kandungan ke dalam DOM.

Gunakan teks jika anda bimbang tentang serangan XSS.
penempatan rentetan | fungsi 'atas'

Cara meletakkan petua alat - auto | atas | bawah | kiri | betul.
Apabila autoditentukan, ia akan mengorientasikan semula petua alat secara dinamik.

Apabila fungsi digunakan untuk menentukan peletakan, ia dipanggil dengan nod DOM petua alat sebagai hujah pertamanya dan nod DOM elemen pencetus sebagai yang kedua. Konteks ditetapkan thiskepada contoh petua alat.
pemilih rentetan | salah salah Jika pemilih disediakan, objek petua alat akan diwakilkan kepada sasaran yang ditentukan. Dalam amalan, ini digunakan untuk turut menggunakan petua alat untuk menambahkan elemen DOM ( jQuery.onsokongan) secara dinamik. Lihat ini dan contoh bermaklumat .
templat tali '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML asas untuk digunakan semasa membuat petua alat.

Petua alat titleakan disuntik ke dalam .tooltip-inner.

.arrowakan menjadi anak panah petua alat.

Elemen pembungkus paling luar harus mempunyai .tooltipkelas dan role="tooltip".
tajuk rentetan | unsur | fungsi ''

Nilai tajuk lalai jika titleatribut tidak ada.

Jika fungsi diberikan, ia akan dipanggil dengan thisset rujukannya kepada elemen yang dilampirkan petua alat.
pencetus tali 'legar fokus'

Cara petua alat dicetuskan - klik | tuding | tumpuan | manual. Anda boleh melepasi pelbagai pencetus; pisahkan mereka dengan ruang.

'manual'menunjukkan bahawa petua alat akan dicetuskan secara pemrograman melalui kaedah .tooltip('show'), .tooltip('hide')dan .tooltip('toggle'); nilai ini tidak boleh digabungkan dengan mana-mana pencetus lain.

'hover'dengan sendirinya akan menghasilkan petua alat yang tidak boleh dicetuskan melalui papan kekunci, dan hanya boleh digunakan jika kaedah alternatif untuk menyampaikan maklumat yang sama untuk pengguna papan kekunci ada.
mengimbangi nombor | rentetan | fungsi 0

Mengimbangi petua alat berbanding sasarannya.

Apabila fungsi digunakan untuk menentukan ofset, ia dipanggil dengan objek yang mengandungi data offset sebagai hujah pertamanya. Fungsi mesti mengembalikan objek dengan struktur yang sama. Nod DOM elemen pencetus diluluskan sebagai hujah kedua.

Untuk maklumat lanjut rujuk kepada dokumen offset Popper .
fallbackPlacement rentetan | tatasusunan 'terbalik' Benarkan untuk menentukan kedudukan yang Popper akan gunakan pada sandaran. Untuk maklumat lanjut rujuk dokumen tingkah laku Popper
customClass rentetan | fungsi ''

Tambahkan kelas pada petua alat apabila ia ditunjukkan. Ambil perhatian bahawa kelas ini akan ditambah sebagai tambahan kepada mana-mana kelas yang dinyatakan dalam templat. Untuk menambah berbilang kelas, pisahkan mereka dengan ruang: 'a b'.

Anda juga boleh lulus fungsi yang harus mengembalikan rentetan tunggal yang mengandungi nama kelas tambahan.
sempadan rentetan | unsur 'scrollParent' Sempadan kekangan limpahan petua alat. Menerima nilai 'viewport', 'window', 'scrollParent', atau rujukan HTMLElement (JavaScript sahaja). Untuk maklumat lanjut rujuk dokumen preventOverflow Popper .
membersihkan boolean benar Dayakan atau lumpuhkan sanitasi. Jika diaktifkan 'template'dan 'title'pilihan akan dibersihkan. Lihat bahagian sanitizer dalam dokumentasi JavaScript kami .
senarai putih objek Nilai asal Objek yang mengandungi atribut dan tag yang dibenarkan
sanitasiFn null | fungsi null Di sini anda boleh membekalkan fungsi sanitasi anda sendiri. Ini boleh berguna jika anda lebih suka menggunakan perpustakaan khusus untuk melakukan sanitasi.
popperConfig null | objek null Untuk menukar konfigurasi Popper lalai Bootstrap, lihat konfigurasi Popper

Atribut data untuk petua alat individu

Pilihan untuk petua alat individu boleh ditentukan secara alternatif melalui penggunaan atribut data, seperti yang dijelaskan di atas.

Kaedah

Kaedah dan peralihan tak segerak

Semua kaedah API adalah tak segerak dan mulakan peralihan . Mereka kembali kepada pemanggil sebaik sahaja peralihan dimulakan tetapi sebelum ia tamat . Selain itu, panggilan kaedah pada komponen peralihan akan diabaikan .

Lihat dokumentasi JavaScript kami untuk mendapatkan maklumat lanjut .

$().tooltip(options)

Melampirkan pengendali petua alat pada koleksi elemen.

.tooltip('show')

Mendedahkan petua alat elemen. Kembali kepada pemanggil sebelum petua alat sebenarnya ditunjukkan (iaitu sebelum shown.bs.tooltipperistiwa berlaku). Ini dianggap sebagai pencetus "manual" petua alat. Petua alat dengan tajuk panjang sifar tidak pernah dipaparkan.

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

.tooltip('hide')

Menyembunyikan petua alat elemen. Kembali kepada pemanggil sebelum petua alat sebenarnya disembunyikan (iaitu sebelum hidden.bs.tooltipperistiwa berlaku). Ini dianggap sebagai pencetus "manual" petua alat.

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

.tooltip('toggle')

Menogol petua alat elemen. Kembali kepada pemanggil sebelum petua alat benar-benar ditunjukkan atau disembunyikan (iaitu sebelum shown.bs.tooltipatau hidden.bs.tooltipperistiwa berlaku). Ini dianggap sebagai pencetus "manual" petua alat.

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

.tooltip('dispose')

Menyembunyikan dan memusnahkan petua alat elemen. Petua alat yang menggunakan perwakilan (yang dibuat menggunakan pilihan ) tidak selectorboleh dimusnahkan secara individu pada elemen pencetus keturunan.

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

.tooltip('enable')

Memberi petua alat elemen keupayaan untuk ditunjukkan. Petua alat didayakan secara lalai.

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

.tooltip('disable')

Mengalih keluar keupayaan untuk petua alat elemen untuk ditunjukkan. Petua alat hanya akan dapat ditunjukkan jika ia didayakan semula.

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

.tooltip('toggleEnabled')

Togol keupayaan untuk petua alat elemen untuk ditunjukkan atau disembunyikan.

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

.tooltip('update')

Mengemas kini kedudukan petua alat elemen.

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

Peristiwa

Jenis acara Penerangan
show.bs.tooltip Peristiwa ini menyala serta-merta apabila showkaedah contoh dipanggil.
ditunjukkan.bs.petua alat Peristiwa ini dicetuskan apabila petua alat telah dilihat kepada pengguna (akan menunggu peralihan CSS selesai).
hide.bs.tooltip Peristiwa ini dicetuskan serta-merta apabila hidekaedah contoh telah dipanggil.
hidden.bs.tooltip Peristiwa ini dicetuskan apabila petua alat telah selesai disembunyikan daripada pengguna (akan menunggu peralihan CSS selesai).
inserted.bs.tooltip Acara ini dicetuskan selepas show.bs.tooltipacara apabila templat petua alat telah ditambahkan pada DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})