Bootstrap Accordion ve Collapse: Açılır Kapanır İçerik

Collapse nasıl çalışır?

Collapse eklentisi içerik göstermek ve gizlemek için kullanılır. Düğmeler ya da bağlantılar tetikleyicidir ve belirli bir öğeyle eşleştirilir. Bir öğeyi kapatmak, onun height değerini mevcut değerinden 0 değerine canlandırır. Eklenti işini üç sınıfla yürütür:

Bu sınıfların tanımı scss/_transitions.scss dosyasındadır, çünkü hem Collapse hem accordion tarafından paylaşılır. Bootstrap'in kaynak kodundaki tanım şöyledir:

.collapse {
  &:not(.show) {
    display: none;
  }
}

.collapsing {
  height: 0;
  overflow: hidden;
  @include transition($transition-collapse);
}

Geçiş süresi scss/_variables.scss içinde $transition-collapse: height .35s ease olarak tanımlıdır. Animasyonun etkisi prefers-reduced-motion medya sorgusuna bağlıdır: kullanıcı işletim sisteminde azaltılmış hareket tercih ettiyse geçiş kapatılır. Belgelerin önemli bir uyarısı da bu yapıdan doğar: CSS animasyonları yüksekliği bu şekilde hesapladığı için .collapse öğesinin kendisine padding veremezsiniz; iç boşluk gereken içeriği .collapse öğesinin içine ayrı bir sarmalayıcı olarak koyarsınız.

Belgeler tetikleyici olarak data-bs-target taşıyan bir düğmeyi önerir. Anlamsal açıdan önerilmese de href değeri hedefi gösteren bir bağlantı da kullanılabilir; bu durumda bağlantıya role="button" eklenir. Her iki durumda da data-bs-toggle="collapse" zorunludur.

<p>
  <a class="btn btn-primary" data-bs-toggle="collapse" href="#kargoBilgi" role="button" aria-expanded="false" aria-controls="kargoBilgi">
    Bağlantıyla aç
  </a>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#kargoBilgi" aria-expanded="false" aria-controls="kargoBilgi">
    Düğmeyle aç
  </button>
</p>
<div class="collapse" id="kargoBilgi">
  <div class="card card-body">
    Siparişler iş günlerinde aynı gün kargoya verilir. Bu alan başlangıçta gizlidir ve iki tetikleyiciden biriyle açılır.
  </div>
</div>

İçerikteki .card.card-body sarmalayıcısı, iç boşluğu taşıyan ayrı öğedir; .collapse öğesi boşluksuz kalır. İki tetikleyici de aynı öğeyi açıp kapatır; biri değiştiğinde eklenti diğerinin aria-expanded değerini de günceller. Kartın kendisi Bootstrap card yazısında anlatılıyor.

Birden fazla hedef ve birden fazla tetikleyici

data-bs-target bir CSS seçicisi kabul eder. Bu yüzden tek bir tetikleyici, seçiciyle eşleşen birden fazla öğeyi aynı anda açıp kapatabilir. Tersine, birden fazla tetikleyici de aynı öğeyi hedefleyebilir. Aşağıdaki örnekte ilk iki düğme kendi panelini, üçüncü düğme ise .coklu-panel sınıfıyla eşleşen iki paneli birlikte açıp kapatır:

<p>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#panelBir" aria-expanded="false" aria-controls="panelBir">Birinci panel</button>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#panelIki" aria-expanded="false" aria-controls="panelIki">İkinci panel</button>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target=".coklu-panel" aria-expanded="false" aria-controls="panelBir panelIki">İkisi birden</button>
</p>
<div class="row">
  <div class="col">
    <div class="collapse coklu-panel" id="panelBir">
      <div class="card card-body">Birinci panelin içeriği.</div>
    </div>
  </div>
  <div class="col">
    <div class="collapse coklu-panel" id="panelIki">
      <div class="card card-body">İkinci panelin içeriği.</div>
    </div>
  </div>
</div>

.coklu-panel bir Bootstrap sınıfı değildir; yalnızca seçicinin iki paneli bulabilmesi için koyduğumuz kendi sınıf adımızdır ve hiçbir stil taşımaz. Belgelerdeki örnek aynı amaçla .multi-collapse adını kullanır. Çoklu hedefli düğmenin aria-controls değerinde iki kimlik boşlukla ayrılarak yazılır. 5.0 belgeleri yalnızca yükseklik yönünde, yani dikey açılıp kapanmayı anlatır.

Collapse ve erişilebilirlik

Belgeler tetikleyicide aria-expanded özniteliğini zorunlu sayar. Bu öznitelik, bağlı içeriğin o anki durumunu ekran okuyuculara bildirir. Kural basittir: içerik başlangıçta kapalıysa aria-expanded="false", .show ile açık başlıyorsa aria-expanded="true" yazılır. Sonrasını eklenti üstlenir; içerik ister JavaScript ile ister aynı öğeye bağlı başka bir tetikleyiciyle açılsın, değeri kendisi değiştirir. Tetikleyici bir düğme değilse (örneğin <a> ya da <div>) ona role="button" verilmelidir.

Tetikleyici tek bir öğeyi hedefliyorsa, yani data-bs-target bir kimlik seçicisiyse, aria-controls içine o öğenin kimliği yazılır; modern ekran okuyucular bu öznitelikle doğrudan içeriğe atlama kısayolu sunabilir. v5.0.2 collapse.js kaynağına göre eklenti, kapanan içeriğin tetikleyicilerine .collapsed sınıfını ekler, açılınca kaldırır; accordion düğmelerinin görünüm değiştirmesi bu sınıfa dayanır.

Belgeler bir sınırı da açıkça yazar: Bootstrap'in mevcut uygulaması, WAI-ARIA Authoring Practices 1.1 accordion deseninde tanımlanan isteğe bağlı klavye etkileşimlerini kapsamaz; bunları istiyorsanız kendi JavaScript'inizle eklemeniz gerekir. ARIA özniteliklerinin genel anlamı için ARIA rolleri ve öznitelikleri yazısına bakın.

Accordion yapısı

Accordion, Collapse eklentisini dikey olarak art arda dizilen bölümlerle birleştirir. Aşağıdaki örnek, belgelerdeki temel örneğin Türkçe bir sık sorulan sorular bölümüne uyarlanmış hâlidir:

<div class="accordion" id="sssAccordion">
  <div class="accordion-item">
    <h2 class="accordion-header" id="sssBaslikBir">
      <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#sssBir" aria-expanded="true" aria-controls="sssBir">
        Siparişim ne zaman kargoya verilir?
      </button>
    </h2>
    <div id="sssBir" class="accordion-collapse collapse show" aria-labelledby="sssBaslikBir" data-bs-parent="#sssAccordion">
      <div class="accordion-body">İş günlerinde saat 15.00'e kadar verilen siparişler aynı gün kargoya teslim edilir.</div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header" id="sssBaslikIki">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#sssIki" aria-expanded="false" aria-controls="sssIki">
        İade süresi kaç gün?
      </button>
    </h2>
    <div id="sssIki" class="accordion-collapse collapse" aria-labelledby="sssBaslikIki" data-bs-parent="#sssAccordion">
      <div class="accordion-body">İade koşulları sayfasında belirtilen süre içinde iade talebi oluşturabilirsiniz.</div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header" id="sssBaslikUc">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#sssUc" aria-expanded="false" aria-controls="sssUc">
        Hangi ödeme yöntemlerini kabul ediyorsunuz?
      </button>
    </h2>
    <div id="sssUc" class="accordion-collapse collapse" aria-labelledby="sssBaslikUc" data-bs-parent="#sssAccordion">
      <div class="accordion-body">Ödeme yöntemleri ödeme sayfasında listelenir.</div>
    </div>
  </div>
</div>

Örneği parça parça okuyalım. Her başlık bir <h2 class="accordion-header"> içindedir; sayfanızın başlık hiyerarşisine göre farklı bir başlık düzeyi seçebilirsiniz. Düğme .accordion-button taşır ve data-bs-target ile kendi panelini gösterir. Panel .accordion-collapse.collapse sınıflarını, düğmeye geri bağlanan aria-labelledby değerini ve data-bs-parent="#sssAccordion" özniteliğini taşır. Bu son öznitelik, aynı üst öğeye bağlı bir panel açıldığında diğerlerinin kapanmasını sağlar; değeri dıştaki .accordion öğesinin kimliğidir.

Küçük ama şaşırtıcı bir ayrıntı: dıştaki .accordion sınıfının v5.0.2 derlenmiş CSS dosyasında kendine ait bir kuralı yoktur. Belgelerdeki bütün örnekler onu sarmalayıcı olarak kullanır ve .accordion-flush değiştiricisi onun yanına yazılır, ama kenarlık, arka plan ve köşe yuvarlaması gibi görünümün tamamı .accordion-item, .accordion-header, .accordion-button ve .accordion-body kurallarından gelir. Sınıfı yine de yazın; hem belgelerdeki yapıya uyar hem de kendi CSS'inizle accordion'u hedeflemek için tutarlı bir kanca olur.

Başlangıçta açık olan bölüm için üç şey birlikte ayarlanır: panelde .show, düğmede .collapsed sınıfının olmaması ve aria-expanded="true". Kapalı bölümlerin düğmeleri ise .collapsed ve aria-expanded="false" taşır. Belgelerin "How it works" bölümünde açık accordion için .accordion öğesine .open sınıfı eklenmesinden söz edilir; ancak v5.0.2 derlenmiş CSS dosyasında böyle bir sınıf tanımlı değildir ve belgelerdeki örneklerin hepsi açık bölümü yukarıdaki yöntemle kurar.

Düğmenin görünümü .collapsed sınıfına göre değişir. Bootstrap 5.0.2 derlenmiş CSS dosyasında açık bölümün düğmesi şöyle tanımlıdır (kısaltıldı):

.accordion-button:not(.collapsed) {
  color: #0c63e4;
  background-color: #e7f1ff;
  box-shadow: inset 0 -1px 0 rgba(0, 0, 0, 0.125);
}
.accordion-button:not(.collapsed)::after {
  /* (kısaltıldı: ok simgesinin mavi SVG arka planı) */
  transform: rotate(-180deg);
}

Yani açık bölümün düğmesi açık mavi bir zemin ve koyu mavi yazı alır, sağdaki ok simgesi 180 derece döner. Kapalı bölüme yanlışlıkla .collapsed koymayı unutursanız düğme açık gibi görünür; bu, accordion'daki en yaygın görsel hatadır.

Flush ve hep açık varyantlar

.accordion öğesine .accordion-flush eklendiğinde varsayılan arka plan rengi, bazı kenarlıklar ve bazı yuvarlatılmış köşeler kalkar; accordion üst kapsayıcısının kenarından kenarına uzanır. Derlenmiş CSS'te bu, öğelerin sağ ve sol kenarlığının sıfırlanması, ilk öğenin üst ve son öğenin alt kenarlığının kaldırılması ve köşe yarıçapının sıfırlanmasıyla yapılır. Kart ya da yan panel içinde, çevresinde zaten çerçeve olan yerlerde kullanışlıdır.

Bölümlerin birbirinden bağımsız açılıp kapanmasını, yani birini açınca diğerinin kapanmamasını istiyorsanız her .accordion-collapse öğesinden data-bs-parent özniteliğini kaldırırsınız. Belgeler bu varyantı "always open" diye adlandırır:

<div class="accordion accordion-flush" id="ozellikListesi">
  <div class="accordion-item">
    <h2 class="accordion-header" id="ozBaslikBir">
      <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#ozBir" aria-expanded="true" aria-controls="ozBir">
        Teknik özellikler
      </button>
    </h2>
    <div id="ozBir" class="accordion-collapse collapse show" aria-labelledby="ozBaslikBir">
      <div class="accordion-body">İşlemci, bellek ve depolama bilgileri.</div>
    </div>
  </div>
  <div class="accordion-item">
    <h2 class="accordion-header" id="ozBaslikIki">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#ozIki" aria-expanded="false" aria-controls="ozIki">
        Kutu içeriği
      </button>
    </h2>
    <div id="ozIki" class="accordion-collapse collapse" aria-labelledby="ozBaslikIki">
      <div class="accordion-body">Cihaz, şarj kablosu ve kullanım kılavuzu.</div>
    </div>
  </div>
</div>

Bu örnek iki varyantı birleştirir: kenardan kenara flush görünüm ve data-bs-parent olmadığı için iki bölümün aynı anda açık kalabilmesi.

JavaScript: seçenekler ve yöntemler

Collapse veri öznitelikleriyle kendiliğinden çalışır. Elle başlatmak isterseniz belgelerdeki parça şudur:

var collapseElementList = [].slice.call(document.querySelectorAll('.collapse'))
var collapseList = collapseElementList.map(function (collapseEl) {
  return new bootstrap.Collapse(collapseEl)
})

Seçenekler veri özniteliğiyle (data-bs-parent="" gibi) ya da JavaScript ile verilir. İki seçenek vardır:

parent için belgelerdeki tablo varsayılanı false olarak gösterir, v5.0.2 collapse.js dosyasındaki Default nesnesinde ise boş dize yazar; ikisi de pratikte "üst öğe yok" anlamına gelir. toggle seçeneği daha çok dikkat ister: varsayılanı true olduğu için new bootstrap.Collapse(oge) çağrısı öğeyi hemen açar ya da kapatır. Yukarıdaki toplu başlatma parçası da bu yüzden kapalı öğeleri açar. Örneği yalnızca daha sonra kullanmak üzere oluşturmak istiyorsanız belgelerdeki gibi toggle: false verin:

var myCollapse = document.getElementById('myCollapse')
var bsCollapse = new bootstrap.Collapse(myCollapse, {
  toggle: false
})

toggle, show ve hide asenkrondur: geçiş başladığında çağırana dönerler, öğe gerçekten açılmadan ya da kapanmadan önce. Ayrıca geçiş sürerken aynı bileşene yapılan çağrılar yok sayılır; arka arkaya hızlı show ve hide çağırmak bu yüzden beklediğiniz sonucu vermez. Bitişe bağlı kodu olaylarda çalıştırın. Tüm eklentilerde ortak olan bu davranış Bootstrap JavaScript API yazısında anlatılıyor.

Collapse olayları

var myCollapsible = document.getElementById('myCollapsible')
myCollapsible.addEventListener('hidden.bs.collapse', function () {
  // do something...
})

Olaylar daraltılan öğede tetiklenir. Örneğin bir accordion bölümü açıldığında içeriğini sunucudan yüklemek ya da bir harita bileşenini yeniden boyutlandırmak istiyorsanız shown.bs.collapse doğru andır, çünkü o noktada panelin gerçek yüksekliği oluşmuştur. JavaScript tarafının temelleri için JavaScript öğrenme rehberine bakabilirsiniz.

Sass değişkenleri

Accordion'un görünümü $accordion- önekli değişkenlerle ayarlanır: iç boşluklar için $accordion-padding-y (1rem) ve $accordion-padding-x (1.25rem), kenarlık için $accordion-border-color ve $accordion-border-radius, açık düğme için $accordion-button-active-bg (tint-color($component-active-bg, 90%)) ve $accordion-button-active-color (shade-color($primary, 10%)). Ok simgesi ve dönüşü için ayrı $accordion-icon- ve $accordion-button-icon değişkenleri vardır. Collapse geçişinin süresi ise $transition-collapse ile değiştirilir. Renk fonksiyonları ve tema renkleri Bootstrap tema renkleri yazısında, değişken ezme yöntemi Bootstrap Sass yazısında anlatılıyor.

Sık yapılan hatalar

• .collapse öğesine padding verilmiş. Açılıp kapanırken içerik sıçrar. Boşluğu içteki ayrı bir öğeye verin.
• Kimlikler uyuşmuyor. data-bs-target="#sssIki" ile panelin id="sssIki" değeri; data-bs-parent="#sssAccordion" ile dış öğenin id değeri aynı olmalıdır.
• Kapalı bölümde collapsed sınıfı yok. Düğme açık bölüm gibi mavi görünür ve ok ters döner; ilk tıklamadan sonra düzelir. Başlangıç HTML'ini doğru yazın.
• aria-expanded başlangıç değeri yanlış. Açık başlayan panelin düğmesinde true, kapalılarda false olmalı.
• new bootstrap.Collapse öğeyi beklenmedik biçimde açıyor. Varsayılan toggle: true yüzündendir; toggle: false verin.
• v4 kart tabanlı accordion. Sürüm geçişi belgesine göre 5.0'da .card tabanlı accordion yerini yeni Accordion bileşenine bıraktı; eski işaretleme taşınırken yeni sınıflara çevrilmelidir. Ayrıntılar Bootstrap 4'ten 5'e geçiş yazısında.
• v4 öznitelikleri. data-toggle, data-target ve data-parent 5.0'da çalışmaz; hepsi data-bs- önekini alır.
• JavaScript yok. Collapse için Popper gerekmez, ama Bootstrap'in JavaScript dosyası gerekir. Kurulum için CDN kurulumu yazısına bakın.

Sık Sorulan Sorular

Accordion'da tüm bölümlerin kapalı başlaması mümkün mü?

Evet. Hiçbir panele .show vermeyin, tüm düğmelere .collapsed ve aria-expanded="false" yazın. Accordion bir bölümün açık olmasını zorunlu tutmaz.

Birden fazla bölüm aynı anda açık kalabilir mi?

Evet, panellerdeki data-bs-parent özniteliğini kaldırın. Bu öznitelik olmadan her bölüm kendi düğmesiyle bağımsız açılıp kapanır.

Accordion için Popper gerekir mi?

Hayır. Accordion yalnızca Collapse eklentisini kullanır; Popper açılır menüler, tooltip ve popover içindir. Bootstrap'in JavaScript dosyasının (bundle ya da normal sürüm) sayfada olması yeterlidir.

Collapse ile accordion arasındaki fark nedir?

Collapse, herhangi bir öğeyi açıp kapatan genel eklentidir; kendi görünümü yoktur. Accordion ise bu eklentiyi kullanan hazır bir bileşendir: başlık düğmesi, ok simgesi, kenarlıklar ve "aynı anda tek bölüm açık" davranışı hazır gelir. Tek bir "devamını oku" alanı için Collapse, sık sorulan sorular listesi için accordion uygundur.

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 navbar menü yapımı · Bootstrap offcanvas yan menü · Bootstrap card bileşeni · Bootstrap JavaScript API ve olaylar · Bootstrap erişilebilirlik · ARIA rolleri ve öznitelikleri