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

CKTIS / JavaScript

HTMLProgressElement: propriedades max e value

`max` define a quantidade total de trabalho e `value` a quantidade concluída. Sem o atributo `value`, o progresso é indeterminado e não está a 0%.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

const p = document.createElement("progress");
p.max = total;
p.value = completed;
const fraction = p.position;
p.removeAttribute("value");

max e value são propriedades numéricas de leitura e escrita no DOM de um elemento <progress>, não funções de ECMAScript. max representa o trabalho total e value o trabalho concluído. Usa a mesma unidade para ambas, como bytes. O limite inferior é sempre 0; um atributo min não o altera.

Ao ler p.max, obténs um número positivo, ou 1 se o atributo max estiver ausente, não puder ser interpretado como número ou contiver um número não positivo. Atribuir um número positivo a p.max define o atributo; segundo a norma, os números finitos não positivos são ignorados. Atribuir NaN, Infinity ou -Infinity a qualquer das propriedades lança um TypeError.

Atribuir um número finito a p.value define o atributo value. A sua presença torna o progresso determinado: na leitura, um valor de atributo negativo ou não interpretável dá 0 e um valor acima de p.max dá p.max. Este ajuste aos limites não altera o texto do atributo devolvido por p.getAttribute("value").

Sem o atributo value, o progresso é indeterminado, embora p.value continue a devolver 0. A atribuição p.value = 0 indica progresso determinado a 0%; p.removeAttribute("value") volta a torná-lo indeterminado. A propriedade p.position, só de leitura, devolve -1 nesse estado e p.value / p.max quando o progresso é determinado.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>HTMLProgressElement: max and value</title>
</head>
<body>
  <script>
    const p = document.createElement("progress");
    console.log(`initial: max=${p.max}, value=${p.value}, position=${p.position}`);

    p.max = 8;
    p.value = 2;
    console.log(`partial: value=${p.value}, position=${p.position}`);

    p.value = 10;
    console.log(`over: attribute=${p.getAttribute("value")}, value=${p.value}, position=${p.position}`);

    p.removeAttribute("value");
    console.log(`removed: max=${p.max}, value=${p.value}, position=${p.position}`);
  </script>
</body>
</html>

Resultado

initial: max=1, value=0, position=-1
partial: value=2, position=0.25
over: attribute=10, value=8, position=1
removed: max=8, value=0, position=-1

Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta o resultado na consola de programador. A linha `over` mostra que o atributo mantém o texto `10`, enquanto a propriedade devolve `8`. O elemento não é inserido na página.

Lições relacionadas

  • JavaScript · Lição 6 · Avançado · Versão: 4

Fontes