Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

HTMLProgressElement: avanzamento di un’attività con max e value

HTMLProgressElement espone le proprietà max e value di un elemento progress. Descrivono la quantità totale di lavoro e la parte completata e permettono di distinguere un avanzamento noto pari a zero da uno stato in cui il livello di completamento è sconosciuto.

Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintassi

progress.max = total;
progress.value = completed;
progress.position;
progress.removeAttribute("value");

HTMLProgressElement è l’interfaccia DOM dell’elemento progress, che mostra l’avanzamento di un’attività. Progress max/value comprende due proprietà numeriche: max descrive la quantità totale di lavoro e value la parte completata. È un’API Web del browser, non una funzionalità di una specifica edizione di ECMAScript; la sola presenza di Node 24 non ne dimostra la disponibilità.

max deve essere maggiore di 0 e il valore predefinito è 1. value rappresenta l’avanzamento da 0 a max, quindi non indica necessariamente una percentuale. Con max = 8 e value = 3, sono state completate tre unità su otto. Il valore minimo è sempre 0; l’elemento progress non supporta un attributo min.

Quando l’attributo value è presente, l’avanzamento è determinato. La proprietà di sola lettura position restituisce quindi value / max. Se l’attributo value è assente, l’avanzamento è indeterminato: leggendo value si ottiene 0, mentre position restituisce -1. Assegnare value = 0 indica un avanzamento noto pari a zero, non uno stato indeterminato. Usa removeAttribute("value") per tornare a tale stato.

Fornisci un nome accessibile tramite un elemento label associato, aria-label oppure aria-labelledby; il testo all’interno dell’elemento non sostituisce un’etichetta. MDN classifica l’interfaccia come ampiamente disponibile nei browser da luglio 2015. L’esempio crea un elemento scollegato e mostra la differenza tra un avanzamento noto pari a zero e uno sconosciuto, senza animazioni né dipendenze temporali.

Esempi

(() => {
  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}`);
})();

Risultato

max=8, value=3, position=0.375
zero: value=0, position=0
unknown: value=0, position=-1

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti