CKTIS / JavaScript
HTMLProgressElement: progresso de uma tarefa com max e value
HTMLProgressElement expõe as propriedades max e value de um elemento progress. Estas descrevem a quantidade total de trabalho e a parte concluída, permitindo distinguir um progresso conhecido igual a zero de um estado em que o grau de conclusão é desconhecido.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
progress.max = total;
progress.value = completed;
progress.position;
progress.removeAttribute("value");HTMLProgressElement é a interface DOM do elemento progress, que apresenta o progresso de uma tarefa. Progress max/value abrange duas propriedades numéricas: max descreve a quantidade total de trabalho e value a parte concluída. Trata-se de uma API Web do navegador, não de uma funcionalidade de uma edição específica de ECMAScript; a mera presença de Node 24 não comprova a sua disponibilidade.
max tem de ser superior a 0 e o valor predefinido é 1. value representa o progresso de 0 a max, pelo que não tem necessariamente de corresponder a uma percentagem. Com max = 8 e value = 3, estão concluídas três de oito unidades. O valor mínimo é sempre 0; o elemento progress não suporta um atributo min.
Quando o atributo value está presente, o progresso é determinado. A propriedade só de leitura position devolve então value / max. Se o atributo value estiver ausente, o progresso é indeterminado: a leitura de value devolve 0, mas position devolve -1. Atribuir value = 0 significa que há um progresso conhecido igual a zero, não um estado indeterminado. Use removeAttribute("value") para regressar a esse estado.
Forneça um nome acessível através de um elemento label associado, de aria-label ou de aria-labelledby; o texto dentro do elemento não substitui uma etiqueta. A MDN classifica a interface como amplamente disponível nos navegadores desde julho de 2015. O exemplo cria um elemento desligado do documento e demonstra a diferença entre progresso conhecido igual a zero e progresso desconhecido, sem animações nem dependências temporais.
Exemplos
(() => {
const progress = document.createElement("progress");
progress.setAttribute("aria-label", "Task progress");
progress.max = 8;
progress.value = 3;
console.log(`max=${progress.max}, value=${progress.value}, position=${progress.position}`);
progress.value = 0;
console.log(`zero: value=${progress.value}, position=${progress.position}`);
progress.removeAttribute("value");
console.log(`unknown: value=${progress.value}, position=${progress.position}`);
})();Resultado
max=8, value=3, position=0.375 zero: value=0, position=0 unknown: value=0, position=-1
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.