תיעוד HTML עם דוגמאות להרצה: details ו-summary

Q: מה עושים details ו-summary ב-HTML?

יוצר רכיב חשיפה: קטע שאפשר לפתוח ולסגור. הילד הראשון שלו, , הוא התווית שתמיד גלויה; לחיצה עליו (או Enter או Space כשהוא במיקוד) מציגה או מסתירה את כל השאר בתוך .

Q: איך גורמים לאלמנט details להיות פתוח כברירת מחדל?

הוסיפו את המאפיין הבוליאני open: . הדפדפן מוסיף ומסיר את המאפיין הזה כשהמשתמש פותח וסוגר, כך ש-CSS יכול לעצב את details[open].

Q: איך יוצרים אקורדיון שבו רק קטע אחד פתוח?

תנו לכל בקבוצה את אותו מאפיין name, למשל name="faq". פתיחה של אחד סוגרת את האחרים באותה קבוצה, בלי JavaScript.

Q: איך מסירים או משנים את החץ ב-summary של details?

הגדירו 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 או Space, ואומר לקוראי מסך אם הוא מורחב או מכווץ. אין כאן 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 מעלות והופך לאיקס כשהקטע נפתח. השאירו סגנון מיקוד גלוי כמו ה-outline של :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 האחרון. האירוע לא מבעבע, אז האזינו על כל אלמנט <details> ולא על הורה.

מה נכנס ל-summary

summary מכיל טקסט, אלמנטים inline, או כותרת כשהכותרת של הקטע שייכת למבנה העמוד:

<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 או Space כשהוא במיקוד) מציגה או מסתירה את כל השאר בתוך <details>.

איך גורמים לאלמנט details להיות פתוח כברירת מחדל?

הוסיפו את המאפיין הבוליאני open: <details open>. הדפדפן מוסיף ומסיר את המאפיין הזה כשהמשתמש פותח וסוגר, כך ש-CSS יכול לעצב את details[open].

איך יוצרים אקורדיון שבו רק קטע אחד פתוח?

תנו לכל <details> בקבוצה את אותו מאפיין name, למשל name="faq". פתיחה של אחד סוגרת את האחרים באותה קבוצה, בלי JavaScript.

איך מסירים או משנים את החץ ב-summary של details?

הגדירו 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 פותחת אותו.

מושגים קשורים