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

CKTIS / HTML

dialog — uma caixa de diálogo nativa

O elemento `dialog` representa uma janela temporária para realizar uma tarefa ou apresentar informações. O método `show()` apresenta-a sem modalidade, enquanto `showModal()` bloqueia a interação com o resto do documento.

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

Sintaxe

<dialog>…</dialog>
dialog.show();
dialog.showModal();
dialog.close(result);

dialog é uma janela para uma interação breve com a aplicação, não um substituto de um menu ou de uma dica de contexto (tooltip). São necessárias as etiquetas de abertura e de fecho. Sem open, não é apresentada por predefinição; open, por si só, não cria uma caixa de diálogo modal.

show() apresenta uma caixa de diálogo não modal. showModal() coloca-a na camada superior; o resto do documento fica inativo (inert). O elemento tem de estar ligado ao documento. Chamar showModal() numa caixa de diálogo já aberta sem modalidade provoca InvalidStateError.

Forneça um nome significativo, por exemplo através de aria-labelledby, e um botão de fecho visível. Defina o foco inicial com autofocus num controlo adequado. Não defina tabindex em dialog.

close(result) fecha a caixa de diálogo, guarda a cadeia fornecida em returnValue e provoca um evento close. requestClose(result) desencadeia primeiro o evento cancelável cancel; preventDefault() pode impedir o fecho. Não remova open manualmente, pois isso contorna o ciclo de fecho correto. closedby controla o fecho automático: any também permite cliques fora da caixa, closerequest permite pedidos de fecho e none não permite nenhum deles. Sem este atributo, as caixas modais processam pedidos de fecho e as não modais não o fazem.

Exemplos

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Dialog example</title>
<button id="launch" type="button">Open</button>
<dialog id="box" aria-labelledby="heading">
  <h2 id="heading">Confirmation</h2>
  <p>Close this dialog to continue.</p>
  <button id="finish" type="button" autofocus>OK</button>
</dialog>
<p id="status" role="status">Ready</p>
<script>
  const box = document.getElementById('box');
  const status = document.getElementById('status');
  document.getElementById('launch').addEventListener('click', () => {
    box.returnValue = '';
    box.showModal();
  });
  document.getElementById('finish').addEventListener('click', () => {
    box.close('confirmed');
  });
  box.addEventListener('close', () => {
    status.textContent = box.returnValue === 'confirmed'
      ? 'Result: confirmed'
      : 'Result: dismissed';
  });
</script>
</html>

Resultado

Result: confirmed

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