Bootstrap JavaScript API: data-bs Öznitelikleri, Yöntemler ve Olaylar

Hangi bileşenler JavaScript gerektirir

Bootstrap’in büyük kısmı yalnızca CSS’tir; grid, yardımcı sınıflar, kartlar, tablolar ve butonlar JavaScript olmadan çalışır. Bootstrap 5.0: Introduction sayfası, JavaScript’e açıkça ihtiyaç duyan bileşenleri şöyle sıralar:

Bu listeye offcanvas ve sekmeler (Tab) de eklenebilir; ikisinin de kaynak dosyası js/src klasöründe bulunur ve ilgili belge sayfalarında JavaScript kullanımları anlatılır. Bileşen ayrıntıları için modal, carousel, toast, tooltip ve popover, scrollspy, dropdown ve collapse yazılarına bakabilirsiniz.

Dosya seçimi: tek dosya, bundle veya ayrı eklentiler

Eklentileri tek tek, Bootstrap’in js/dist/*.js dosyalarıyla ekleyebilir ya da hepsini birden bootstrap.js veya küçültülmüş bootstrap.min.js ile yükleyebilirsiniz. Belge ikisini birlikte eklememenizi açıkça söyler; aynı eklentiler iki kez tanımlanır. Webpack veya Rollup gibi bir paketleyici kullanıyorsanız UMD biçimindeki js/dist/*.js dosyaları doğrudan kullanılabilir.

Bağımlılıklar konusunda iki kural vardır. Bazı eklentiler ve CSS bileşenleri başka eklentilere bağlıdır; eklentileri tek tek ekliyorsanız her bileşenin belge sayfasındaki bağımlılıkları kontrol etmelisiniz. Örneğin popover, tooltip eklentisi olmadan çalışmaz. İkincisi, dropdown, popover ve tooltip konumlandırma için Popper kütüphanesine bağlıdır. bootstrap.bundle.min.js Popper’ı içinde barındırır; bootstrap.min.js kullanıyorsanız Popper’ı ondan önce ayrıca yüklemelisiniz. Aşağıdaki örnek bundle dosyasını kullanır ve iki bileşeni yalnızca veri öznitelikleriyle çalıştırır:

<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#detaylar" aria-expanded="false" aria-controls="detaylar">
  Detayları göster
</button>
<div class="collapse" id="detaylar">
  <div class="card card-body">Paket ayrıntıları burada.</div>
</div>

<div class="alert alert-warning alert-dismissible fade show" role="alert">
  Bakım çalışması bu gece 02.00'de başlayacak.
  <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Kapat"></button>
</div>

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>

integrity değeri Bootstrap 5.0.2 belgesinin yapılandırmasındaki bundle özetidir; integrity ve crossorigin özniteliklerinin ne işe yaradığını integrity ve crossorigin yazısında bulabilirsiniz. CDN bağlantılarının tamamı ve başlangıç şablonu CDN kurulum yazısında, npm ile kurulum npm, webpack ve parcel yazısında yer alır.

Bootstrap’i ES modülü olarak kullanmak

Bootstrap, tarayıcıda modül olarak kullanılabilen ESM derlemeleri de sunar: bootstrap.esm.js ve bootstrap.esm.min.js. Hedeflediğiniz tarayıcılar modülleri destekliyorsa bileşenleri adlarıyla içe aktarırsınız. Belgedeki örnek bütün toastları modül içinden başlatır:

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

Burada önemli bir sınırlama vardır: belgeye göre tarayıcı kısıtlamaları nedeniyle Dropdown, Tooltip ve Popover eklentileri type="module" olan bir <script> etiketi içinde kullanılamaz, çünkü Popper’a bağlıdırlar ve tarayıcı bu bağımlılığı çıplak bir modül adıyla çözemez. Bu üç bileşen için klasik script etiketi ya da bir paketleyici kullanmalısınız.

Veri öznitelikleri: data-bs-* API

Neredeyse bütün Bootstrap eklentileri yalnızca HTML ile, veri öznitelikleri aracılığıyla etkinleştirilip ayarlanabilir ve belge bunu tercih edilen yol olarak tanımlar. Tetikleyici öğeye data-bs-toggle ile bileşen türünü, data-bs-target ile hedefi verirsiniz; seçenekler ise seçenek adının başına data-bs- eklenerek yazılır: data-bs-backdrop="static", data-bs-interval="3000", data-bs-delay="10000" gibi. Birden fazla kelimeden oluşan seçenek adları camelCase’ten kebab-case’e çevrilir; customClass için data-bs-custom-class yazılır.

Öznitelik değerleri her zaman metindir, peki Bootstrap "false" ile false arasındaki farkı nasıl anlar? Bootstrap v5.0.2 kaynak kodu: manipulator.js dosyasındaki dönüştürücü değerleri şu kurallarla çevirir:

Bu yüzden data-bs-interval="false" gerçekten false olarak okunur ve carousel otomatik dönmez. data-bs-interval="5 000" gibi boşluk içeren bir değer ise sayıya birebir dönüşmediği için metin olarak kalır. Bootstrap ayrıca seçeneklerin türünü denetler: carousel interval için sayı ya da boolean beklediğinden bu metni kabul etmez. Genel olarak bir seçeneğe yanlış türde değer verildiğinde kaynak kod, bileşen adını, seçeneği, verilen türü ve beklenen türü belirten bir TypeError fırlatır. Hata konsolunda böyle bir mesaj görürseniz öznitelik değerinizi kontrol edin.

Belgenin veri öznitelikleri için koyduğu en önemli kural şudur: tek bir öğede yalnızca bir takım veri özniteliği kullanın. Örneğin aynı buton hem tooltip hem modal tetikleyemez. Böyle bir ihtiyaçta butonu bir <span> ile sarıp tooltipi sarmalayıcıya, modalı butona verirsiniz. İkinci kural seçicilerle ilgilidir: Bootstrap öğeleri performans nedeniyle yerel querySelector ve querySelectorAll yöntemleriyle bulur; bu yüzden data-bs-target gibi yerlerde geçerli CSS seçicileri kullanmalısınız. collapse:Example gibi özel karakter içeren bir kimlik kullanıyorsanız karakterleri kaçışlamanız gerekir.

Olaylar: show ve shown farkı

Bootstrap, eklentilerin kendine özgü eylemlerinin çoğu için özel olaylar sağlar. Olay adları genelde iki biçimde gelir: mastar biçimi (örneğin show) eylemin başında, geçmiş zaman ortacı biçimi (örneğin shown) ise eylem tamamlandığında tetiklenir. Olay adının sonuna bileşenin ad alanı eklenir: show.bs.modal, hidden.bs.toast, slid.bs.carousel, shown.bs.collapse gibi.

Mastar biçimli bütün olaylar preventDefault() desteği sunar; böylece bir eylemi başlamadan durdurabilirsiniz. Olay işleyicisinden false döndürmek de otomatik olarak preventDefault() çağırır. Belgedeki örnek, gerekli veri yoksa modalın açılmasını engeller:

var myModal = document.getElementById('myModal')

myModal.addEventListener('show.bs.modal', function (event) {
  if (!data) {
    return event.preventDefault() // modalin gosterilmesini durdurur
  }
})

Geçmiş zaman biçimli olaylar (shown, hidden, slid) ise eylem bittikten sonra çalıştığı için iptal edilemez; bunlar odak taşıma, içerik yükleme ya da sayaç güncelleme gibi “bittikten sonra” işleri içindir.

Programatik API: yapıcı, getInstance ve getOrCreateInstance

Bütün yapıcılar isteğe bağlı bir seçenek nesnesi alır; hiçbir şey vermezseniz eklenti varsayılan davranışla başlar:

var myModalEl = document.getElementById('myModal')

var modal = new bootstrap.Modal(myModalEl) // varsayilan seceneklerle
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // Esc ile kapanmaz

// Ilk arguman olarak CSS secici de verilebilir
var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')

Yapıcıya öğe yerine bir CSS seçici verdiğinizde öğe querySelector ile bulunur; eklentiler tek bir öğeyi desteklediğinden seçiciye uyan ilk öğe kullanılır. Birden fazla öğeyi başlatmak için querySelectorAll ile seçip her biri için ayrı örnek oluşturursunuz, tooltip ve toast yazılarındaki başlatma kalıpları bunu yapar.

Bir öğeye bağlı mevcut örneği almak için her eklentinin statik getInstance yöntemi vardır: bootstrap.Popover.getInstance(myPopoverEl). Örnek yoksa bu yöntem null döndürür. Modal, carousel, toast, tooltip, popover ve scrollspy gibi bileşenlerin belge sayfaları bir de getOrCreateInstance yöntemini anlatır; bu yöntem örnek varsa onu, yoksa verilen seçeneklerle yenisini oluşturup döndürür. Her iki yöntem de Bootstrap v5.0.2 kaynak kodu: base-component.js dosyasındaki ortak temel sınıfta tanımlıdır. Aynı öğe için iki kez new çağırmak yerine getOrCreateInstance kullanmak, özellikle bir butona her tıklandığında çalışan kodlarda daha güvenlidir:

var el = document.getElementById('myModal')

var a = bootstrap.Modal.getInstance(el)          // henuz ornek yoksa null doner
var b = bootstrap.Modal.getOrCreateInstance(el)  // yoksa olusturur
var c = bootstrap.Modal.getOrCreateInstance(el)  // ayni ornegi tekrar verir

b.dispose() // ogedeki ornek verisini siler

dispose() öğe üzerinde saklanan örnek verisini ve bileşenin bu öğeye bağladığı olay dinleyicilerini kaldırır. Bir bileşeni farklı seçeneklerle yeniden kurmak istiyorsanız önce dispose(), sonra yeni bir yapıcı çağrısı yaparsınız.

Eşzamansız yöntemler ve geçişler

Programatik API yöntemlerinin hepsi eşzamansızdır: geçiş başladığı anda çağırana döner, bitmesini beklemez. Geçiş tamamlandıktan sonra bir şey yapmak istiyorsanız ilgili olayı dinlersiniz. Ayrıca geçiş sürerken aynı bileşen üzerinde yapılan yöntem çağrısı yok sayılır. Belgenin carousel örneği bunu açıkça gösterir:

var myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl)

myCarouselEl.addEventListener('slid.bs.carousel', function (event) {
  carousel.to('2') // 1. slayda gecis bitince 2. slayda gider
})

carousel.to('1') // 1. slayda gecisi baslatir ve hemen doner
carousel.to('2') // yok sayilir: onceki gecis bitmedi

Bu davranış en sık şu hatayla karşınıza çıkar: bir modalı kapatıp hemen ardından başka bir modalı açan kod, ikinci çağrının sessizce kaybolması yüzünden çalışmıyor gibi görünür. Doğru çözüm ikinci işlemi hidden.bs.modal olayının içine taşımaktır.

Varsayılan ayarları değiştirmek

Bir eklentinin varsayılan seçeneklerini, sayfadaki bütün örnekleri etkileyecek biçimde, eklentinin Constructor.Default nesnesi üzerinden değiştirebilirsiniz. Bu değişikliği örnekleri oluşturmadan önce yapmalısınız:

// Modal eklentisinin keyboard varsayilanini false yapar
bootstrap.Modal.Default.keyboard = false

// Surum bilgisi her eklentinin VERSION ozelliginde
console.log(bootstrap.Tooltip.VERSION)

Her eklentinin sürümü yapıcısının VERSION özelliğinden okunur; bu yazının dayandığı kaynak kodda değer 5.0.2’dir. Kodun hangi Bootstrap sürümüyle çalıştığını doğrulamak için kullanışlıdır. Tooltip ve popover gibi HTML kabul eden bileşenlerin temizleyici izin listesi de aynı yolla, bootstrap.Tooltip.Default.allowList üzerinden genişletilir; ayrıntısı tooltip ve popover yazısında.

jQuery ile kullanım ve noConflict

Bootstrap 5 jQuery olmadan kullanılmak üzere tasarlanmıştır, ama jQuery ile kullanmak hâlâ mümkündür. Bootstrap window nesnesinde jQuery bulursa bütün bileşenleri jQuery eklenti sistemine ekler; böylece $('[data-bs-toggle="tooltip"]').tooltip() gibi bir çağrıyla tooltipleri etkinleştirebilirsiniz.

Olaylar konusunda dikkat edilmesi gereken bir ayrıntı vardır. jQuery window üzerinde mevcutsa ve <body> öğesinde data-bs-no-jquery özniteliği yoksa, Bootstrap olaylarını jQuery’nin olay sistemi üzerinden de yayar. Belge bu durumda olayları addEventListener yerine jQuery’nin .on ve .one yöntemleriyle dinlemenizi söyler. Sayfanızda jQuery var ama Bootstrap’in onu kullanmasını istemiyorsanız <body> öğesine data-bs-no-jquery eklersiniz.

$('#myTab a').on('shown.bs.tab', function () {
  // sekme gosterildikten sonra calisir
})

// Ad cakismasi varsa eski degeri geri yukleyin
var bootstrapButton = $.fn.button.noConflict()
$.fn.bootstrapBtn = bootstrapButton

Bootstrap eklentilerini başka arayüz çatılarıyla birlikte kullanırken ad alanı çakışması yaşanabilir. Bu durumda geri almak istediğiniz eklentinin .noConflict yöntemini çağırırsınız; belge bu yöntemin yalnızca jQuery kullanıyorsanız geçerli olduğunu belirtir. Belge ayrıca Prototype veya jQuery UI gibi üçüncü taraf JavaScript kütüphanelerinin resmî olarak desteklenmediğini, .noConflict ve ad alanlı olaylara rağmen çıkabilecek uyumluluk sorunlarını sizin çözmeniz gerektiğini söyler. jQuery bağımlılığının kaldırılması v4’ten v5’e geçiş yazısında değişiklik listesinin başında yer alır.

JavaScript kapalıyken ne olur

Belge, Bootstrap eklentilerinin JavaScript devre dışıyken düzgün bir yedek davranışa geçmediğini açıkça belirtir: modal açılmaz, dropdown menüsü görünmez, carousel ilk slaytta kalır. Bu kullanıcılar sizin için önemliyse <noscript> ile durumu ve JavaScript’in nasıl yeniden açılacağını açıklayabilir ya da kendi yedek çözümlerinizi ekleyebilirsiniz:

<noscript>
  <div class="alert alert-info" role="alert">
    Menü ve açılır pencereler için tarayıcınızda JavaScript'i etkinleştirin.
  </div>
</noscript>

Yalnızca gereken JavaScript’i yüklemek

Ana dağıtım dosyaları (bootstrap.js, bootstrap.min.js) her bileşeni, bundle dosyaları ise ek olarak Popper’ı içerir. Bootstrap 5.0: Optimize sayfası, kendi paketleyicinizi kullanıyorsanız yalnızca kullandığınız eklentileri içe aktarmanızı önerir. Örneğin yalnızca modal kullanan bir proje şöyle yazar:

// Yalnizca gerekeni ice aktarin
// import 'bootstrap/js/dist/alert';
// import 'bootstrap/js/dist/carousel';
import 'bootstrap/js/dist/modal';
// import 'bootstrap/js/dist/tooltip';

// js/dist dosyalari varsayilan disa aktarim kullanir
import Modal from 'bootstrap/js/dist/modal'

const modal = new Modal(document.getElementById('myModal'))

bootstrap/js/dist içindeki dosyalar varsayılan dışa aktarım (default export) kullandığından, sınıfı yukarıdaki gibi adsız içe aktarma ile alırsınız. Dropdown, tooltip veya popover içe aktarıyorsanız Popper bağımlılığını package.json dosyanıza eklemeyi unutmayın. Sass tarafında kullanmadığınız bileşenleri çıkarırken ilgili JavaScript’i de çıkarmak tutarlı bir küçültme sağlar; Sass kısmı Sass ile özelleştirme yazısında anlatılır.

Aynı sayfa, ilk boyamada gerekmeyen betiklerin async veya defer öznitelikleriyle yüklenerek sayfanın ilk görüntülenmesini geciktirmemesini, dağıtım dosyalarında küçültülmüş .min.js sürümlerinin kullanılmasını ve bütün dosyaların HTTPS üzerinden sunulmasını önerir. Bootstrap’i defer ile yüklüyorsanız, kendi başlatma kodunuzun da Bootstrap yüklendikten sonra çalıştığından emin olun.

Sık yapılan hatalar

• bootstrap.min.js ile bootstrap.js’i birlikte yüklemek: Belge ikisini birlikte eklememenizi söyler.
• Popper eksikliği: Dropdown, tooltip ve popover için bundle kullanın ya da Popper’ı önce yükleyin.
• v4 öznitelikleri: data-toggle, data-target ve data-dismiss v5’te çalışmaz; hepsi data-bs- önekini alır.
• Başlatma kodu yazmamak: Tooltip, popover ve toast opt-in’dir; veri öznitelikleri tek başına yetmez.
• Bootstrap yüklenmeden bootstrap nesnesine erişmek: Başlatma kodunuzu Bootstrap betiğinden sonra çalıştırın; aksi hâlde tarayıcı bootstrap adının tanımlı olmadığını bildiren bir hata verir.
• jQuery varken addEventListener ile olay beklemek: jQuery tespit edildiğinde belge olayları jQuery yöntemleriyle dinlemenizi söyler; ya bunu yapın ya da data-bs-no-jquery ekleyin.
• Geçiş bitmeden ikinci yöntem çağrısı: Çağrı yok sayılır; ikinci işlemi tamamlanma olayına bağlayın.

Daha fazla belirti ve çözüm için Bootstrap çalışmıyor yazısına bakabilirsiniz.

Sık Sorulan Sorular

Bootstrap 5 jQuery gerektirir mi?

Hayır. Bootstrap 5 saf JavaScript ile çalışır. Sayfada jQuery varsa bileşenler ayrıca jQuery eklentisi olarak da kaydedilir.

getInstance ile getOrCreateInstance arasındaki fark nedir?

getInstance yalnızca var olan örneği verir, yoksa null döner. getOrCreateInstance örnek yoksa yenisini oluşturur, varsa aynısını döndürür.

Bir modalın açılmasını koşula bağlayabilir miyim?

Evet. show.bs.modal olayında event.preventDefault() çağırın; mastar biçimli bütün olaylar iptal edilebilir.

Seçenekleri hem veri özniteliği hem JavaScript ile verebilir miyim?

Her iki yol da desteklenir. Yalnızca sanitize, sanitizeFn ve allowList gibi güvenlik seçenekleri veri özniteliğiyle verilemez.

Kullandığım Bootstrap sürümünü koddan nasıl öğrenirim?

Herhangi bir eklentinin VERSION özelliğine bakın, örneğin bootstrap.Tooltip.VERSION.

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 · CDN kurulumu · Modal pencere · Tooltip ve popover · Sık hatalar · JavaScript öğrenme rehberi