Bootstrap Offcanvas: Kenardan Açılan Yan Menü

Offcanvas nasıl çalışır?

Offcanvas, görünür alanın solundan, sağından, üstünden veya altından açılan, JavaScript ile gösterilip gizlenen bir kenar paneli bileşenidir. Gezinme menüsü, alışveriş sepeti, filtre paneli gibi işler için tasarlanmıştır. Belgelerin bileşen hakkında sıraladığı temel bilgiler şunlardır:

• Offcanvas, modal bileşeniyle bazı JavaScript kodlarını paylaşır. Kavram olarak birbirlerine çok benzerler, ama ayrı eklentilerdir.
• Offcanvas'ın stil ve ölçülerini belirleyen bazı Sass değişkenleri modal değişkenlerinden türetilir.
• Açıldığında varsayılan olarak bir arka perde (backdrop) gösterir; perdeye tıklamak paneli kapatır.
• Modallarda olduğu gibi aynı anda yalnızca bir offcanvas gösterilebilir.
• Animasyonun etkisi prefers-reduced-motion medya sorgusuna bağlıdır; azaltılmış hareket tercih eden kullanıcılarda geçiş kapanır.

Belgelerin bir uyarısı da var: CSS animasyonları nasıl işlediği için .offcanvas öğesine margin ya da translate uygulayamazsınız. Bu sınıfı bağımsız bir sarmalayıcı olarak kullanın, boşluk ve konum ayarlarını içerideki öğelere verin. Nedeni derlenmiş CSS'te görülür; Bootstrap 5.0.2 derlenmiş CSS dosyasında temel kural ve yerleşimlerden biri şöyle tanımlıdır:

.offcanvas {
  position: fixed;
  bottom: 0;
  z-index: 1050;
  display: flex;
  flex-direction: column;
  max-width: 100%;
  visibility: hidden;
  background-color: #fff;
  background-clip: padding-box;
  outline: 0;
  transition: transform 0.3s ease-in-out;
}
/* (kısaltıldı) */
.offcanvas-start {
  top: 0;
  left: 0;
  width: 400px;
  border-right: 1px solid rgba(0, 0, 0, 0.2);
  transform: translateX(-100%);
}

.offcanvas.show {
  transform: none;
}

Panel sabit konumludur ve transform ile ekranın dışına itilmiş hâlde bekler; .show sınıfı gelince transform: none ile yerine kayar. Kendi translate değerinizi verirseniz bu mekanizmayı bozarsınız. z-index: 1050 değeri Sass'taki $zindex-offcanvas değişkeninden gelir ve sabit navbar'ın (1030) ve modal arka perdesinin (1040) üstündedir. Katman sırası Bootstrap position yazısında anlatılıyor.

Temel offcanvas örneği

Offcanvas bir başlık, bir kapatma düğmesi ve isteğe bağlı bir gövdeden oluşur. .offcanvas-header başlıkla kapatma düğmesini iki uca yerleştirir, .offcanvas-body içeriğe başlangıç iç boşluğu verir ve taşan içerikte dikey kaydırma sağlar. Belgeler mümkün olduğunda kapatma eylemi içeren bir başlık ya da açık bir kapatma eylemi eklemenizi önerir. Aşağıdaki örnekte biri bağlantı, biri düğme olan iki tetikleyici aynı paneli açar:

<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#filtrePanel" role="button" aria-controls="filtrePanel">
  Bağlantıyla aç
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#filtrePanel" aria-controls="filtrePanel">
  Düğmeyle aç
</button>

<div class="offcanvas offcanvas-start" tabindex="-1" id="filtrePanel" aria-labelledby="filtrePanelBaslik">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="filtrePanelBaslik">Filtreler</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Kapat"></button>
  </div>
  <div class="offcanvas-body">
    <p>Ürünleri fiyata ve markaya göre süzün.</p>
    <div class="dropdown mt-3">
      <button class="btn btn-secondary dropdown-toggle" type="button" id="siralamaMenu" data-bs-toggle="dropdown" aria-expanded="false">
        Sıralama
      </button>
      <ul class="dropdown-menu" aria-labelledby="siralamaMenu">
        <li><a class="dropdown-item" href="#">Artan fiyat</a></li>
        <li><a class="dropdown-item" href="#">Azalan fiyat</a></li>
      </ul>
    </div>
  </div>
</div>

Bağlantı tetikleyicide hedef href ile, düğme tetikleyicide data-bs-target ile verilir; ikisinde de data-bs-toggle="offcanvas" zorunludur. Kapatma düğmesi .btn-close sınıflı boş bir düğmedir; görünür metni olmadığı için aria-label ile adlandırılır. Belgeler kapatma düğmesi için cihazlar arasında doğru davranış göstermesi adına <button> öğesi kullanmanızı ister. Kapatma düğmesinin kendisi Bootstrap buton yazısında, panel içindeki açılır menü ise dropdown yazısında anlatılıyor.

Belgelerdeki ilk örnek paneli .show sınıfıyla başlangıçta açık gösterir. v5.0.2 offcanvas.js kaynağına göre sayfa yüklendiğinde .show taşıyan offcanvas öğeleri için eklenti bir örnek oluşturup paneli gösterir; yani .show ile başlayan panel arka perdesi ve davranışlarıyla birlikte açık gelir.

Dört yerleşim seçeneği

Offcanvas'ın varsayılan bir yerleşimi yoktur; aşağıdaki değiştirici sınıflardan birini eklemeniz gerekir. Yerleşim sınıfı olmadan panel ekranın dışına itilmez ve beklediğiniz kayma hareketi oluşmaz. Derlenmiş CSS'teki ölçüler şöyledir:

Yan panellerin 400 piksellik genişliği max-width: 100% ile sınırlandığı için dar bir telefon ekranında panel ekranın tamamını kaplar. Üst ve alt paneller görünür alan yüksekliğinin yüzde 30'u kadardır; içerik fazlaysa .offcanvas-body kendi içinde kayar. Bu ölçüler Sass'taki $offcanvas-horizontal-width ve $offcanvas-vertical-height değişkenlerinden gelir. Aşağıdaki örnek sağdan açılan bir sepet panelidir:

<button class="btn btn-outline-dark" type="button" data-bs-toggle="offcanvas" data-bs-target="#sepetPanel" aria-controls="sepetPanel">Sepetim (2)</button>

<div class="offcanvas offcanvas-end" tabindex="-1" id="sepetPanel" aria-labelledby="sepetBaslik">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="sepetBaslik">Sepetiniz</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Kapat"></button>
  </div>
  <div class="offcanvas-body">
    <ul class="list-group mb-3">
      <li class="list-group-item d-flex justify-content-between">Kablosuz klavye <span>1 adet</span></li>
      <li class="list-group-item d-flex justify-content-between">USB-C kablo <span>2 adet</span></li>
    </ul>
    <a class="btn btn-primary w-100" href="#">Ödemeye geç</a>
  </div>
</div>

Panelin içinde Bootstrap'in diğer bileşenlerini serbestçe kullanabilirsiniz; bu örnekte ürünler bir liste grubunda, ödeme bağlantısı ise w-100 ile tam genişlikte bir düğme olarak duruyor. Liste grubu Bootstrap list group yazısında anlatılıyor.

Arka perde ve sayfa kaydırma

Offcanvas ve arka perdesi görünürken <body> öğesinin kaydırılması kapatılır. Bu davranışı iki veri özniteliğiyle değiştirirsiniz: data-bs-scroll sayfa kaydırmayı açar ya da kapatır, data-bs-backdrop arka perdeyi açar ya da kapatır. Öznitelikler tetikleyiciye değil, .offcanvas öğesinin kendisine yazılır. Belgelerdeki üç birleşim şöyledir:

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#notPanel" aria-controls="notPanel">Not paneli</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="notPanel" aria-labelledby="notPanelBaslik">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="notPanelBaslik">Notlarım</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Kapat"></button>
  </div>
  <div class="offcanvas-body">
    <p>Panel açıkken sayfanın geri kalanını kaydırmaya devam edebilirsiniz.</p>
  </div>
</div>

Arka perdesiz ve kaydırmalı bu düzen, kullanıcının sayfayı okurken yan tarafta bir araç paneli açık tutması gereken durumlar için uygundur. Arka perde yokken panel dışına tıklamak onu kapatmaz; kapatma düğmesi ve Esc tuşu çalışmaya devam eder.

Odak, klavye ve erişilebilirlik

Belgelere göre offcanvas paneli kavram olarak bir modal iletişim kutusudur. Bu yüzden .offcanvas öğesine panel başlığını gösteren bir aria-labelledby eklemelisiniz. role="dialog" eklemeniz gerekmez, çünkü Bootstrap bunu JavaScript ile kendisi ekler. v5.0.2 offcanvas.js kaynağı ayrıntıyı gösterir: panel açılırken aria-hidden kaldırılır, aria-modal="true" ve role="dialog" eklenir; kapanırken bu iki öznitelik geri alınır.

Aynı kaynaktan okunabilen diğer davranışlar şunlardır:

• scroll seçeneği kapalıyken (varsayılan) panel açılınca odak panele taşınır ve odak panelin dışına çıkmaya çalıştığında yeniden panele döndürülür. Böylece klavye kullanıcısı arkadaki sayfada kaybolmaz.
• keyboard seçeneği açıkken (varsayılan) Esc tuşu paneli kapatır.
• Panel bir veri öznitelikli tetikleyiciyle açıldıysa, kapandıktan sonra odak, görünür olduğu sürece o tetikleyiciye geri verilir.
• Bir offcanvas açıkken başka bir offcanvas'ın tetikleyicisine tıklanırsa önce açık olan gizlenir; böylece aynı anda tek panel kuralı korunur.

Örneklerdeki tabindex="-1", paneli sekme sırasına sokmadan programatik olarak odaklanabilir yapar; eklentinin paneli odaklayabilmesi buna dayanır. ARIA özniteliklerinin anlamı için ARIA rolleri ve öznitelikleri yazısına, Bootstrap'in genel erişilebilirlik yaklaşımı için Bootstrap erişilebilirlik yazısına bakabilirsiniz.

Seçenekler, yöntemler ve olaylar

Seçenekler veri öznitelikleriyle (data-bs-backdrop="" gibi) ya da JavaScript ile verilir. Varsayılanlar belgelerdeki tabloyla v5.0.2 kaynağındaki Default nesnesinde aynıdır:

Veri öznitelikli tetikleyiciler kendiliğinden çalışır. Panelleri koddan başlatmak için belgelerdeki parça şudur:

var offcanvasElementList = [].slice.call(document.querySelectorAll('.offcanvas'))
var offcanvasList = offcanvasElementList.map(function (offcanvasEl) {
  return new bootstrap.Offcanvas(offcanvasEl)
})

Kurucu isteğe bağlı bir seçenek nesnesi alır. Tek bir panel için örnek oluşturup göstermek:

var myOffcanvas = document.getElementById('myOffcanvas')
var bsOffcanvas = new bootstrap.Offcanvas(myOffcanvas)
bsOffcanvas.show()

toggle, show ve hide asenkrondur; geçiş başladığında çağırana dönerler, panel tamamen açılmadan ya da kapanmadan önce. Geçiş sürerken yapılan yöntem çağrıları yok sayılır. Bu ortak davranış ve örnek oluşturma kalıpları Bootstrap JavaScript API yazısında anlatılıyor. Offcanvas'ın dört olayı vardır:

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

v5.0.2 kaynağında show.bs.offcanvas olayında preventDefault() çağrılırsa panel açılmaz. Panel her açıldığında içeriğini tazelemek için show.bs.offcanvas, içindeki bir arama kutusuna odak vermek gibi işler için ise geçiş bittikten sonra tetiklenen shown.bs.offcanvas uygundur. JavaScript'in temelleri için JavaScript öğrenme rehberine bakabilirsiniz.

Offcanvas ile mobil menü

Offcanvas'ın en yaygın kullanımlarından biri mobil gezinme menüsüdür. Bootstrap 5.0 örnek şablonları arasında "Offcanvas navbar" adlı bir şablon vardır, ama dikkat: bu şablon offcanvas bileşenini kullanmaz. Kendi CSS dosyasında tanımlanan .offcanvas-collapse adlı özel bir sınıfla ve bu sınıfa .open ekleyip çıkaran birkaç satırlık kendi JavaScript koduyla çalışır. Şablonu kopyalayıp offcanvas seçeneklerinin, olaylarının ya da odak yönetiminin çalışmasını beklemek bu yüzden yanıltıcıdır.

Belgelenmiş parçalarla kurulan bir alternatif şöyledir: navbar'daki açma düğmesi Collapse yerine offcanvas'ı hedefler. Navbar'a hiçbir .navbar-expand sınıfı verilmediği için düğme her ekran genişliğinde görünür; bağlantılar sağdan açılan panelde dikey bir nav olarak durur.

<nav class="navbar navbar-light bg-light">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Firma Adı</a>
    <button class="navbar-toggler" type="button" data-bs-toggle="offcanvas" data-bs-target="#mobilMenu" aria-controls="mobilMenu" aria-label="Menüyü aç">
      <span class="navbar-toggler-icon"></span>
    </button>
  </div>
</nav>

<div class="offcanvas offcanvas-end" tabindex="-1" id="mobilMenu" aria-labelledby="mobilMenuBaslik">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="mobilMenuBaslik">Menü</h5>
    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Kapat"></button>
  </div>
  <div class="offcanvas-body">
    <nav class="nav flex-column">
      <a class="nav-link active" aria-current="page" href="#">Ana sayfa</a>
      <a class="nav-link" href="#">Hizmetler</a>
      <a class="nav-link" href="#">İletişim</a>
    </nav>
  </div>
</div>

5.0 belgelerinde offcanvas'ı belirli bir kesme noktasından sonra normal navbar'a çeviren bir sınıf anlatılmaz. Geniş ekranda bağlantıların yatay görünmesini istiyorsanız ya klasik Collapse tabanlı navbar'ı kullanırsınız ya da yatay bağlantıları ve düğmeyi display yardımcılarıyla kesme noktasına göre gösterip gizlersiniz. Navbar seçenekleri Bootstrap navbar yazısında, gösterme ve gizleme sınıfları display yardımcıları yazısında anlatılıyor.

Sass değişkenleri

Offcanvas değişkenleri scss/_variables.scss içindedir ve çoğu modal değişkenlerinden türetilir: iç boşluk için $offcanvas-padding-y ve $offcanvas-padding-x ($modal-inner-padding, yani $spacer), yan panel genişliği için $offcanvas-horizontal-width (400px), üst ve alt panel yüksekliği için $offcanvas-vertical-height (30vh), geçiş süresi için $offcanvas-transition-duration (.3s), arka plan için $offcanvas-bg-color ($modal-content-bg). Kenarlık ve gölge değişkenleri de modal içerik değişkenlerinden gelir. Katman değeri $zindex-offcanvas (1050) olarak ayrı tanımlıdır. Değişkenleri ezmek için Bootstrap Sass yazısına bakın.

Sık yapılan hatalar

• Yerleşim sınıfı yok. Offcanvas'ın varsayılan yerleşimi olmadığı için yalnızca .offcanvas yazılan panel doğru açılmaz; .offcanvas-start gibi bir sınıf ekleyin.
• Panele margin veya translate verilmiş. Kayma animasyonu transform ile çalıştığı için bozulur; ayarları iç öğelere verin.
• Seçenek tetikleyiciye yazılmış. data-bs-scroll ve data-bs-backdrop .offcanvas öğesine yazılır, düğmeye değil.
• Offcanvas navbar şablonunu bileşen sanmak. O şablon kendi CSS ve JavaScript'iyle çalışır; bileşen seçenekleri ona uygulanmaz.
• Kapatma için bağlantı kullanmak. Belgeler data-bs-dismiss="offcanvas" için <button> öğesini ister.
• Başlıkla bağlantı kurulmamış. aria-labelledby yoksa ekran okuyucu açılan iletişim kutusunun adını duyuramaz.
• İki paneli aynı anda açmaya çalışmak. Aynı anda yalnızca bir offcanvas gösterilebilir; panel içinden başka bir panel açmak yerine içeriği tek panelde düzenleyin.
• Bootstrap 4 ile denemek. Offcanvas v4'te yoktur; sınıflar 4.x CSS'inde tanımlı değildir. Geçiş notları için Bootstrap 4'ten 5'e geçiş yazısına bakın.

Sık Sorulan Sorular

Offcanvas ile modal arasındaki fark nedir?

İkisi de kavram olarak modal iletişim kutusudur ve bazı JavaScript kodlarını paylaşır, ama ayrı eklentilerdir. Modal sayfanın üzerinde bir iletişim kutusu olarak açılır; offcanvas ekranın bir kenarından kayar ve scroll seçeneğiyle arkadaki sayfanın kaydırılmasına izin verebilir. Modal ayrıntıları Bootstrap modal yazısında anlatılıyor.

Offcanvas için Popper gerekir mi?

Hayır, offcanvas'ın kendisi Popper kullanmaz. Ancak panelin içine açılır menü koyarsanız o menü için Popper gerekir; en kolay yol Popper'ı içeren bootstrap.bundle.min.js dosyasını yüklemektir.

Panelin genişliğini değiştirebilir miyim?

Sass kullanıyorsanız $offcanvas-horizontal-width değişkenini değiştirin. Derlenmiş CSS kullanıyorsanız kendi CSS dosyanızda .offcanvas-start veya .offcanvas-end için width değerini ezebilirsiniz; max-width: 100% kuralı dar ekranda taşmayı yine önler.

Sayfa açıldığında panelin açık gelmesi mümkün mü?

Evet, .offcanvas öğesine .show sınıfını ekleyin. v5.0.2 kaynağına göre eklenti sayfa yüklendiğinde bu paneller için örnek oluşturup onları gösterir.

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 modal pencere · Bootstrap accordion ve collapse · Bootstrap JavaScript API ve olaylar · Bootstrap erişilebilirlik · JavaScript öğrenme rehberi