Bootstrap Tooltip ve Popover Kullanımı: Başlatma, Seçenekler ve Erişilebilirlik

Tooltip ve popover farkı

Tooltip, bir öğenin üzerine gelindiğinde ya da öğe odaklandığında beliren kısa, tek parçalı bir açıklamadır. Popover ise başlık ve gövde içeren, varsayılan olarak tıklamayla açılan daha büyük bir kutudur. İkisinin varsayılan değerleri kaynak kodda farklıdır:

Popover sınıfı Bootstrap v5.0.2 kaynak kodu: popover.js dosyasında Tooltip sınıfını genişletir ve varsayılan seçenekleri tooltipin varsayılanlarına content ekleyip yerleşimi, ofseti, tetikleyiciyi ve şablonu değiştirerek oluşturur. Bu nedenle popover kullanıyorsanız tooltip eklentisinin de yüklü olması gerekir; bundle dosyası ikisini de içerir.

Bilmeniz gereken kurallar

Belge, iki bileşen için de aynı uyarı listesini verir. Bunları baştan bilmek, “tooltip çalışmıyor” sorunlarının çoğunu önler:

• Konumlandırma için Popper gerekir; bundle dosyasını ya da Popper ile ayrı Bootstrap dosyasını yükleyin.
• Bileşenler opt-in’dir; sayfadaki öğeleri kendiniz başlatmalısınız.
• Başlığı boş olan tooltip hiçbir zaman gösterilmez; popoverda başlık ve içeriğin ikisi de boşsa kutu açılmaz.
• Giriş grupları ve buton grupları gibi karmaşık bileşenlerde görüntü sorunlarını önlemek için container: 'body' verin.
• Gizli öğeler üzerinde tooltip tetiklenemez.
• disabled özniteliğine ya da .disabled sınıfına sahip öğeler için tooltip, bir sarmalayıcı öğe üzerinden tetiklenmelidir.
• Birden fazla satıra bölünen bağlantılarda ipucu ortalanır; bunu önlemek için bağlantıya white-space: nowrap verin (popover belgesi aynı iş için .text-nowrap sınıfını önerir).
• Öğeyi DOM’dan kaldırmadan önce tooltip ya da popoverı gizlemelisiniz.
• Shadow DOM içindeki bir öğe de tetikleyici olabilir.

Animasyon prefers-reduced-motion medya sorgusuna bağlıdır. HTML kabul eden seçenekler varsayılan olarak yerleşik temizleyiciden (sanitizer) geçer; bu konuya aşağıda ayrıca değiniyoruz.

Tooltip başlatma ve dört yön

Belgenin önerdiği kalıp, sayfadaki bütün data-bs-toggle="tooltip" öğelerini seçip her biri için bir örnek oluşturmaktır. Bu kodu Bootstrap JavaScript dosyası yüklendikten sonra çalıştırmalısınız:

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

Yönü data-bs-placement ile belirlersiniz; değerler top, right, bottom ve left’tir. Bootstrap’i RTL (sağdan sola) düzende kullandığınızda yönler aynalanır. auto verirseniz ipucu yerleşimi boş alana göre dinamik olarak değiştirilir:

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Üstte ipucu">Üst</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Sağda ipucu">Sağ</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Altta ipucu">Alt</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Solda ipucu">Sol</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<b>Kalın</b> ve <u>altı çizili</u>">HTML ipucu</button>

Tooltip eklentisi ipucu kutusunu gerektiğinde üretir ve varsayılan olarak tetikleyici öğeden sonra yerleştirir. Üretilen yapı, belgeye göre .tooltip sınıflı ve role="tooltip" öznitelikli bir kapsayıcı, içinde ok için .tooltip-arrow ve metin için .tooltip-inner öğelerinden oluşur. Kaynak kod, tooltip gösterilirken tetikleyici öğeye aria-describedby ekleyerek ipucunu ona bağlar ve gizlenince bu özniteliği kaldırır. Başlatma sırasında title değeri data-bs-original-title özniteliğine taşınır; öğenin metni ve aria-label değeri yoksa başlık aria-label olarak da yazılır. Bu yüzden başlatılmış bir tooltipin metnini değiştirmek için doğrudan title özniteliğini düzenlemek beklediğiniz sonucu vermeyebilir.

HTML içerik ve sanitizer

html seçeneği varsayılan olarak false’tur; bu durumda başlık metin olarak eklenir. data-bs-html="true" verdiğinizde title içindeki etiketler ipucunda işlenir. Belge, XSS saldırılarından endişe ediyorsanız metin modunda kalmanızı önerir.

HTML açık olsa bile içerik doğrudan sayfaya yazılmaz; tooltip ve popover, HTML kabul eden seçenekleri yerleşik bir temizleyiciden geçirir. Temizleyici, izin listesinde (allowList) olmayan bütün etiketleri ve öznitelikleri siler. Varsayılan listede b, i, u, strong, small, span, p, ul, ol, li, başlık etiketleri gibi metin öğeleri; href, target, title ve rel öznitelikleriyle a; src, alt gibi özniteliklerle img bulunur. Her öğede ayrıca class, dir, id, lang, role ve aria- ile başlayan öznitelikler serbesttir. Tablo gibi listede olmayan öğelere izin vermek için listeyi genişletirsiniz:

var myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// Tablo ogelerine izin ver
myDefaultAllowList.table = []

// td ogelerine ve uzerindeki data-bs-option ozniteligine izin ver
myDefaultAllowList.td = ['data-bs-option']

// Tum ogeler icin kendi duzenli ifadenizle oznitelik izni
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

Belge, düzenli ifadelerin fazla gevşek olmamasına dikkat etmenizi ister. DOMPurify gibi ayrı bir kütüphane kullanmak isterseniz sanitizeFn seçeneğine kendi temizleme fonksiyonunuzu verebilirsiniz. Güvenlik nedeniyle sanitize, sanitizeFn ve allowList seçenekleri veri öznitelikleriyle verilemez; yalnızca JavaScript tarafında ayarlanabilir. Bu kural, sayfaya dışarıdan HTML enjekte edebilen birinin temizleyiciyi öznitelik üzerinden kapatmasını engeller.

Devre dışı öğeler ve erişilebilirlik

disabled özniteliğine sahip bir buton etkileşimli değildir: kullanıcı onu odaklayamaz, üzerine gelmesi ya da tıklaması olay üretmez. Bu yüzden ipucunu doğrudan devre dışı butona bağlarsanız hiç görünmez. Çözüm, butonu bir <span> ya da <div> ile sarıp tooltipi sarmalayıcıya vermek ve klavye ile ulaşılabilmesi için sarmalayıcıya tabindex="0" eklemektir. .d-inline-block sınıfı sarmalayıcının buton kadar yer kaplamasını sağlar:

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Önce formu doldurun">
  <button class="btn btn-primary" type="button" disabled>Gönder</button>
</span>

Erişilebilirlik konusunda belge net kurallar koyar. Tooltipleri yalnızca bağlantılar ve form kontrolleri gibi doğası gereği klavyeyle odaklanabilen ve etkileşimli öğelere ekleyin. Herhangi bir <span> öğesini tabindex="0" ile odaklanabilir yapmak mümkündür, ancak bu klavye kullanıcıları için kafa karıştırıcı fazladan sekme durakları yaratır ve çoğu yardımcı teknoloji bu durumda ipucunu duyurmaz. Ayrıca tetikleyici olarak yalnızca hover kullanmayın; bu, klavye kullanıcılarının ipucunu hiç açamaması demektir. Varsayılan hover focus değeri bu yüzden iki yolu birden açık tutar. ARIA özniteliklerinin genel anlamı için ARIA yazısına, Bootstrap tarafındaki kurallar için erişilebilirlik yazısına bakabilirsiniz.

Popover: başlatma, yönler ve sonraki tıklamada kapanma

Popover başlatma kalıbı tooltip ile aynıdır, yalnızca seçici ve sınıf adı değişir:

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

Başlığı title, gövdeyi data-bs-content özniteliği verir. Yönler yine data-bs-placement ile seçilir. Belgedeki dört yön örneği data-bs-container="body" de kullanır; böylece popover HTML kodu butonun yanına değil doğrudan <body> içine eklenir ve üst öğelerin stillerinden etkilenmez:

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Kargo bilgisi" data-bs-content="Siparişler 1-3 iş günü içinde teslim edilir.">Kargo süresi</button>

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Alttaki popover">
  Altta aç
</button>

Popoverın, kullanıcı sayfada başka bir yere tıkladığında kapanmasını istiyorsanız focus tetikleyicisini kullanırsınız. Belge burada özel bir işaretleme şartı koyar: tarayıcılar ve platformlar arasında doğru davranış için <button> değil <a> etiketi kullanmalı ve bir tabindex özniteliği eklemelisiniz:

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="İade koşulları" data-bs-content="Ürünü 14 gün içinde iade edebilirsiniz.">İade koşulları</a>

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Stokta yok">
  <button class="btn btn-primary" type="button" disabled>Sepete ekle</button>
</span>

İkinci örnek devre dışı bir butonun popoverıdır. Belge, kullanıcılar devre dışı bir öğeye tıklamayı beklemeyeceği için bu durumda data-bs-trigger="hover focus" kullanmanızın daha iyi bir görsel geri bildirim sağlayacağını belirtir.

Popover için erişilebilirlik uyarıları daha da kapsamlıdır. html seçeneğiyle zengin içerik koyabilirsiniz ama çok fazla içerikten kaçınmalısınız: popover açıldığında içeriği tetikleyiciye aria-describedby ile bağlanır ve ekran okuyucu bütün içeriği tek ve kesintisiz bir akış olarak okur. Popover içine form alanı ya da bağlantı gibi etkileşimli öğeler koymak teknik olarak mümkündür (izin listesine eklenirse), ancak popover klavye odak sırasını yönetmez; odak tetikleyicide kalır ve Tab tuşunun kullanıcıyı popoverın içine götüreceğinin garantisi yoktur. Belge bu tür durumlarda bunun yerine modal pencere kullanmayı önerir.

Ortak seçenekler

Seçenekler JavaScript ile ya da veri öznitelikleriyle verilir. Veri özniteliklerinde seçenek adı camelCase’ten kebab-case’e çevrilir: customClass için data-bs-customClass değil data-bs-custom-class yazılır. Belgede listelenen başlıca seçenekler şunlardır (popover için farklı olan varsayılanlar yukarıdaki tabloda verildi):

manual tetikleyici, kutunun yalnızca show(), hide() ve toggle() yöntemleriyle açılıp kapanacağı anlamına gelir ve başka bir tetikleyiciyle birleştirilemez. delay seçeneği manual tetikleyicide uygulanmaz; nesne biçimi { "show": 500, "hide": 100 } şeklindedir. selector seçeneği özellikle sayfaya sonradan eklenen öğeler için kullanışlıdır: tek bir üst öğede başlatırsınız, eşleşen alt öğeler kendiliğinden ipucu kazanır. Ancak belgeye göre bu devretme yoluyla oluşturulan tooltipler alt öğeler üzerinde tek tek yok edilemez.

Kaydırılabilir kapsayıcılarda bir tuzak vardır. Üst öğede overflow: auto ya da overflow: scroll varsa, örneğin .table-responsive tablolarda, ipucu konumu değişmeye çalışır ama asıl yerleşimin konumlandırmasını korur. Belge bu durumda boundary seçeneğine document.body gibi bir HTML öğesi vermenizi önerir:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: document.body,
  delay: { show: 300, hide: 100 },
  customClass: 'genis-ipucu'
})

Yöntemler ve olaylar

Tooltip ve popover aynı yöntem kümesini paylaşır: show(), hide() ve toggle() kutuyu elle açar, kapatır ya da değiştirir; belge bunları “manuel” tetikleme sayar. dispose() kutuyu gizler ve örneği yok eder. enable(), disable() ve toggleEnabled() kutunun gösterilebilir olup olmadığını denetler; tooltipler varsayılan olarak etkindir. update() kutunun konumunu yeniden hesaplar. Statik getInstance() ve getOrCreateInstance() öğeye bağlı örneği verir. Bütün bu yöntemler eşzamansızdır ve geçiş bitmeden döner.

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl)

tooltip.show()
tooltip.update()
tooltip.disable()

exampleTriggerEl.addEventListener('hidden.bs.tooltip', function () {
  // ipucu tamamen gizlendi
})

Her iki bileşen de beş olay yayar; tooltip için sonek .bs.tooltip, popover için .bs.popover’dır:

Olayların preventDefault() desteği, seçeneklerin Default nesnesi üzerinden genel olarak değiştirilmesi ve jQuery ile kullanım Bootstrap JavaScript API yazısında anlatılır. Modal içine yerleştirilen tooltip ve popoverlar modal kapandığında kendiliğinden gizlenir.

Sık yapılan hatalar

• Başlatma kodunu yazmamak: data-bs-toggle="tooltip" tek başına ipucu göstermez; yukarıdaki başlatma kalıbını ekleyin.
• Popper olmadan bootstrap.min.js yüklemek: Tooltip ve popover Popper gerektirir. Ya bundle dosyasını kullanın ya da Popper’ı Bootstrap’ten önce ekleyin. Dosya seçenekleri için CDN kurulum yazısına bakın.
• ES modül olarak yüklemek: Belgeye göre Dropdown, Tooltip ve Popover eklentileri Popper’a bağlı oldukları için <script type="module"> içinde kullanılamaz.
• Devre dışı butona doğrudan ipucu vermek: Butonu sarmalayıcıya alın.
• Öğeyi kaldırmadan önce kutuyu gizlememek: Belge, tooltipin öğe DOM’dan silinmeden önce gizlenmesini şart koşar.
• Aynı öğeye hem tooltip hem modal bağlamak: Bir öğede tek bir veri özniteliği takımı kullanılabilir.
• Kebab-case kuralını atlamak: data-bs-customClass çalışmaz, data-bs-custom-class yazın.

Bootstrap 4’ten gelen data-toggle="tooltip" kodunun neden çalışmadığı geçiş yazısında, diğer yaygın sorunlar sık hatalar yazısında yer alır.

Sık Sorulan Sorular

Bootstrap tooltip neden görünmüyor?

En sık iki neden, tooltipin JavaScript ile başlatılmamış olması ve Popper içermeyen bootstrap.min.js dosyasının tek başına yüklenmesidir. Başlığın boş olmadığını ve öğenin gizli olmadığını da kontrol edin.

Popover dışarı tıklayınca nasıl kapanır?

data-bs-trigger="focus" kullanın, tetikleyici olarak tabindex="0" içeren bir <a> etiketi seçin.

Tooltipe HTML koyabilir miyim?

Evet, data-bs-html="true" ile. İçerik yerleşik temizleyiciden geçer ve izin listesinde olmayan etiketler silinir.

Sonradan eklenen öğelerde tooltip nasıl çalışır?

Üst öğede selector seçeneğiyle başlatın ya da yeni öğeyi ekledikten sonra onun için ayrıca new bootstrap.Tooltip() çağırın.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Bootstrap öğrenme rehberi · Bootstrap JavaScript API · Dropdown menü · Modal pencere · Erişilebilirlik · JavaScript öğrenme rehberi