Descubre cómo funcionan los detalles y elementos de resumen muy útiles, y dónde los usan.
Un widget de divulgación es un control de interfaz de usuario que oculta y muestra contenido. Si estás leyendo en web.dev y tu viewport tiene menos de 106 ems de ancho; para ello, haz clic en el botón arriba de este párrafo revela el índice de esta sección. Si no ves la opción, reduce el tamaño del navegador para ver la navegación del índice en esta página como una de divulgación.
La interfaz gráfica de usuario de acordeón es una serie de imágenes apiladas verticalmente de divulgación. Un caso de uso común para la IU de acordeón es la página de Preguntas frecuentes en muchos sitios. Una pregunta frecuente sobre acordeón contiene una lista de preguntas visibles; hacer clic en una pregunta expande o "divulga", la respuesta a esa pregunta.
jQuery ha incluido un patrón de IU de acordeón desde al menos 2009. Versión original sin JavaScript
la solución de acordeón incluía hacer que cada pregunta de Preguntas frecuentes fuera una <label>
seguida de la marca de verificación etiquetada y, luego, mostrar <div>
cuando se marcó la marca de verificación. El CSS se veía así:
#FAQ [type="checkbox"] + div.answer {
/* all the answer styles */
display: none;
}
#FAQ [type="checkbox"]:checked + div.answer {
display: block;
}
¿Por qué es historia? Los widgets de divulgación, como los acordeones, sin JavaScript ni hackeos de controles de formularios, son relativamente recientes.
suma; <details>
y <summary>
son completamente compatibles con todos los navegadores modernos desde enero de 2020. Ahora puedes crear funciones
que usar widgets de divulgación atractivos
con solo HTML semántico. Los elementos <details>
y <summary>
son todo lo que necesitas: son una forma integrada de controlarlos.
expandir y contraer contenido. Cuando un usuario presiona un <summary>
o hace clic en él, o suelta la tecla Intro cuando
El elemento <summary>
está enfocado, el contenido del elemento superior <details>
se activa o desactiva a visible.
Como todo el contenido semántico, puedes mejorar de forma progresiva las características y el aspecto predeterminados. En este caso, un poco de Se agregó CSS, pero nada más:
Notarás que estos códecs no contienen JavaScript.
Activar o desactivar la visibilidad: el atributo open
El elemento <details>
es el contenedor del widget de divulgación. <summary>
es el resumen o la leyenda de su elemento superior <details>
. El
"resumen", por lo que funciona como un botón que activa o desactiva la visualización del resto del contenido del elemento superior. Interacciones
Con <summary>
, se activa o desactiva <details>
para mostrar los elementos del mismo nivel del resumen autoetiquetado el atributo open
del elemento.
El atributo open
es un atributo booleano. Si está presente, sin importar el valor o la falta de este, indica que todos los <details>
el contenido se muestra al usuario. Si el atributo open
no está presente, solo se muestra el contenido de <summary>
.
Debido a que el atributo open
se agrega y se quita automáticamente a medida que el usuario interactúa con el control, se puede usar en CSS para lo siguiente:
diseñar el elemento de forma diferente según su estado.
Puedes crear un acordeón con una lista de varios elementos <details>
, cada uno con un elemento secundario <summary>
. Omite el atributo open
en tu código HTML significa que el elemento <details>
se contraerá o se cerrará, y solo se verán los encabezados de resumen cuando se cargue la página.
cada encabezado abre el resto del contenido del elemento superior <details>
. Si incluyes el atributo open
en tu HTML, la <details>
se renderizará expandido, con el contenido visible, cuando se cargue la página.
El contenido oculto en el estado contraído se puede buscar en algunos navegadores, pero no en otros, a pesar de que el contenido contraído no es parte del DOM. Si realizas una búsqueda en Edge o Chrome, se expandirán los detalles que contengan un término de búsqueda para mostrarse el caso. Este comportamiento no se replica en Firefox ni en Safari.
<summary>
debe ser el primer elemento secundario de un elemento <details>
, que represente un resumen, una leyenda o una leyenda del resto
del contenido del elemento <details>
superior en el que está anidado. El contenido del elemento <summary>
puede ser cualquier encabezado.
contenido, texto sin formato o HTML que se puede usar en un párrafo.
Cómo activar o desactivar el marcador de resumen
En los dos códecs anteriores, notarás la flecha hacia inline-start.
en la parte lateral del resumen. Un widget de divulgación normalmente se presenta en la pantalla con un pequeño triángulo que rota (o se tuerce)
para indicar el estado abierto o cerrado, con una etiqueta junto al triángulo. El contenido del elemento <summary>
etiqueta el widget de divulgación.
La flecha que gira en la parte superior de cada sección es un ::marker
establecido en el
<summary>
. Al igual que los elementos de lista, el elemento <summary>
admite list-style
.
propiedad abreviada y sus propiedades de atajo, incluida list-style-type
.
Puedes definir el estilo del triángulo desplegable con CSS, lo que incluye cambiar el marcador utilizado de un triángulo a cualquier otro tipo de viñeta, como
una imagen con list-style-image
Para aplicar otros estilos, usa un selector similar a details summary::marker
. El
El pseudoelemento ::marker
solo acepta una cantidad limitada de estilos. Quita el
::marker
y reemplazarlo por ::before
, que es más fácil de diseñar, es
Una práctica común: los estilos de CSS cambian levemente el estilo del contenido generado en función de la presencia (o ausencia)
del atributo open. Para quitar el ícono del widget de divulgación, configura list-style: none
o configura el contenido
del marcador en none
, pero siempre deben incluir indicadores visuales para informar a los usuarios videntes que el contenido del resumen es un botón de activación
que mostrará y ocultará contenido tras la activación.
details summary::before {
/* all the styles */
}
details[open] summary::before {
/* changes applied when open only */
}
En este ejemplo, se quita el marcador predeterminado y se agrega contenido generado para crear una +
cuando se cierran los detalles y una -
.
cuando se abren los detalles.
Si quieres que el bloque de detalles se abra de forma predeterminada, incluye el atributo open
en la etiqueta <details>
de apertura. También puedes agregar espacio
entre cada diálogo y cambia la rotación del marcador creado con el contenido generado para mejorar su aspecto:
Cómo se manejan los errores
Si no incluyes un <summary>
, el navegador creará uno por ti: con un marcador y la palabra "details". Este resumen
es parte de una shadow root y, por lo tanto, no se le aplicarán estilos de resumen de CSS de autor. Lamentablemente, Safari no incluye
los detalles en el orden de enfoque del teclado.
Si incluyes una <summary>
, pero no es el primer elemento en la <details>
, el navegador aún mostrará el resumen.
como se debe. Tampoco fallará si incluyes un vínculo, una etiqueta o algún otro elemento interactivo en el resumen, pero los navegadores
manejan el contenido interactivo dentro de contenido interactivo de manera diferente. Por ejemplo, si incluyes un vínculo en un resumen, algunos navegadores
agregará el resumen y el enlace al orden predeterminado de tabulación, pero otros navegadores no se enfocarán en el enlace de forma predeterminada.
Si haces clic en una <label>
anidada en una <summary>
, algunos navegadores se enfocarán en el control de formulario asociado. otros navegadores
Se enfocará el control de formulario y activarás o cerrarás la <details>
.
La interfaz HTMLDetailsElement
Como todos los elementos HTML, la HTMLDetailsElement
hereda todos
propiedades, métodos y eventos de HTMLElement
, y agrega el
La propiedad de instancia open
y la toggle
para cada evento. La propiedad HTMLDetailsElement.open
es un valor booleano
valor que refleje el atributo HTML open
e indica
si el contenido del elemento (sin contar los <summary>
) se mostrará al usuario. Se activa el evento de activación
Cuando el elemento <details>
se abre o se cierra. Puedes escuchar este evento mediante addEventListener()
.
Si deseas escribir una secuencia de comandos para cerrar los detalles abiertos cuando el usuario abra otros detalles, quita el atributo open.
con removeAttribute("open")
:
Este es el único ejemplo de uso de JavaScript. Es probable que no necesites JavaScript, excepto para esta funcionalidad de cerrar otras widgets de divulgación abiertos.
Recuerda que <details>
y <summary>
pueden tener mucho estilo y hasta se pueden usar para crear sugerencias de herramientas.
Pero, si vas a usar estos elementos semánticos para casos de uso en los que la semántica nativa no coincide, asegúrate siempre de mantener la accesibilidad.
HTML, en su mayoría, es accesible de forma predeterminada. Nuestro trabajo como desarrolladores es asegurarnos de que se pueda acceder a nuestro contenido.
Verifica tus conocimientos
Pon a prueba tu conocimiento sobre los detalles y el resumen.
¿<summary>
debe ser el primer elemento secundario de qué elemento?
<p>
<fieldset>
<details>