Bootstrap 4'ten 5'e Geçiş Rehberi: jQuery, data-bs, Sınıf Adları ve Formlar

Bağımlılıklar ve tarayıcı desteği

Geçiş belgesinin ilk bölümü bağımlılıklardır: jQuery bırakıldı ve eklentiler düz JavaScript ile yeniden yazıldı, Popper 1.x'ten 2.x'e yükseltildi, Sass derleyicisi olarak kullanımdan kalkan Libsass yerine Dart Sass'a geçildi. Dokümantasyon da Jekyll yerine Hugo ile üretilmeye başlandı; bu sizin projenizi etkilemez ama belge kaynaklarını incelerken farkı görürsünüz.

Tarayıcı tarafında v5; Internet Explorer 10 ve 11'i, 16'dan eski (Legacy) Edge'i, 60'tan eski Firefox ve Chrome'u, 12'den eski Safari ve iOS Safari'yi desteklemeyi bıraktı. Tarayıcılar sayfası bunu açık bir cümleyle söyler: Internet Explorer desteğine ihtiyacınız varsa Bootstrap 4 kullanmalısınız. Kullanıcılarınızın önemli bir kısmı eski tarayıcılardaysa geçişi bu bilgiye göre planlayın. Desteklenen aralık depodaki .browserslistrc dosyasında tanımlıdır.

JavaScript: jQuery yok, öznitelikler bs- önekli

JavaScript tarafındaki en büyük kırıcı değişiklik veri öznitelikleridir. Bootstrap işlevlerini üçüncü taraf kodlardan ve sizin kendi kodunuzdan ayırmak için bütün öznitelikler bir ad alanına alındı: data-toggle artık data-bs-toggle, data-target artık data-bs-target'dır. v4 özniteliğiyle kalan bir buton hata vermez, yalnızca hiçbir şey yapmaz; bu yüzden geçişte projenizde data-toggle, data-target, data-dismiss, data-ride, data-parent, data-spy gibi öznitelikleri arayıp hepsine bs- eklemek ilk iş olmalıdır.

Programatik API'de de değişiklikler var. Belgeye göre bütün eklentiler artık ilk argüman olarak bir DOM öğesi yerine CSS seçici de kabul eder, genel statik yöntemlerin başındaki alt çizgi kaldırıldı (_getInstance() yerine getInstance()) ve dropdown, popover ve tooltip için popperConfig seçeneği, Bootstrap'in varsayılan Popper ayarını alan bir fonksiyon olarak da verilebilir. Aynı üç bileşende fallbackPlacements varsayılanı ['top', 'right', 'bottom', 'left'] oldu.

var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')

jQuery'yi tamamen bırakamıyorsanız JavaScript belgesi bir geçiş kolaylığı tanır: window nesnesinde jQuery bulunursa Bootstrap bileşenlerini jQuery eklenti sistemine de ekler ve $('[data-bs-toggle="tooltip"]').tooltip() gibi çağrılar çalışır. Bu durumda olaylar da jQuery üzerinden yayılır. Programatik API'nin ayrıntıları JavaScript API yazısında.

Yardımcı sınıflar: mantıksal adlar

Sağdan sola dil desteği eklendiği için yöne bağlı adlar start ve end kavramlarına çevrildi. Bu, geçişte en çok satıra dokunduğunuz değişiklik olacaktır. Belgedeki yeniden adlandırmalar şunlardır:

Bunların yanında bazı sınıflar tamamen kalktı: .text-hide, .text-justify ve .pre-scrollable. Negatif margin sınıfları varsayılan olarak kapatıldı (açmak için $enable-negative-margins). .text-* renk sınıfları artık bağlantılara üzerine gelme ve odak durumu eklemiyor; bunun için yeni .link-* sınıfları var. Yeni gelenler arasında .bg-body, .d-grid ve gap sınıfları, .translate-middle-x ve .translate-middle-y, kenar kalınlığı sınıfları, .fs-* yazı boyutları ve .lh-1, .lh-sm, .lh-base, .lh-lg satır yüksekliği sınıfları bulunur. Utilities API ile eski ml-* adlarını geri üretmek mümkündür (Utilities API yazısı), ancak uzun vadede yeni adlara geçmek daha az kafa karıştırır.

Izgara ve yerleşim

• Yeni xxl kırılma noktası eklendi (1400px ve üzeri); diğer kırılma noktaları değişmedi.
• Gutter değerleri rem birimine geçti ve daraldı: v4'teki 30px yerine 1.5rem. Yeni .g-*, .gx-*, .gy-* sınıfları geldi.
• Sütunlar artık position: relative almıyor; konumlandırma için bazı öğelere .position-relative eklemeniz gerekebilir.
• Sıralama sınıfları .order-1 ile .order-5 arasıyla sınırlandı.
• .media bileşeni kaldırıldı; aynı düzen flex yardımcılarıyla kurulur.
• bootstrap-grid.css genel box-sizing değerini sıfırlamıyor, yalnızca sütunlara uyguluyor.
• make-col mixin'i boyut verilmezse eşit sütun üretir.

Kaldırılan media bileşeninin yerine belgedeki flex yardımcıları önerisi şöyledir; görsel tarafı flex-shrink-0 ile küçülmez, metin tarafı flex-grow-1 ile kalan alanı doldurur:

<div class="d-flex">
  <div class="flex-shrink-0">
    <img src="avatar.png" alt="Kullanıcı görseli" width="64" height="64">
  </div>
  <div class="flex-grow-1 ms-3">
    Yorum metni burada yer alır.
  </div>
</div>

Izgaranın kendisi için grid yazısına, gutter sınıfları için gutter yazısına, flex sınıfları için flex yazısına bakın.

İçerik, tipografi ve tablolar

Geçiş belgesine göre RFS artık varsayılan olarak açık; font-size() mixin'iyle yazılan başlıklar ekran genişliğine göre ölçeklenir. Display başlıkları için ayrı $display-* değişkenleri yerine $display-font-sizes map'i geldi ve .display-5 ile .display-6 eklendi. Bağlantılar artık yalnızca üzerine gelince değil, varsayılan olarak altı çizili gösteriliyor. <ul> ve <ol> öğelerinin sol iç boşluğu tarayıcının 40px varsayılanı yerine 2rem oldu.

Tablolar CSS değişkenleriyle yeniden yazıldı ve iç içe tablolar artık üst tablonun stilini miras almıyor. .thead-light ve .thead-dark kaldırıldı; onların yerine thead, tbody, tr, td gibi her tablo öğesinde kullanılabilen .table-* renk sınıfları var. Ayrıntılar tipografi ve tablo yazılarında.

Formlar

Formlar geçişte ikinci büyük iş kalemidir. v4'te yerel ve özel (custom) olarak iki ayrı sınıf ailesi taşıyan onay kutusu, radyo, select ve diğer alanlar birleştirildi:

Bunlara ek olarak etiketler artık .form-label sınıfı istiyor, .form-text kendi başına display ayarlamıyor, doğrulama içeren input grupları için .has-validation sınıfı eklendi ve floating label örneği tam desteklenen bir bileşene dönüştü. Çoklu seçimli <select> öğelerinde doğrulama simgesi artık gösterilmiyor. Ayrıntılar form kontrolleri, checkbox ve select, input group ve form düzeni yazılarında.

Bileşenler: kaldırılanlar, yeniden adlandırılanlar, yeniler

Jumbotron'un yerine resmî örnek şablonlar arasındaki jumbotron örneği, p-5 mb-4 bg-light rounded-3 gibi yardımcı sınıflarla aynı görünümü kurar. Buton ve kart değişiklikleri için buton ve kart yazılarına, yeni bileşenler için accordion ve offcanvas yazılarına bakın.

Yardımcılar (helpers)

İki yardımcı ailesinin adı değişti. Duyarlı gömme yardımcıları oran (ratio) yardımcılarına dönüştü: .embed-responsive-16by9 yerine .ratio ve .ratio-16x9 kullanılıyor, .embed-responsive-item sınıfı gerekmiyor ve özel oranlar --bs-aspect-ratio değişkeniyle veriliyor. Ekran okuyucu sınıfları da "görsel olarak gizli" adını aldı: .sr-only yerine .visually-hidden, .sr-only-focusable yerine .visually-hidden-focusable. Ayrıntılar görsel ve ratio ile erişilebilirlik yazılarında.

Sass tarafındaki kırıcı değişiklikler

Kendi Sass dosyalarınızı derliyorsanız şu değişiklikler derleme hatasına ya da beklenmedik çıktıya yol açabilir:

• color-yiq() fonksiyonu color-contrast() oldu; $yiq-contrasted-threshold yerine $min-contrast-ratio, $yiq-text-dark ve $yiq-text-light yerine $color-contrast-dark ve $color-contrast-light geldi.
• color(), theme-color() ve gray() fonksiyonları kaldırıldı; değişkenleri doğrudan kullanın.
• lighten() ve darken() kullanımları tint-color() ve shade-color() ile, scale-color() ise shift-color() ile değiştirildi.
• Varsayılan map birleştirmeleri kaldırıldı; $theme-colors gibi map'leri yeniden tanımlarsanız bütün değerleri yazmalısınız.
• $enable-print-styles ve yazdırma stilleri kaldırıldı; yazdırma display sınıfları duruyor.
• $enable-prefers-reduced-motion-media-query ve $enable-pointer-cursor-for-buttons sırasıyla $enable-reduced-motion ve $enable-button-pointers oldu.
• hover, float(), visibility(), text-hide() gibi daha önce kullanımdan kaldırılmış mixin'ler silindi.

En sinsi değişiklik medya sorgusu mixin'lerinin parametre anlamıdır. v5'te media-breakpoint-down() bir sonraki kırılma noktasını değil, verilen kırılma noktasının kendisini alır. Belgedeki örneğe göre lg altını hedeflemek için v4'te md yazılırken v5'te lg yazılır. Aynı mantık media-breakpoint-between() mixin'inin ikinci parametresi için de geçerlidir. Kod hata vermeden derlendiği için bu değişikliği gözden kaçırmak kolaydır:

// Bootstrap 4: lg altındaki ekranlar
@include media-breakpoint-down(md) { ... }

// Bootstrap 5: lg altındaki ekranlar
@include media-breakpoint-down(lg) { ... }

Renk sisteminde de değişiklik var: kontrast oranı 3:1'den 4.5:1'e çıkarıldı ve her temel renk için dokuz ton değişken olarak eklendi. Sass yapısı Sass yazısında, renk değişiklikleri tema renkleri yazısında.

Uygulamalı örnek: bir kart ve form parçasını taşımak

Aşağıdaki v4 parçası tipik bir fiyat kartı ve iki form alanı içerir. Bu kodu bu serideki denetleyiciyle v5.0.2 CSS dosyasına karşı kontrol ettiğimizde şu sınıfların stok CSS'te bulunmadığı bildirildi: badge-pill, badge-primary, btn-block, card-deck, custom-control, custom-control-input, custom-control-label, custom-switch, form-group, ml-2 ve text-left. Ayrıca butondaki data-toggle ve data-target öznitelikleri v5'te hiçbir şey yapmaz.

<div class="card-deck">
  <div class="card">
    <div class="card-body">
      <h5 class="card-title">Başlangıç <span class="badge badge-pill badge-primary ml-2">Yeni</span></h5>
      <p class="card-text text-left">Küçük siteler için.</p>
      <button type="button" class="btn btn-primary btn-block" data-toggle="modal" data-target="#siparis">Seç</button>
    </div>
  </div>
</div>
<div class="form-group">
  <label for="eposta">E-posta</label>
  <input type="email" class="form-control" id="eposta">
</div>
<div class="custom-control custom-switch">
  <input type="checkbox" class="custom-control-input" id="bulten">
  <label class="custom-control-label" for="bulten">Bülten</label>
</div>

Aynı parçanın v5 karşılığında kart destesi yerine row-cols-* ızgarası, rozet için rounded-pill ve bg-primary, tam genişlik buton için d-grid sarmalayıcısı, form grubu yerine mb-3, özel anahtar yerine form-check form-switch kullanılır. Bu sürüm aynı denetleyiciden hatasız geçti:

<div class="row row-cols-1 row-cols-md-3 g-4">
  <div class="col">
    <div class="card h-100">
      <div class="card-body">
        <h5 class="card-title">Başlangıç <span class="badge rounded-pill bg-primary ms-2">Yeni</span></h5>
        <p class="card-text text-start">Küçük siteler için.</p>
        <div class="d-grid">
          <button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#siparis">Seç</button>
        </div>
      </div>
    </div>
  </div>
</div>
<div class="mb-3">
  <label for="eposta" class="form-label">E-posta</label>
  <input type="email" class="form-control" id="eposta">
</div>
<div class="form-check form-switch">
  <input class="form-check-input" type="checkbox" id="bulten">
  <label class="form-check-label" for="bulten">Bülten</label>
</div>

Örnekteki data-bs-target="#siparis" sayfada o kimliğe sahip bir modal olduğunu varsayar; modal yapısı için modal yazısına bakın.

Adım adım geçiş planı

• 1. Bağımlılıklar: jQuery'ye yalnızca Bootstrap için ihtiyacınız varsa kaldırın, Popper 2'yi ya da Popper içeren bundle dosyasını yükleyin. CDN ve dosya seçimi için kurulum yazısı.
• 2. Öznitelikler: projede data-toggle, data-target, data-dismiss gibi öznitelikleri arayıp data-bs- önekine çevirin.
• 3. Yardımcı sınıflar: yukarıdaki tabloya göre ml-, mr-, pl-, pr-, left, right içeren sınıfları değiştirin.
• 4. Formlar: .form-group, .form-row, .custom-* ve input group eklerini yeni yapıya taşıyın, etiketlere .form-label ekleyin.
• 5. Bileşenler: jumbotron, card-deck, media, btn-block, badge renkleri ve close butonu gibi kaldırılan parçaları yeniden kurun; navbar içine container ekleyin.
• 6. Sass: fonksiyon ve değişken adlarını güncelleyin, media-breakpoint-down() çağrılarını tek tek kontrol edin.
• 7. Kontrol: sayfalarınızda kullandığınız sınıfları derlenmiş v5 CSS dosyasında arayın; bulunmayan her ad bir taşıma eksiğidir.

Geçişten sonra karşılaşılan tipik belirtiler ve çözümleri sık hatalar yazısında toplu hâlde duruyor.

Sık Sorulan Sorular

Bootstrap 5 jQuery ile çalışır mı?

Bootstrap 5 jQuery'ye ihtiyaç duymaz. Sayfada jQuery varsa Bootstrap bileşenlerini jQuery eklentisi olarak da kaydeder, ama bu zorunlu değildir ve eklentiler düz JavaScript ile çalışır.

Eski data-toggle öznitelikleri neden hata vermiyor?

Bootstrap 5 yalnızca data-bs- önekli öznitelikleri arar. Eski öznitelikler geçerli HTML olduğu için tarayıcı hata göstermez; Bootstrap da onları görmezden gelir. Sonuç, tıklandığında hiçbir şey yapmayan bir butondur.

Internet Explorer kullanıcılarım varsa ne yapmalıyım?

Belgeye göre Bootstrap 5 Internet Explorer'ı desteklemez ve IE desteği gereken projeler için Bootstrap 4 önerilir.

ml-3 gibi eski sınıfları geri getirebilir miyim?

Utilities API ile margin-start grubunun sınıf önekini ml yaparak üretebilirsiniz; belge bu örneği gösterir. Ancak bu, takımınızın v5 belgeleriyle uyumsuz bir adlandırma kullanması demektir.

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 sık hatalar · Utilities API · Form kontrolleri · JavaScript API · HTML öğrenme rehberi