Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / HTML

ontoggle — gerir alterações do estado de abertura

O atributo ontoggle contém JavaScript que gere o evento toggle depois de o estado de abertura de um elemento mudar. Entre os elementos relevantes estão details, dialog e os que funcionam como popovers. O atributo não abre nem fecha um elemento por si só.

Versão: WHATWG HTML Living Standard; index snapshot date recorded separately

Sintaxe

ontoggle="JavaScript statements"
element.ontoggle = (event) => { /* handler */ };
element.addEventListener("toggle", (event) => { /* listener */ });

ontoggle é um atributo de gestão do evento toggle; o seu valor é código JavaScript, não um valor booleano. Está disponível nos elementos HTML, mas adicioná-lo não cria um comportamento de expansão. O evento é gerado quando muda o estado de details, dialog e dos elementos que funcionam como popover.

No código do atributo, event refere-se ao evento e this ao elemento que o gere. O objeto ToggleEvent disponibiliza oldState e newState, cujos valores são "open" ou "closed". toggle comunica uma alteração já efetuada: não propaga na fase de bubbling e não pode ser cancelado. preventDefault() não desfaz a alteração.

A notificação é colocada numa fila e alterações rápidas e sucessivas podem ser agrupadas num único evento. Por isso, não pressuponhas que o gestor é chamado uma vez por cada alteração de estado. beforetoggle é um evento separado, emitido antes de uma alteração pelos mecanismos que o suportam; não é uma forma anterior de toggle disponível para todas as alterações de details.

Em JavaScript, podes atribuir uma função à propriedade element.ontoggle; uma nova atribuição substitui a função anterior nesse espaço de gestão. addEventListener("toggle", handler) permite registar ouvintes independentes. O exemplo usa o atributo para mostrar a sua sintaxe: o script abre details e o gestor atualiza o texto quando o evento é entregue.

Exemplos

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>ontoggle example</title>
<details id="panel" ontoggle="document.getElementById('status').textContent = event.oldState + ' -> ' + event.newState">
  <summary>Details</summary>
  <p>Extra information.</p>
</details>
<pre id="status">Waiting</pre>
<script>
  document.getElementById('panel').open = true;
</script>
</html>

Resultado

closed -> open

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes