HTML details ve summary Etiketi: Açılır Kapanır İçerik ve Akordeon

Temel yapı ve davranış

MDN <details> öğesini, bilgilerin yalnızca açık durumdayken görünür olduğu bir açma kapama bileşeni (disclosure widget) olarak tanımlar. Bileşen ekranda genellikle dönen küçük bir üçgen ve yanındaki etiketle gösterilir; etiket <summary> öğesinin içeriğidir. Varsayılan kapalı durumda yalnızca üçgen ve etiket görünür. Kullanıcı bileşene tıkladığında ya da odaklanıp boşluk tuşuna bastığında bileşen açılır ve içeriği ortaya çıkar. Dönen üçgen nedeniyle bu bileşenlere bazen İngilizce "twisty" de denir.

<details>
  <summary>Sistem gereksinimleri</summary>
  <p>Güncel bir tarayıcı yeterlidir.</p>
</details>

İçerik modeli bu yapıyı kesinleştirir: <details> içine önce bir <summary>, ardından akış içeriği alır. <summary> ise yalnızca bir <details> öğesinin ilk çocuğu olarak kullanılabilir. İlk çocuk bir <summary> değilse tarayıcı etiket olarak kendi varsayılan metnini, genellikle "Details" sözcüğünü kullanır. Bu metni siz belirleyemezsiniz ve sayfanızın diliyle uyumlu olmayabilir; bu yüzden <summary> yazmayı unutmayın.

open özniteliği: Açık başlatmak ve Boolean tuzağı

open bir Boolean özniteliktir. Varsa içerik görünür, yoksa gizlidir; varsayılan olarak yoktur. MDN burada sık yapılan bir hataya özellikle dikkat çeker: open="false" yazmak içeriği gizlemez, aksine görünür yapar. Boolean özniteliklerde değerin ne olduğu önemli değildir, yalnızca özniteliğin varlığına bakılır. İçeriği gizlemek için özniteliği tamamen kaldırmanız gerekir.

<details open>
  <summary>Kurulum adımları</summary>
  <ol>
    <li>Dosyaları yükleyin.</li>
    <li>Veritabanını oluşturun.</li>
  </ol>
</details>

Bileşeni bir betikle açıp kapatmak için de aynı öznitelik kullanılır: open eklenir ya da kaldırılır. CSS ile açık durumu hedeflemek istediğinizde details[open] öznitelik seçicisi çalışır; MDN, :open sözde sınıfını desteklemeyen tarayıcılar için bu seçiciyi önerir.

name ile akordeon: Aynı anda tek açık kutu

name özniteliği birden çok <details> öğesini bir gruba bağlar. Aynı name değerini taşıyan öğelerden aynı anda yalnızca biri açık olabilir; birini açmak diğerini kapatır. MDN bunun, betik yazmadan akordeon gibi arayüzler oluşturmayı kolaylaştırdığını belirtir. İki ayrıntı önemlidir: Gruptaki birden çok öğeye open verirseniz yalnızca kaynak koddaki ilk öğe açık gösterilir. Gruptaki öğelerin kaynak kodda yan yana olması da gerekmez; aynı adı taşımaları yeterlidir.

<details name="sss" open>
  <summary>details için JavaScript gerekir mi?</summary>
  <p>Hayır, açma ve kapama tarayıcıya yerleşiktir.</p>
</details>
<details name="sss">
  <summary>Kutu açık başlayabilir mi?</summary>
  <p>Evet, open özniteliğini ekleyin.</p>
</details>
<details name="sss">
  <summary>Gruptaki kutular yan yana olmak zorunda mı?</summary>
  <p>Hayır, aynı name değeri yeterlidir.</p>
</details>

Bu örnekte ilk soru açık başlar. Kullanıcı ikinci soruyu açtığında ilk soru kendiliğinden kapanır. Aynı sayfada farklı gruplar istiyorsanız her grup için farklı bir name değeri kullanırsınız; örneğin bir bölüm için name="sss", başka bir bölüm için name="fatura".

summary içine ne yazılabilir?

MDN'e göre <summary> içeriği herhangi bir başlık içeriği, düz metin ya da paragraf içinde kullanılabilecek HTML olabilir. Teknik özet bunu "cümle içi içerik, isteğe bağlı olarak başlık içeriğiyle karışık" diye ifade eder. Yani etiketin önemli olduğunu belirtmek için içine <strong> koyabilir ya da etiketi bir başlık olarak yazabilirsiniz.

<details>
  <summary><strong>Önemli:</strong> Okumadan geçmeyin</summary>
  <p>Buradaki içerik yalnızca kutu açıldığında görünür.</p>
</details>

Erişilebilirlik ve klavye

<details> kullanmanın en büyük avantajı, erişilebilirlik bilgisinin tarayıcı tarafından hazır sağlanmasıdır. MDN, <summary> içeriğinin bileşenin etiketi, <details> içeriğinin ise <summary> için erişilebilir açıklama olduğunu belirtir. <details> öğesinin varsayılan ARIA rolü group'tur ve teknik özete göre başka bir role izin verilmez; <summary> için de rol değiştirmeye izin yoktur. ARIA group rolü, sayfanın özetinde ya da içindekiler listesinde yer alması amaçlanmayan, ilişkili öğelerden oluşan bir topluluğu tanımlar; bu yüzden bir açma kapama kutusu için uygundur.

Klavye tarafında ek bir işe gerek yoktur. tabindex sayfası, bir <details> öğesinin özetini sağlayan <summary> öğesinin, tarayıcının arka planda varsayılan olarak tabindex değeri 0 verdiği odaklanabilir öğeler arasında olduğunu belirtir. MDN, bu öğelere davranışı değiştirmek istemiyorsanız tabindex eklememenizi söyler. Aynı sayfa, etkileşimli bileşenleri <div> gibi etkileşimsiz öğelerle kurmak yerine <details>, <button> ve <select> gibi yerleşik rolü ve durumu olan öğeleri kullanmayı önerir. Bir <div> ile JavaScript'ten yapılmış açılır kapanır kutu bu bilgileri kendiliğinden taşımaz. Klavye erişiminin genel kuralları için tabindex yazısına bakabilirsiniz.

İçerik kategorileri ve iç içe kurallar

Teknik özete göre <details> akış içeriği, bölümleme kökü (sectioning root), etkileşimli içerik ve somut içerik kategorilerindedir; akış içeriği kabul eden her öğenin içinde durabilir. Etkileşimli içerik olması pratikte önemli bir sonuç doğurur: <a> öğesinin içinde hiçbir etkileşimli içerik bulunamaz, <button> de etkileşimli içerik alamaz. Bu yüzden bir <details> öğesini bağlantının ya da düğmenin içine koyamazsınız.

Bir başka tuzak paragraflardır. <p> yalnızca cümle içi içerik alır ve <details> bu kategoride değildir. Üstelik <p> sayfasındaki etiket atlama kuralına göre, bir paragrafın ardından hemen <details> geliyorsa paragrafın kapanış etiketi atlanabilir. Yani <p>Metin <details>... yazdığınızda ayrıştırıcı paragrafı <details> başlamadan önce kapatır; yani açılır kutu paragrafın parçası olmaz. Açılır içeriği paragrafın içine değil, paragraftan sonra yazın. Bu tür yapı hataları için HTML iç içe kuralları yazısına bakabilirsiniz.

toggle olayı

Normal HTML olaylarına ek olarak <details>, durumu açık ile kapalı arasında her değiştiğinde bir toggle olayı alır. Olay durum değiştikten sonra gönderilir. Tarayıcı olayı gönderemeden durum birkaç kez değişirse olaylar birleştirilir ve yalnızca bir tane gönderilir. <summary> sayfası sırayı da açıklar: Kullanıcı özete tıklar, üst <details> açılır ya da kapanır, ardından toggle olayı gönderilir. Açılan kutunun içeriğini ilk açılışta yüklemek ya da açık kalan bölümü kaydetmek gibi işler için bu olayı dinleyebilirsiniz.

const kutu = document.querySelector("details");
kutu.addEventListener("toggle", () => {
  if (kutu.open) {
    // kutu açıldı
  } else {
    // kutu kapandı
  }
});

Burada open özelliği öğenin o anki durumunu verir. Olay işleme konusunun genel anlatımı için JavaScript öğrenme rehberine bakabilirsiniz.

Görünümü değiştirmek: Kısa notlar

MDN, <details> öğesini iki parçalı bir kap gibi düşünmeyi önerir: Açıkken de kapalıyken de görünen <summary> ve içeriği kapalıyken gizlenen ::details-content sözde öğesi. Spesifikasyona göre <summary> varsayılan olarak display: list-item değerini alır; bu yüzden üçgen işaret bir liste işareti gibi değiştirilebilir ya da display: block ile kaldırılabilir. Açılış kapanış animasyonu ::details-content üzerinden yapılabilir. Bu işlerin ayrıntısı CSS konusudur ve bu yazının kapsamı dışındadır.

Uygulamalı örnek: Bir rehber sayfasında ek ayrıntılar

Aşağıdaki örnekte bir kurulum rehberinin ana adımları her zaman görünür; her adımın teknik ayrıntıları ise isteyen okuyucu için bir <details> içinde durur. Kutular bir name grubunda değildir, çünkü okuyucunun birden fazla adımın ayrıntısını aynı anda açık tutmak isteyebileceğini varsayıyoruz. Açılan içerik akış içeriği olduğu için liste, tablo ya da kod bloğu içerebilir.

<section>
  <h2>1. Dosyaları yükleyin</h2>
  <p>Sitenizin dosyalarını sunucudaki ana klasöre kopyalayın.</p>
  <details>
    <summary>Hangi dosyalar yüklenmeli?</summary>
    <ul>
      <li><code>index.html</code> ve diğer sayfalar</li>
      <li>Görseller ve stil dosyaları</li>
    </ul>
  </details>
</section>
<section>
  <h2>2. Adresi kontrol edin</h2>
  <p>Tarayıcıda alan adınızı açın.</p>
  <details>
    <summary>Sayfa açılmazsa</summary>
    <p>Dosya adının <code>index.html</code> olduğundan emin olun.</p>
  </details>
</section>

Bu düzende iki şeye dikkat edin. Okuyucunun mutlaka bilmesi gereken talimat <details> dışında, görünür paragraftadır; kutu yalnızca isteğe bağlı ayrıntıyı saklar. Her <summary> de içerikten ne beklenmesi gerektiğini anlatan kısa bir soru ya da ifade olarak yazılmıştır. Ekran okuyucu kullanıcısı odakladığı özetin metnini duyar ve kutunun açık mı kapalı mı olduğunu öğrenir; bu yüzden "Daha fazla" gibi belirsiz etiketler yerine konuyu söyleyen etiketler seçmek iyi bir uygulamadır. Bölümler başlıklarıyla ayrıldığı için sayfanın genel yapısı da bozulmaz; bölüm seçimi için article ve section farkı yazısına bakabilirsiniz.

details, dialog, popover ve hidden karşılaştırması

Belirleyici fark, içeriğin nerede durduğudur. <details> içeriği sayfanın normal akışında, etiketinin hemen altında açılır. Diyalog ve popover ise içeriği sayfanın üstünde ayrı bir katmanda gösterir. hidden özniteliği bir açma kapama bileşeni değildir; görünürlüğü sizin betiğiniz yönetir. Ayrıntılar için hidden ve inert yazısına bakabilirsiniz.

Sık yapılan hatalar

• open="false" yazmak: Boolean öznitelik olduğu için kutu açık kalır. Kapatmak için özniteliği silin.
• summary'yi ilk çocuk yapmamak: <summary> yalnızca ilk çocuk olarak kullanılabilir; yoksa tarayıcı varsayılan bir etiket gösterir.
• summary'ye tabindex eklemek: Öğe zaten odaklanabilir; gereksiz tabindex varsayılan davranışı değiştirebilir.
• details'e rol vermek: Teknik özete göre <details> ve <summary> için başka bir ARIA rolüne izin yoktur.
• details'i paragraf, bağlantı ya da düğme içine koymak: İçerik modeli kurallarına aykırıdır.
• Önemli içeriği kapalı kutuda saklamak: Kullanıcının mutlaka görmesi gereken bir uyarı, kapalı bir kutunun içinde gözden kaçabilir.
• Gruplu akordeonda birden çok open: Yalnızca kaynak koddaki ilk öğe açık gösterilir; diğer open öznitelikleri boşa yazılmış olur.

Sık Sorulan Sorular

details çalışması için JavaScript gerekir mi?

Hayır. Açma, kapama, klavye desteği ve name ile tek açık kutu davranışı tarayıcıya yerleşiktir. JavaScript yalnızca toggle olayına tepki vermek gibi ek işler için gerekir.

Sayfa açıldığında birden çok kutu açık olabilir mi?

Evet, kutular bir name grubunda değilse her birine open verebilirsiniz. Aynı grupta ise yalnızca kaynak koddaki ilk açık kutu açık gösterilir.

summary içinde başlık kullanmak doğru mu?

MDN örneğinde <summary> içinde bir <h4> kullanılır ve içerik modeli buna izin verir. Ancak bazı tarayıcılar <summary> öğesine button rolü verdiği için başlık, ekran okuyucularda başlık olarak duyurulmayabilir. Kullanacaksanız farklı platformlarda deneyin.

summary yazmadan details kullanabilir miyim?

Teknik olarak tarayıcı kutuyu yine gösterir, ama etiket olarak kendi varsayılan metnini (genellikle "Details") kullanır. MDN, bir özet ya da etiketin <summary> ile sağlanması gerektiğini belirtir. Kullanıcının kutuyu açmadan içinde ne olduğunu anlaması için her zaman açıklayıcı bir <summary> yazın.

Kutunun açık olup olmadığını betikte nasıl anlarım?

Öğenin open özelliğine bakarsınız; MDN'in toggle örneği de bu özelliği kullanır. Olay durum değiştikten sonra gönderildiği için, olay işleyicisinin içinde okuduğunuz değer kutunun yeni durumudur. Kutuyu betikle açmak ya da kapatmak için de open özniteliğini ekler veya kaldırırsınız.

İç içe details kullanabilir miyim?

<details> akış içeriği alır ve kendisi de akış içeriğidir; bu yüzden bir kutunun içeriğinde başka bir <details> yer alabilir. Kullanıcının nerede olduğunu kaybetmemesi için iç içe seviyeleri az tutmak iyi bir fikirdir.

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: HTML öğrenme rehberi · dialog etiketi · popover özniteliği · hidden ve inert · tabindex ve klavye erişimi · HTML sık yapılan hatalar