Detalles y resumen

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.