Bootstrap Çalışmıyor mu? Sık Yapılan Hatalar, Nedenleri ve Çözümleri

Hızlı teşhis tablosu

1. JavaScript yüklenmemiş, yanlış sırada ya da iki kez yüklenmiş

Giriş sayfasına göre pek çok bileşen hem Bootstrap'in kendi eklentilerine hem de Popper'a ihtiyaç duyar. Uyarıyı kapatmak, butonları açıp kapatmak, carousel, collapse, dropdown, modal, navbar'ın açılır menüsü, toast, tooltip, popover ve scrollspy JavaScript olmadan çalışmaz. Belgenin önerisi, iki seçenekten birini </body> kapanışından hemen önce eklemektir: ya Popper'ı da içeren bundle dosyası ya da önce Popper, sonra Bootstrap'in ayrı dosyası.

<!doctype html>
<html lang="tr">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
    <title>Merhaba</title>
  </head>
  <body>
    <div class="container py-4">
      <div class="dropdown">
        <button class="btn btn-secondary dropdown-toggle" type="button" id="menuDugmesi" data-bs-toggle="dropdown" aria-expanded="false">
          Menü
        </button>
        <ul class="dropdown-menu" aria-labelledby="menuDugmesi">
          <li><a class="dropdown-item" href="#">Profil</a></li>
          <li><a class="dropdown-item" href="#">Çıkış</a></li>
        </ul>
      </div>
    </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>
  </body>
</html>

Bu sayfa bir ayrıştırıcıyla denetlendi; adresler ve integrity değerleri v5.0.2 depo yapılandırmasındaki değerlerdir. Burada en sık görülen üç hata vardır. Birincisi, bootstrap.min.js dosyasını tek başına yükleyip Popper'ı unutmaktır: dropdown, tooltip ve popover belgeleri Popper'ın Bootstrap'ten önce yüklenmesi ya da bundle dosyasının kullanılması gerektiğini açıkça söyler. İkincisi, bundle dosyasının yanına ayrıca Popper ya da bootstrap.js eklemektir; JavaScript belgesi bootstrap.js ile bootstrap.min.js dosyalarının ikisini birden eklememenizi söyler. Üçüncüsü, integrity değerinin dosya sürümüyle uyuşmamasıdır; tarayıcı bu durumda dosyayı yüklemez. Kurulum ayrıntıları CDN kurulumu yazısında, integrity özniteliğinin mantığı integrity ve crossorigin yazısında.

ES modülü kullanıyorsanız bir sınırlama daha var. JavaScript belgesine göre Dropdown, Tooltip ve Popover eklentileri Popper'a bağlı oldukları için tarayıcı kısıtları yüzünden type="module" olan bir <script> etiketinde kullanılamaz. Bu bileşenler için bundle dosyasını ya da bir paketleyiciyi kullanın (npm ve paketleyici yazısı).

2. Bootstrap 4 öznitelikleri: data-toggle yerine data-bs-toggle

Geçiş belgesine göre v5'te bütün veri öznitelikleri bs ad alanına alındı. İnternette bulduğunuz bir v4 örneğini kopyaladığınızda data-toggle="collapse" yazan buton hata vermez, yalnızca hiçbir şey yapmaz. Çözüm, data-toggle, data-target, data-dismiss ve benzeri bütün öznitelikleri data-bs- önekiyle yazmaktır:

<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#detay" aria-expanded="false" aria-controls="detay">
  Ayrıntıları göster
</button>
<div class="collapse" id="detay">
  <div class="card card-body">Gizli içerik.</div>
</div>

Collapse belgesine göre hedef öğe collapse sınıfını taşımalıdır, açık başlaması için ayrıca show eklenir. JavaScript belgesi bir uyarı daha yapar: tek bir öğede yalnızca bir eklentinin veri özniteliklerini kullanın; aynı buton hem tooltip hem modal tetikleyemez. İkisine de ihtiyacınız varsa tooltip'i bir sarmalayıcı öğeye taşıyın. Sınıf tarafındaki v4 kalıntıları için 4'ten 5'e geçiş rehberine bakın.

3. Tooltip, popover ve toast başlatılmamış

Bu üç bileşenin belgelerinde aynı cümle geçer: performans nedeniyle isteğe bağlıdırlar ve onları sizin başlatmanız gerekir. data-bs-toggle="tooltip" yazmak tek başına yetmez. Belgedeki başlatma kodu sayfadaki bütün tooltip tetikleyicilerini seçip her biri için bir örnek oluşturur:

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

Toast için de aynı kalıp new bootstrap.Toast(toastEl, option) ile kullanılır; toast belgesine göre autohide: false vermezseniz toast kendiliğinden kapanır. Tooltip belgesindeki diğer kurallar da sık hata kaynağıdır: başlığı boş olan tooltip hiç gösterilmez, gizli öğelerde tetiklenmez ve öğe DOM'dan kaldırılmadan önce tooltip gizlenmelidir. Devre dışı bir butonda tooltip istiyorsanız, belgeye göre tooltip'i odaklanabilir bir sarmalayıcıya koymanız gerekir, çünkü disabled öğeler fare ve klavye etkileşimi almaz:

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

Tooltip ve popover ayrıntıları tooltip ve popover yazısında, toast toast yazısında anlatılıyor.

4. Viewport meta etiketi ve doctype eksik

Giriş sayfasına göre Bootstrap mobil öncelikli geliştirilmiştir ve doğru görüntü ile dokunarak yakınlaştırma için <meta name="viewport" content="width=device-width, initial-scale=1"> etiketinin <head> içinde olması gerekir. Bu etiket yoksa mobil tarayıcı sayfayı geniş bir masaüstü sayfası gibi çizip küçültür; col-md-6 gibi sınıflar telefonda da masaüstündeki gibi davranır ve duyarlı tasarım bozulmuş görünür. Belge ayrıca HTML5 doctype'ının zorunlu olduğunu, olmadığında eksik ve garip stiller göreceğinizi belirtir. Kavramın kendisi için mobil uyumluluk yazısına bakın.

5. Izgara: row dışında col, container eksik

Grid belgesine göre satırlar sütunların sarmalayıcısıdır: her sütunun yatay iç boşluğu (gutter) vardır ve bu boşluk satırdaki negatif margin ile dengelenir. .col-* sınıfını bir .row öğesinin doğrudan çocuğu olmayan bir öğeye verirseniz, sütunlar belgesine göre sınıf yalnızca genişlik verir ve iç boşluklar uygulanmaz. Satırı bir kapsayıcı olmadan kullandığınızda da negatif margin içeriği sayfa kenarına taşıyabilir. Doğru yapı kapsayıcı, satır ve sütun sırasıdır:

<div class="container">
  <div class="row">
    <div class="col-md-8">Ana içerik</div>
    <div class="col-md-4">Kenar çubuğu</div>
  </div>
</div>

Kırılma noktaları en küçük genişlikten (min-width) başlayarak çalışır: col-md-8 md ve üzerinde geçerlidir, daha dar ekranda sütunlar tam genişlikte alt alta durur. Bunu "md'de çalışmıyor" diye yorumlamak yaygın bir yanılgıdır. Ayrıntılar grid, container ve breakpoint yazılarında.

6. Var olmayan sınıflar ve sürüm farkı

Bootstrap sınıfları HTML'de yanlış yazıldığında hiçbir uyarı çıkmaz; tarayıcı tanımadığı sınıfı görmezden gelir. En sık iki kaynak vardır. Birincisi v4 adlarıdır: ml-3, pr-2, text-left, float-right, form-group, btn-block, badge-primary, sr-only, close. Bunların hiçbiri v5.0.2 derlenmiş CSS dosyasında yoktur. İkincisi, daha yeni bir 5.x sürümünün belgesinden alınmış örneğin 5.0 dosyasıyla kullanılmasıdır; yeni sürümlerde eklenen sınıflar eski dosyada bulunmaz. Kendinizi korumanın yolu, sayfada hangi Bootstrap sürümünü yüklediğinizi bilmek ve o sürümün belgesine bakmaktır. Şüphelendiğiniz bir sınıfı, yüklediğiniz CSS dosyasında aramak en hızlı kontroldür.

Benzer bir durum negatif margin sınıflarında yaşanır. Boşluk belgesine göre mt-n1 gibi sınıflar varsayılan olarak kapalıdır ve stok CSS'te yer almaz; yalnızca Sass ile $enable-negative-margins: true derlediğinizde oluşur (seçenekler yazısı).

7. Kendi CSS kuralınız işlemiyor

Utilities API belgesine göre API'nin ürettiği bütün yardımcı sınıflar !important taşır; örneğin derlenmiş CSS'te .d-none kuralı display: none !important; şeklindedir. Bu yüzden d-none taşıyan bir öğeyi kendi stil dosyanızdaki bir kuralla göstermeye çalışırsanız başaramazsınız. Çözüm, sınıfı HTML'den kaldırmak ya da d-none d-md-block gibi duyarlı bir display birleşimi kullanmaktır (display yazısı).

Bootstrap'in kendi bileşen kurallarını ezmek isterken de sıra önemlidir: giriş sayfası Bootstrap CSS bağlantısını diğer bütün stil dosyalarından önce eklemenizi söyler. Kendi dosyanız Bootstrap'ten önce yüklenirse eşit özgüllükteki kurallarda Bootstrap kazanır. Özgüllük kavramı için CSS öğrenme rehberine bakabilirsiniz. Renkleri derlemeden değiştirmek için --bs-primary gibi değişkenleri değiştirmek de bileşenleri etkilemez, çünkü bileşenler sabit renk kodlarıyla derlenmiştir; doğru yol Sass'tır (Sass ile özelleştirme).

8. Modal, z-index ve katmanlar

Modal belgesi birkaç kesin kural koyar. Bootstrap aynı anda yalnızca bir modal penceresini destekler; iç içe modaller desteklenmez. Modaller position: fixed kullandığı için HTML'lerini mümkün olduğunca sayfanın üst düzeyine koymanız gerekir; sabit konumlu başka bir öğenin içine yerleştirilen modal sorun çıkarır. HTML'deki autofocus özniteliği modal içinde etkisizdir; belge bunun yerine shown.bs.modal olayında alana odak vermeyi önerir:

var myModal = document.getElementById('myModal')
var myInput = document.getElementById('myInput')

myModal.addEventListener('shown.bs.modal', function () {
  myInput.focus()
})

Katman sorunlarında Bootstrap'in sabit z-index ölçeğini bilmek işe yarar. v5.0.2'de değerler şöyledir: dropdown 1000, sticky 1020, fixed 1030, modal arka planı 1040, offcanvas 1050, modal 1060, popover 1070, tooltip 1080. Z-index belgesi bu değerleri tek tek değiştirmeyi önermez, birini değiştirirseniz muhtemelen hepsini değiştirmeniz gerektiğini söyler. Kendi sabit başlığınız modalın üstünde kalıyorsa, ona 1060'tan büyük bir değer verip vermediğinizi kontrol edin. Ayrıca tarayıcılar sayfası, iOS ve Android'de <body> üzerindeki overflow: hidden desteğinin sınırlı olduğunu, bu yüzden modalın üst ya da alt sınırını geçerek kaydırıldığında arka plandaki sayfanın da kayabileceğini belirtir. Ayrıntılar modal ve position ve z-index yazılarında.

9. Olaylar ve yöntemler beklendiği gibi çalışmıyor

JavaScript belgesine göre programatik API yöntemlerinin hepsi eşzamansızdır: geçiş başladığı anda geri döner, bittiğinde değil. Geçiş sürerken aynı bileşende çağrılan ikinci yöntem yok sayılır. Belgedeki örnekte carousel birinci slayda giderken hemen ardından carousel.to('2') çağrılırsa bu çağrı görmezden gelinir. Bir işi geçiş bittikten sonra yapmak için shown.bs.collapse ya da slid.bs.carousel gibi geçmiş zaman olaylarını dinleyin.

Sayfada jQuery yüklüyse bir tuzak daha var: belgeye göre Bootstrap window üzerinde jQuery bulursa (ve <body> üzerinde data-bs-no-jquery özniteliği yoksa) olayları jQuery'nin olay sistemiyle yayar. Bu durumda olayları addEventListener yerine jQuery'nin .on yöntemiyle dinlemeniz gerekir. Belge ayrıca Bootstrap'in öğeleri querySelector ile bulduğunu, bu yüzden data-bs-target gibi değerlerin geçerli CSS seçicisi olması ve özel karakterlerin kaçışlanması gerektiğini hatırlatır. Olay ve yöntem listesi JavaScript API yazısında.

10. Üçüncü taraf bileşenlerle çakışma

Giriş sayfası, Bootstrap'in genel box-sizing değerini border-box yaptığını ve bunun Google Maps ya da Google Custom Search Engine gibi bazı üçüncü taraf yazılımlarda sorun çıkarabileceğini söyler. Böyle bir bileşenin düzeni bozuluyorsa, onu saran öğe için box-sizing: content-box; kuralını yazmak iç öğelerin de bu değeri almasını sağlar. JavaScript tarafında ise belge, Prototype ya da jQuery UI gibi üçüncü taraf kütüphanelerin resmî olarak desteklenmediğini, çakışmaları sizin çözmeniz gerekebileceğini belirtir. JavaScript kapalıyken de eklentilerin özel bir yedek davranışı yoktur; bu durumu önemsiyorsanız <noscript> ile kullanıcıyı bilgilendirin.

Sık Sorulan Sorular

Konsolda "bootstrap is not defined" hatası alıyorum, neden?

Kodunuz Bootstrap'in JavaScript dosyası yüklenmeden çalışıyordur ya da dosya hiç yüklenmemiştir. Kendi betiğinizi Bootstrap'in <script> etiketinden sonra koyun ve ağ sekmesinde dosyanın başarıyla indirildiğini kontrol edin. Bir paketleyici kullanıyorsanız bootstrap/js/dist dosyaları varsayılan dışa aktarım kullanır; sınıfı içe aktarıp kullanmanız gerekir.

Navbar menüsü küçük ekranda açılmıyor, neden?

Navbar'ın açılır menüsü Collapse eklentisine dayanır. JavaScript dosyasının yüklü olduğundan, açma butonunun data-bs-toggle="collapse" ve doğru data-bs-target değerini taşıdığından emin olun. Yapı için navbar yazısına bakın.

Dropdown navbar içinde farklı konumlanıyor, hata mı?

Hayır. Dropdown belgesine göre navbar içindeki dropdown'lar dinamik konumlandırma gerektirmediği için Popper ile konumlandırılmaz. Ayrıntı dropdown yazısında.

Formum doğrulama renklerini göstermiyor, neden?

Bootstrap'in doğrulama stilleri .was-validated ya da .is-invalid gibi sınıflara bağlıdır ve bu sınıfları sizin JavaScript ile eklemeniz gerekir. Kurulum form doğrulama yazısında.

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 4'ten 5'e geçiş · CDN kurulumu · JavaScript API · Tooltip ve popover · JavaScript öğrenme rehberi