وثائق HTML قابلة للتشغيل: details وsummary

Q: ما وظيفة details وsummary في HTML؟

ينشئ عنصر إفصاح: قسمًا يمكن فتحه وإغلاقه. وابنه الأول هو التسمية الظاهرة دائمًا، والنقر عليه (أو الضغط على Enter أو المسافة حين يكون التركيز عليه) يُظهر أو يخفي كل ما عداه داخل .

Q: كيف أجعل عنصر details مفتوحًا افتراضيًا؟

أضف السمة المنطقية open: . يضيف المتصفح هذه السمة ويزيلها حين يبدّل المستخدم الحالة، فيستطيع CSS تنسيق details[open].

Q: كيف أصنع أكورديون لا يُفتح فيه إلا قسم واحد؟

أعطِ كل في المجموعة السمة name نفسها، مثل name="faq". فتح أحدها يغلق الأخرى في تلك المجموعة، من دون JavaScript.

Q: كيف أزيل السهم في details summary أو أغيّره؟

اضبط list-style: none على summary وأضف summary::-webkit-details-marker { display: none; } لـ Safari. ثم ارسم مؤشرك الخاص، مثلًا بـ summary::after، وغيّره بـ details[open] summary::after.

Q: هل يمكنني معرفة متى يُفتح عنصر details؟

نعم. استمع إلى حدث toggle على العنصر واقرأ خاصيته open. وضبط details.open = true في JavaScript يفتحه.

محتوى قابل للطي بـ details وsummary

أحط المحتوى بـ <details> وضع <summary> أولًا. يبقى summary ظاهرًا، وكل ما عداه مخفي حتى ينقر عليه القارئ:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>details</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <details>
    <summary>What is included in the free plan?</summary>
    <p>Five projects, community support and all the beginner courses.</p>
  </details>
</body>
</html>

انقر السؤال لفتحه، ومرة أخرى لإغلاقه. يضيف المتصفح علامة المثلث، ويجعل summary قابلًا للتركيز، ويبدّله بـ Enter أو المسافة، ويخبر قارئات الشاشة إن كان موسَّعًا أم مطويًا. لا دخل لـ JavaScript في أي من ذلك.

إن حذفت <summary>، يعرض المتصفح تسمية افتراضية («Details» بالإنجليزية) بدلًا منه.

مفتوح افتراضيًا

السمة المنطقية open تُظهر المحتوى من البداية. يضيف المتصفح open ويزيلها حين يبدّل القارئ الحالة، فهي أيضًا نقطة الارتكاز للتنسيق:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>open</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    details { border: 2px solid #e5e7eb; border-radius: 8px; padding: 8px 12px; margin-bottom: 8px; }
    details[open] { border-color: #2563eb; }
    summary { cursor: pointer; font-weight: 600; }
  </style>
</head>
<body>
  <details open>
    <summary>Shipping</summary>
    <p>Orders ship within two working days.</p>
  </details>
  <details>
    <summary>Returns</summary>
    <p>Return any item within 30 days.</p>
  </details>
</body>
</html>

الصندوق المفتوح له حد أزرق من details[open]. افتح «Returns» وسيصبح أزرق أيضًا، ويمكن أن يكون الاثنان مفتوحين في الوقت نفسه.

الأكورديون: قسم واحد مفتوح في كل مرة

أعطِ عدة عناصر <details> الاسم name نفسه فتصبح مجموعة حصرية: فتح أحدها يغلق الأخرى. كان هذا يحتاج إلى JavaScript، وصار يعمل بالسمة وحدها في الإصدارات الحالية من Chrome وEdge وFirefox وSafari:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Accordion</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .faq { max-width: 420px; border: 1px solid #e5e7eb; border-radius: 10px; }
    .faq details + details { border-top: 1px solid #e5e7eb; }
    .faq summary { padding: 12px 14px; cursor: pointer; font-weight: 600; }
    .faq p { margin: 0; padding: 0 14px 12px; color: #374151; }
  </style>
</head>
<body>
  <div class="faq">
    <details name="faq" open>
      <summary>Is it free?</summary>
      <p>Yes, the basics are free forever.</p>
    </details>
    <details name="faq">
      <summary>Do I need to install anything?</summary>
      <p>No, everything runs in the browser.</p>
    </details>
    <details name="faq">
      <summary>Can I cancel any time?</summary>
      <p>Yes, from your account settings.</p>
    </details>
  </div>
</body>
</html>

افتح السؤال الثاني وسيُغلق الأول. احذف سمات name وستعود إلى الفتح بشكل مستقل. الأكورديون الحصري يخفي محتوى قد يرغب القارئ في مقارنته، لذلك استخدمه حين تكون الأقسام بدائل، واستخدم <details> العادي حين قد يريد الناس فتح عدة أقسام.

تنسيق العلامة

المثلث علامة قائمة على summary. list-style: none تزيله (وقاعدة ::-webkit-details-marker تغطي Safari)، ويمكن لعنصر زائف أن يرسم مؤشرك الخاص:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Custom marker</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    details { max-width: 420px; background: #f9fafb; border-radius: 8px; margin-bottom: 8px; }
    summary {
      list-style: none; cursor: pointer;
      display: flex; justify-content: space-between; align-items: center;
      padding: 12px 14px; font-weight: 600;
    }
    summary::-webkit-details-marker { display: none; }
    summary::after {
      content: "+"; font-size: 20px; color: #2563eb;
      transition: transform 0.2s;
    }
    details[open] summary::after { transform: rotate(45deg); }
    summary:focus-visible { outline: 3px solid #2563eb; outline-offset: 2px; border-radius: 8px; }
    details p { margin: 0; padding: 0 14px 12px; }
  </style>
</head>
<body>
  <details>
    <summary>How long are the lessons?</summary>
    <p>Most lessons take five to ten minutes.</p>
  </details>
  <details>
    <summary>Do I get a certificate?</summary>
    <p>Yes, when you finish a course.</p>
  </details>
</body>
</html>

علامة الزائد تدور 45 درجة لتصبح علامة ضرب حين يُفتح القسم. أبقِ نمط تركيز ظاهرًا مثل إطار :focus-visible هنا: فبمجرد إزالة العلامة الافتراضية تصبح حلقة التركيز هي ما يعتمد عليه مستخدمو لوحة المفاتيح.

حدث toggle والخاصية open

تستطيع JavaScript قراءة details.open وضبطها، وحدث toggle ينطلق بعد كل تغيير، سواء سببه نقرة أو مفتاح أو سكربت:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>toggle</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    button { font: inherit; padding: 4px 10px; margin-inline-end: 6px; }
    details { margin-top: 10px; border: 2px solid #e5e7eb; border-radius: 8px; padding: 8px 12px; }
    #log { color: #16a34a; }
  </style>
</head>
<body>
  <button id="expand">Expand all</button>
  <button id="collapse">Collapse all</button>
  <details><summary>Step 1</summary><p>Create an account.</p></details>
  <details><summary>Step 2</summary><p>Pick a course.</p></details>
  <p id="log">Nothing toggled yet.</p>
  <script>
    const all = document.querySelectorAll('details');
    all.forEach((d) => d.addEventListener('toggle', () => {
      document.getElementById('log').textContent =
        d.querySelector('summary').textContent + (d.open ? ' opened' : ' closed');
    }));
    document.getElementById('expand').onclick = () => all.forEach((d) => { d.open = true; });
    document.getElementById('collapse').onclick = () => all.forEach((d) => { d.open = false; });
  </script>
</body>
</html>

«Expand all» تضبط open على الاثنين، ويُظهر السجل آخر حدث toggle. الحدث لا ينتشر صعودًا إلى العناصر الأب (no bubbling)، لذلك استمع على كل عنصر <details> لا على العنصر الأب.

ما الذي يوضع في summary

يحتوي summary على نص، أو عناصر سطرية، أو عنوان حين يكون عنوان القسم جزءًا من مخطط الصفحة:

<details>
  <summary><h3>Refund policy</h3></summary>
  <p>...</p>
</details>

تجنّب الروابط والأزرار وحقول النماذج داخل <summary>: فـ summary نفسه عنصر تحكم، والعنصر التفاعلي بداخله سهل التفويت أو النقر بالخطأ، وتعلن قارئات الشاشة عناصر التحكم المتداخلة بشكل سيئ. ضع المحتوى التفاعلي في جسم <details> بدلًا من ذلك.

أخطاء شائعة

بناء زر تبديل بـ <div> وJavaScript. <details> يتولى أصلًا النقرات والمفاتيح وحالة قارئ الشاشة. وحين تحتاج فعلًا إلى زر تبديل مخصص، استخدم زرًا مع aria-expanded.
وضع <summary> في أي مكان غير البداية. يجب أن يكون الابن الأول لـ <details>.
إخفاء العلامة بلا بديل. أعطِ القراء إشارة ما إلى أن summary يُفتح، مثل علامة الزائد أعلاه.
استخدام display لإخفاء المحتوى. بدّل open بدلًا من ذلك، فـ CSS الذي يفرض إظهار المحتوى أو إخفاءه يتصادم مع حالة المتصفح.
مجموعات حصرية لمحتوى يقارنه الناس. استخدم name فقط حين يكون فتح قسم واحد في كل مرة منطقيًا.

الأسئلة الشائعة

ما وظيفة details وsummary في HTML؟

<details> ينشئ عنصر إفصاح: قسمًا يمكن فتحه وإغلاقه. وابنه الأول <summary> هو التسمية الظاهرة دائمًا، والنقر عليه (أو الضغط على Enter أو المسافة حين يكون التركيز عليه) يُظهر أو يخفي كل ما عداه داخل <details>.

كيف أجعل عنصر details مفتوحًا افتراضيًا؟

أضف السمة المنطقية open: <details open>. يضيف المتصفح هذه السمة ويزيلها حين يبدّل المستخدم الحالة، فيستطيع CSS تنسيق details[open].

كيف أصنع أكورديون لا يُفتح فيه إلا قسم واحد؟

أعطِ كل <details> في المجموعة السمة name نفسها، مثل name="faq". فتح أحدها يغلق الأخرى في تلك المجموعة، من دون JavaScript.

كيف أزيل السهم في details summary أو أغيّره؟

اضبط list-style: none على summary وأضف summary::-webkit-details-marker { display: none; } لـ Safari. ثم ارسم مؤشرك الخاص، مثلًا بـ summary::after، وغيّره بـ details[open] summary::after.

هل يمكنني معرفة متى يُفتح عنصر details؟

نعم. استمع إلى حدث toggle على العنصر <details> واقرأ خاصيته open. وضبط details.open = true في JavaScript يفتحه.

مفاهيم ذات صلة