HTML <summary> Tag
Il tag HTML <summary> definisce l'etichetta cliccabile per un widget <details>. Sintassi, accessibilità, stile ed esempi.
Il tag <summary> definisce la didascalia cliccabile — l'etichetta visibile — per un widget di divulgazione <details>. Fare clic sul summary espande o comprime il resto del contenuto di <details>, quindi il summary è la parte che rimane sempre visibile sullo schermo, sia che il widget sia aperto che chiuso.
L'elemento <summary> deve essere il primo figlio di un elemento <details>. Se <details> non ha un <summary>, il browser fornisce un'etichetta predefinita (di solito la parola "Details"), che raramente è ciò che si desidera — quindi quasi ogni widget di divulgazione dovrebbe includerne uno.
Questa pagina tratta la sintassi di <summary>, il suo comportamento, le caratteristiche di accessibilità, l'evento toggle e come applicare stili (inclusa la rimozione del triangolo di divulgazione).
Sintassi
Il tag <summary> si usa in coppia. Il testo dell'etichetta viene scritto tra i tag di apertura <summary> e chiusura </summary>, e risiede direttamente all'interno di <details>.
Esempio del tag HTML <summary>
Tag HTML <summary>
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<details>
<summary>Copyright 2013-2014.</summary>
<p>W3docs. All rights reserved.</p>
<p>The content of the website is the property of W3Docs.com.</p>
</details>
</body>
</html>Contenuto avanzato all'interno di <summary>
Un summary non è limitato al solo testo. Può contenere contenuto inline come <strong>, <em>, <code> o un'icona, utile per enfatizzare l'etichetta:
<details>
<summary><strong>Shipping & returns</strong> — read before ordering</summary>
<p>Orders ship within 2 business days. Returns accepted for 30 days.</p>
</details>Mantenere il summary breve e significativo: è l'etichetta che un utente legge (e che uno screen reader annuncia) per decidere se aprire il widget.
Accessibilità
L'elemento <summary> espone un ruolo ARIA implicito di button alle tecnologie assistive, ed è focalizzabile e azionabile da tastiera per impostazione predefinita:
- Tab sposta il focus sul summary.
- Invio o Spazio attiva o disattiva l'apertura del
<details>padre.
Per questo motivo, non bisogna inserire un vero <button> o un link all'interno del summary — il summary è già il controllo. Assicurarsi che il summary contenga un'etichetta chiara e descrittiva, in modo che gli utenti che navigano tramite tabulazione o screen reader sappiano cosa rivela il widget.
L'evento toggle e details.open
Lo stato aperto/chiuso di un widget di divulgazione risiede nell'elemento <details>, non nel summary. L'attributo boolean open riflette questo stato e può essere letto o impostato come details.open in JavaScript.
Ogni volta che lo stato cambia — tramite clic, tastiera o script — il browser genera un evento toggle sull'elemento <details>. L'ascolto di questo evento consente di reagire all'apertura o chiusura del widget da parte dell'utente (ad esempio, per caricare contenuto in modo lazy o inviare dati di analytics) invece di interrogare continuamente lo stato:
const details = document.querySelector('details');
details.addEventListener('toggle', () => {
console.log('Details is now', details.open ? 'open' : 'closed');
});Come applicare stili al tag <summary>
Lo stile predefinito di un <summary> usa la proprietà CSS display con il valore list-item, che è ciò che disegna il triangolo di divulgazione (il marcatore) accanto all'etichetta.
È possibile applicare stili al summary come a qualsiasi altro elemento — cambiare il colore, aggiungere padding o impostare un cursor:
summary {
color: blue;
cursor: pointer;
padding: 8px;
}Rimozione del triangolo di divulgazione
Per nascondere il triangolo predefinito in modo affidabile su tutti i browser, rimuovere il marcatore di lista e anche il marcatore legacy WebKit/Blink:
summary {
list-style: none; /* Firefox and standards-based browsers */
}
summary::-webkit-details-marker {
display: none; /* Safari and older Chrome */
}Attributi
Il tag <summary> non ha attributi propri obbligatori. Supporta gli Attributi Globali e gli Attributi di Evento.
Creare una FAQ / accordion
Poiché ogni <details> funziona in modo indipendente, è possibile inserirne diversi in una pagina per creare una FAQ o un accordion. Ogni <summary> rappresenta la domanda, e il contenuto nascosto è la risposta:
<details>
<summary>How do I track my order?</summary>
<p>Use the tracking link in your confirmation email.</p>
</details>
<details>
<summary>Can I change my shipping address?</summary>
<p>Yes, as long as the order has not yet shipped.</p>
</details>
<details>
<summary>Do you ship internationally?</summary>
<p>We ship to most countries. Rates are shown at checkout.</p>
</details>Per consentire l'apertura di una sola sezione alla volta (un vero accordion), assegnare agli elementi <details> lo stesso attributo name in modo che il browser li mantenga mutuamente esclusivi.
Il tag <summary> è uno degli elementi HTML5. Vedere anche l'elemento <details> che etichetta.