Detalhes e resumo

Descubra como os detalhes muito úteis e os elementos de resumo funcionam e onde usá-los.

Um widget de divulgação é um controle de interface do usuário que oculta e mostra conteúdo. Se você estiver lendo isso em web.dev, e sua janela de visualização tem menos de 106 ems de largura, clicando no botão "Nesta página" acima desse parágrafo revela o sumário para nesta seção. Caso não o veja, reduza o navegador para ver a navegação do sumário nesta página como uma widget de divulgação.

A interface gráfica do usuário acordeão é uma série de imagens empilhadas verticalmente widgets de divulgação. Um caso de uso comum da interface do usuário acordeão é a página de Perguntas frequentes em muitos sites. Uma lista de perguntas frequentes contém uma lista de perguntas visíveis. clicar em uma pergunta expande, ou "divulga" a resposta à pergunta.

O jQuery inclui um padrão de interface acordeão desde 2009, no mínimo. A versão original, sem JavaScript, solução padrão incluiu tornar cada pergunta de perguntas frequentes uma <label> seguida pela marca de verificação rotulada e, em seguida, exibindo <div> quando a marca de seleção foi marcada. O CSS é mais ou menos assim:

#FAQ [type="checkbox"] + div.answer {
  /* all the answer styles */
  display: none;
}
#FAQ [type="checkbox"]:checked + div.answer {
  display: block;
}

Por que a história? Widgets de divulgação, como acordeões, sem JavaScript ou invasões de controle de formulário, são um método relativamente recente Além disso, <details> e <summary> têm suporte total a todos os navegadores modernos desde janeiro de 2020. Agora é possível criar conteúdo funcional, mas com menos widgets de divulgação usando apenas HTML semântico. Os elementos <details> e <summary> são tudo de que você precisa: eles são uma forma integrada de processar expandir e recolher o conteúdo. Quando um usuário clica ou toca em uma <summary> ou libera a tecla Enter quando a <summary> está em foco, e o conteúdo do botão <details> pai fica visível.

Como todo conteúdo semântico, você pode aprimorar progressivamente os recursos e a aparência padrão. Nesse caso, um pequeno O CSS foi adicionado, mas nada mais:

Observe que esses Codepens não contêm JavaScript.

Alternando a visibilidade: o atributo open

O elemento <details> é o contêiner do widget de divulgação. O <summary> é o resumo ou a legenda do <details> pai. A sumário é sempre exibido, agindo como um botão que alterna a exibição do restante do conteúdo do pai. Interação com <summary> alterna a exibição dos irmãos de resumo identificados automaticamente, alternando a tecla <details>. atributo open do elemento.

O atributo open é booleano. Se presente, independentemente do valor ou da falta dele, indica que todos os <details> conteúdos são mostrados ao usuário. Se o atributo open não estiver presente, apenas o conteúdo do <summary> será mostrado.

Como o atributo open é adicionado e removido automaticamente quando o usuário interage com o controle, ele pode ser usado no CSS para: definir um estilo diferente para o elemento com base no estado dele.

É possível criar um acordeão com uma lista de vários elementos <details>, cada um com um filho <summary>. Omitir o atributo open no seu HTML significa que o <details> será recolhido ou fechado, com apenas os cabeçalhos de resumo visíveis quando a página for carregada; cada título sendo o aberto para o restante do conteúdo no <details> pai. Se você incluir o atributo open no HTML, o <details> será renderizado expandido, com conteúdo visível, quando a página for carregada.

O conteúdo oculto no estado recolhido pode ser pesquisado em alguns navegadores, mas não em outros, mesmo que o conteúdo recolhido não faz parte do DOM. Se você pesquisar no Edge ou no Chrome, os detalhes que contêm um termo de pesquisa serão expandidos para mostrar o que aconteceu. Esse comportamento não é replicado no Firefox ou no Safari.

O <summary> precisa ser o primeiro filho de um elemento <details>, representando um resumo, legenda ou legenda para o restante. do conteúdo do elemento <details> pai em que ele está aninhado. O conteúdo do elemento <summary> pode ser qualquer título. conteúdo, texto simples ou HTML que possa ser usado em um parágrafo.

Alternar o marcador de resumo

Nos dois Codepenss anteriores, há uma seta para o lado do inline-start lado do resumo. Um widget de divulgação normalmente é apresentado na tela usando um pequeno triângulo que gira (ou torce). para indicar o status aberto/fechado, com um marcador ao lado do triângulo. O conteúdo do elemento <summary> rotula o widget de divulgação. A seta giratória na parte de cima de cada seção é um ::marker definido no <summary>. Assim como os itens de lista, o elemento <summary> é compatível com a list-style. propriedade abreviada e as propriedades longas dela, incluindo list-style-type. Você pode estilizar o triângulo de divulgação com CSS, incluindo alterar o marcador usado de um triângulo para qualquer outro tipo de marcador, incluindo: uma imagem com list-style-image.

Para aplicar outros estilos, use um seletor semelhante a details summary::marker. A O pseudoelemento ::marker aceita apenas um número limitado de estilos. Ao remover o ::marker e substituí-la pelo ::before, que é mais fácil de personalizar, prática comum, com estilos CSS alterando um pouco o estilo do conteúdo gerado com base na presença (ou ausência) do atributo open. Para remover o ícone do widget de divulgação, defina list-style: none ou defina o conteúdo. do marcador para none, mas sempre inclua indicadores visuais para informar aos usuários que enxergam que o conteúdo do resumo é um botão de alternância. que mostra e oculta o conteúdo após a ativação.

details summary::before {
  /* all the styles */
}
details[open] summary::before {
  /* changes applied when open only */
}

Este exemplo remove o marcador padrão e adiciona conteúdo gerado para criar um + quando os detalhes forem fechados e uma -. quando os detalhes estiverem disponíveis.

Se você quiser que o bloco de detalhes seja aberto por padrão, inclua o atributo open na tag de abertura <details>. Também é possível adicionar espaço entre cada caixa de diálogo e fazer a transição da rotação do marcador criado com conteúdo gerado para melhorar a aparência:

Como os erros são tratados

Se você não incluir uma <summary>, o navegador vai criar uma para você: com um marcador e a palavra "details". Este resumo faz parte de uma raiz paralela e, portanto, não terá estilos de resumo CSS de autor aplicados. Infelizmente, o Safari não inclui os detalhes na ordem de foco do teclado.

Se você incluir um <summary>, mas ele não for o primeiro elemento no <details>, o navegador ainda vai mostrar o resumo como deveria. Ele também não falhará se você incluir um link, marcador ou outro elemento interativo no resumo, mas os navegadores lidam com conteúdo interativo dentro dele de maneira diferente. Por exemplo, se você incluir um link em um resumo, alguns navegadores adicionará o resumo e o link à ordem de tabulação padrão, mas outros navegadores não se concentrarão no link por padrão. Se você clicar em um <label> aninhado em uma <summary>, alguns navegadores vão focar no controle de formulário associado. Outros navegadores vai focar no controle de formulário e abrir ou fechar o <details>.

Interface HTMLDetailsElement

Como todos os elementos HTML, HTMLDetailsElement herda todos propriedades, métodos e eventos de HTMLElement e adiciona a propriedade da instância open e um toggle evento. A propriedade HTMLDetailsElement.open é um booleano que reflete o atributo HTML open, indicando se o conteúdo do elemento (sem contar a <summary>) vai ser mostrado ao usuário. O evento de alternância é disparado quando o elemento <details> é aberto ou fechado. Para ouvir este evento, use addEventListener().

Se você quiser escrever um script para fechar os detalhes abertos quando o usuário abrir outros detalhes, remova o atributo "open" usando removeAttribute("open"):

Este é o único exemplo que usa JavaScript. Você provavelmente não precisará do JavaScript, com exceção dessa funcionalidade de fechar outros widgets de divulgação abertos.

Lembre-se de que <details> e <summary> podem ter estilos intensos e até ser usados para criar dicas de ferramentas. No entanto, se você for usar esses elementos semânticos para casos de uso em que a semântica nativa é incompatível, mantenha a acessibilidade. Na maioria das vezes, o HTML pode ser acessado por padrão. Como desenvolvedores, nosso trabalho é garantir que o conteúdo permaneça acessível.

Teste seu conhecimento

Teste seu conhecimento sobre detalhes e resumo.