Aggiornamenti parziali dichiarativi

Pubblicazione: 19 maggio 2026, Ultimo aggiornamento: 8 settembre 2026

Il web ha fatto molta strada dai suoi esordi come mezzo statico basato sui documenti. Le app web moderne e avanzate vengono utilizzate da tutti per molti motivi, dalla comunicazione, all'acquisto, alla fruizione di contenuti avanzati, fino alla gestione delle nostre vite complesse.

L'HTML, nonostante tutti i suoi progressi, viene ancora fornito in ordine dall'alto verso il basso, con poca considerazione per quando i contenuti sono pronti o quando l'utente li consuma. Il CSS consente di modificare l'ordine dei contenuti, ma spesso con effetti collaterali significativi sull'accessibilità. JavaScript ti consente di manipolare il DOM tramite varie API per liberarti in qualche modo da questa situazione, ma spesso richiedono una sintassi dettagliata o la creazione di alberi DOM da inserire in HTML.

Le prestazioni sono incredibilmente importanti per il web, data la natura client-server del mezzo. Tuttavia, spesso vengono effettuate scelte non ottimali per aggirare questa natura sequenziale dell'HTML, il che rallenta le prestazioni. Ciò include l'attesa che l'intera pagina sia pronta o l'utilizzo di un framework pesante per fornire i componenti in modo asincrono. La popolarità dei framework JavaScript dimostra che gli sviluppatori web preferiscono un modello basato su componenti rispetto al rigido modello mentale dei documenti delle origini del web.

Il team di Chrome ha preso in considerazione questo problema e ha sviluppato nuove aggiunte alla piattaforma web con il nome di Aggiornamenti parziali dichiarativi.

I primi due nuovi set di API semplificano la pubblicazione di HTML in modo meno lineare, sia fuori ordine nel documento HTML stesso sia tramite modi più semplici per inserire dinamicamente l'HTML nei documenti esistenti utilizzando nuove API JavaScript. Sono disponibili anche polyfill per consentirti di utilizzare subito queste nuove API, anche nei browser che non le supportano ancora.

Streaming fuori ordine

Browser Support

  • Chrome: 150.
  • Edge: 150.
  • Firefox: not supported.
  • Safari: not supported.

Source

Il primo insieme di modifiche riguarda le nuove API di streaming fuori ordine che utilizzano segnaposto per le istruzioni di elaborazione e l'elemento HTML <template> con l'attributo for. Ad esempio:

<div>
  <?marker name="placeholder">
</div>

...

<template for="placeholder">
  Here is some <em>HTML content</em>!
</template>

Le istruzioni di elaborazione esistono da molto tempo in XML, ma sono state trattate come commenti in HTML e ignorate. Questa nuova API cambia la situazione e introduce le istruzioni di elaborazione in HTML. Ad esempio, quando il browser vede l'istruzione di elaborazione <?marker name="placeholder">, non esegue alcuna azione immediata, come prima, ma può essere richiamata in un secondo momento.

L'elemento <template> con l'attributo for cerca le istruzioni di elaborazione corrispondenti con un attributo name e sostituisce i contenuti. In questo caso, dopo l'analisi, il DOM risulta come segue (ignorando alcune differenze di spazi vuoti):

<div>
  Here is some <em>HTML content</em>!
</div>

Oltre all'attributo <?marker> per le sostituzioni, sono disponibili anche gli indicatori di intervallo <?start> e <?end> che consentono di mostrare contenuti segnaposto temporanei prima dell'elaborazione del template:

<div>
  <?start name="another-placeholder">
  Loading…
  <?end>
</div>

...

<template for="another-placeholder">
  Here is some <em>HTML content</em>!
</template>

In questo caso, viene visualizzata una stringa Loading… finché non viene visualizzato <template>, che viene poi sostituito con i nuovi contenuti.

È anche possibile includere istruzioni di elaborazione nei modelli per consentire più aggiornamenti:

<ul id="results">
  <?start name="results">
  Loading…
  <?end>
</ul>

...

<template for="results">
  <li>Result One</li>
  <?marker name="results">
</template>

...

<template for="results">
  <li>Result Two</li>
  <?marker name="results">
</template>

...

Dopo l'analisi e l'elaborazione, il codice HTML risultante è il seguente:

<ul id="results">
  <li>Result One</li>
  <li>Result Two</li>
  <?marker name="results">
</ul>

Con l'istruzione di elaborazione finale alla fine, nel caso in cui vengano aggiunti altri segnaposto <template for="results"> al documento in un secondo momento.

Perché utilizzare le istruzioni di elaborazione anziché gli elementi HTML standard?

Questa è una domanda comune per chi utilizza questa API per la prima volta, con suggerimenti per utilizzare gli elementi <slot> o anche <template> stessi. Una versione iniziale di questa proposta funzionava con elementi HTML standard, ma le istruzioni di elaborazione sono state modificate man mano che il design veniva perfezionato. Le istruzioni di elaborazione consentono di applicare patch senza influire sul DOM. In questo modo, può essere utilizzato in <head>, ad esempio per gli aggiornamenti di <title>, o anche all'interno di altri elementi come <table> (ad esempio per aggiungere righe aggiuntive facoltative).

Sebbene la sintassi non sia familiare a molti sviluppatori web, le istruzioni di elaborazione offrono una flessibilità molto maggiore con meno possibilità di problemi di compatibilità con le versioni precedenti. Sono già utilizzati in XML e, grazie a questa proposta, ora fanno parte dello standard HTML.

Demo

In questo video, un'applicazione di base per album fotografici viene implementata con lo streaming HTML:

Demo di un album fotografico implementato con streaming fuori sequenza (fonte)

Sia lo stato che le foto vengono inseriti in streaming nell'HTML dopo il layout iniziale.

Casi d'uso

Esistono molti casi d'uso per questo HTML di applicazione di patch fuori ordine se abbinato all'HTML di streaming:

  • Architettura a isole. Un pattern comune reso popolare da framework come Astro è l'architettura a isole, in cui i componenti vengono idratati in modo indipendente sopra l'HTML statico. L'API <template for> consente di gestire i contenuti statici in modo simile direttamente in HTML. I framework JavaScript possono utilizzare questa funzionalità anche per isole più interattive o per gestire i componenti.
  • Pubblica i contenuti quando sono pronti. Grazie a questa architettura a isole, i contenuti possono essere trasmessi in streaming quando sono pronti, anziché essere trattenuti per contenuti che richiedono un'elaborazione aggiuntiva, ad esempio una ricerca nel database. Sebbene molte piattaforme consentano lo streaming di HTML, la natura sequenziale dell'HTML fa sì che i contenuti vengano spesso trattenuti o che si debba ricorrere a complesse manipolazioni del DOM JavaScript. Ora puoi pubblicare i contenuti statici durante l'attesa e poi inserire contenuti più costosi e dinamici alla fine dello stream HTML.
  • Il codice HTML può essere pubblicato nell'ordine ottimale per il rendimento del caricamento pagina. Facendo un ulteriore passo avanti, puoi modificare l'ordine anche quando è pronto. Ad esempio, i mega menu sono una funzionalità di navigazione comune che contiene molto codice HTML che l'utente non vedrà finché la pagina non diventa interattiva. Questo grande blocco di HTML può essere pubblicato in un secondo momento nel documento HTML per dare la priorità all'HTML più importante necessario per il caricamento iniziale della pagina. L'ordine non è più un ostacolo con l'HTML.

Questi sono solo alcuni casi d'uso e non vediamo l'ora di scoprire per cosa gli sviluppatori utilizzeranno questa nuova API.

Limitazioni e particolarità

L'API include alcune limitazioni e sottigliezze di cui tenere conto:

  • <template for> può aggiornare le istruzioni di elaborazione solo all'interno dello stesso elemento principale per motivi di sicurezza. L'aggiunta di <template for> direttamente all'elemento <body> consente di accedere all'intero documento (incluso <head>).
  • L'istruzione di elaborazione <?end> è facoltativa e, se manca, i contenuti tra l'elemento <?start> e la fine dell'elemento contenitore verranno sostituiti.
  • Anche lo spostamento delle istruzioni di elaborazione dopo l'avvio dello streaming di un <template for> può avere conseguenze impreviste, con i nuovi contenuti che continuano a essere trasmessi in streaming nella vecchia posizione.
  • Tieni presente che quando inserisci <template for> in modo dinamico con un metodo come setHTML o la proprietà innerHTML, l'elemento "principale" del modello quando viene analizzato è un frammento di documento intermedio. Ciò significa che l'inserimento di HTML con questi metodi non può modificare il DOM esistente e l'applicazione di patch avviene "in loco" all'interno del frammento. Tuttavia, quando si esegue lo streaming utilizzando metodi come streamHTMLUnsafe (descritti di seguito), non esiste un frammento intermedio, quindi i modelli possono sostituire i contenuti esistenti.

Stato della standardizzazione

L'attributo <template for> fa parte dello standard HTML, ma non è ancora supportato in tutti i browser.

Potenziali aggiunte future

Alcune potenziali aggiunte future in fase di valutazione includono:

  • Include lato client. Ad esempio, <template for="footer" src="/partials/footer.html"> o anche senza applicare patch <template src="/partials/footer.html">. Per maggiori dettagli, consulta la spiegazione. Questa opzione è disponibile dietro il flag chrome://flags/#enable-experimental-web-platform-features.
  • Evitare di sovrascrivere i contenuti che non cambieranno. Questo obiettivo può essere raggiunto con un numero di revisione dei contenuti o con il controllo delle versioni. In questo modo, lo stato verrebbe mantenuto tra le modifiche del percorso o altri aggiornamenti, anziché reimpostare i contenuti.
  • Sanitizing while patching. Ad esempio, <template for=icon safe><svg id="from-untrusted-source">...</svg></template>

Polyfill

Il team di Chrome ha rilasciato un template-for-polyfill disponibile su npm per consentire ai siti di utilizzare subito questa nuova funzionalità, anche prima che venga implementata in altri browser.

Esistono alcune limitazioni, in quanto non può aggiornare direttamente gli analizzatori sintattici HTML del browser, ma i casi d'uso più comuni sono coperti. I siti devono comunque eseguire i test in altri browser.

Metodi di inserimento e streaming HTML rinnovati

Non tutti i contenuti possono essere pubblicati come HTML. Una seconda parte del lavoro svolto da Chrome in quest'area mira a semplificare l'aggiornamento dei contenuti con JavaScript.

Esistono già diversi modi per inserire dinamicamente l'HTML in un documento esistente utilizzando JavaScript:

  • setHTML
  • setHTMLUnsafe
  • innerHTML e outerHTML
  • createContextualFragment
  • insertAdjacentHTML

Tuttavia, funzionano tutti in modi leggermente diversi, con sfumature e differenze che gli sviluppatori potrebbero non considerare sempre:

  • I nuovi contenuti sovrascrivono o vengono aggiunti?
  • Sanitizzano l'HTML potenzialmente pericoloso, ad esempio eseguendo l'escape dei tag <script>?
  • In caso contrario, <script> dovrebbe essere eseguito?
  • Come funzionano con i Trusted Types?

Pochi sviluppatori potrebbero esaminare onestamente queste API e rispondere con sicurezza a queste domande per ciascuna di esse.

Una grande limitazione è che possono essere utilizzati solo per un insieme completo di HTML noto in anticipo, quando sono state effettuate chiamate per consentire lo streaming dell'HTML. In pratica, ciò significa che devi scaricare l'intero contenuto prima di inserirlo, quando uno dei punti di forza dell'HTML è la possibilità di trasmettere i contenuti in streaming immediatamente. Questo problema può essere aggirato in modo limitato suddividendo i payload o utilizzando metodi deprecati e complessi come document.write, che però introducono i propri problemi.

Un nuovo set di API statiche e di streaming

Browser Support

  • Chrome: behind a flag.
  • Edge: behind a flag.
  • Firefox: not supported.
  • Safari: not supported.

Chrome ha lavorato a una suite di nuove API ed estensioni per le API setHTML e setHTMLUnsafe esistenti che semplificano questa operazione, oltre a introdurre la funzionalità di streaming.

Queste funzionalità sono pronte per i test degli sviluppatori a partire da Chrome 148 utilizzando il flag chrome://flags/#enable-experimental-web-platform-features e il lancio è previsto in Chrome 155.

Esistono metodi per impostare o sostituire, nonché metodi per inserire contenuti prima o dopo l'HTML esistente. Ogni metodo ha un equivalente per lo stream:

Azione Statico Streaming
Imposta i contenuti HTML dell'elemento setHTML(html, options); streamHTML(options);
Sostituisci l'intero elemento con questo codice HTML replaceWithHTML(html, options); streamReplaceWithHTML(options);
Aggiungi l'HTML prima dell'elemento beforeHTML(html, options); streamBeforeHTML(options);
Aggiungi l'HTML come primo elemento secondario dell'elemento prependHTML(html, options); streamPrependHTML(options);
Aggiungi l'HTML come ultimo elemento secondario dell'elemento appendHTML(html, options); streamAppendHTML(options);
Aggiungi l'HTML dopo l'elemento afterHTML(html, options); streamAfterHTML(options);
I nuovi metodi di inserimento e streaming

Esistono anche versioni Unsafe che verranno trattate a breve. Anche se potrebbero sembrare molti, soprattutto se si aggiungono gli equivalenti Unsafe, la convenzione di denominazione coerente rende più evidente la funzione di ciascuno rispetto ai metodi non correlati menzionati in precedenza.

Le versioni statiche accettano il nuovo HTML come argomento di stringa DOM, insieme a opzioni facoltative:

const newHTML = "<p>This is a new paragraph</p>";
const contentElement = document.querySelector('#content-to-update');

contentElement.setHTML(newHTML);

Le versioni di streaming funzionano con l'API Streams, ad esempio con un getWriter():

const contentElement = document.querySelector('#content-to-update');
const writer = contentElement.streamHTMLUnsafe().getWriter();

// Example stream of updating content
while (true) {
  await writer.write(`<p>${++i}</p>`);
  await new Promise((resolve) => setTimeout(resolve, 1000));
}

writer.close();

In alternativa, da una risposta di recupero utilizzando le catene di pipe:

const contentElement = document.querySelector('#content-to-update');
const response = await fetch('/api/content.html');

response.body
  .pipeThrough(new TextDecoderStream())
  .pipeTo(contentElement.streamHTMLUnsafe());

textStream() metodo di convenienza

Browser Support

  • Chrome: 151.
  • Edge: 151.
  • Firefox: not supported.
  • Safari: not supported.

Source

È stato aggiunto anche un metodo di convenienza textStream, con cui puoi eseguire lo streaming direttamente senza dover eseguire il passaggio intermedio TextDecoderStream():

const contentElement = document.querySelector('#content-to-update');
const response = await fetch('/api/content.html');

response.textStream().pipeTo(contentElement.streamHTMLUnsafe());

options

L'argomento options consente di specificare un sanitizer personalizzato, che per impostazione predefinita è default, ovvero la configurazione predefinita del sanitizer. Si utilizza nel seguente modo:

const newHTML = '<p>This is a new paragraph</p>';
const contentElement = document.querySelector('#content-to-update');

// Only allows basic formatting
const basicFormattingSanitzer = new Sanitizer({ elements: ['em', 'i', 'b', 'strong'] });

contentElement.setHTML(newHTML, {sanitizer: basicFormattingSanitzer});

Metodi "non sicuri"

Esistono anche versioni "non sicure" di ciascuna API:

Azione Statico Streaming
Imposta i contenuti HTML dell'elemento setHTMLUnsafe(html,options); streamHTMLUnsafe(options);
Sostituisci l'intero elemento con questo codice HTML replaceWithHTMLUnsafe(html, options); streamReplaceWithHTMLUnsafe(options);
Aggiungi l'HTML prima dell'elemento beforeHTMLUnsafe(html, options); streamBeforeHTMLUnsafe(options);
Aggiungi l'HTML come primo elemento secondario dell'elemento prependHTMLUnsafe(html, options); streamPrependHTMLUnsafe(options);
Aggiungi l'HTML come ultimo elemento secondario dell'elemento appendHTMLUnsafe(html, options); streamAppendHTMLUnsafe(options);
Aggiungi l'HTML dopo l'elemento afterHTMLUnsafe(html, options); streamAfterHTMLUnsafe(options);
Metodi di inserimento e flussi di dati "non sicuri"

Questi metodi "non sicuri" disattivano il sanitizer per impostazione predefinita e, se vuoi, puoi specificare un sanitizer personalizzato. Questi metodi consentono anche di eseguire gli script con un'opzione runScripts facoltativa, che per impostazione predefinita è false.

Come setHTML, setHTMLUnsafe è un metodo esistente, ma è stato aggiunto il parametro delle opzioni runScripts per consentirne l'utilizzo con l'esecuzione dello script:

const newHTML = `<p>This is a new paragraph</p>
                 <script src=script.js></script>`;
const contentElement = document.querySelector('#content-to-update');

contentElement.setHTMLUnsafe(newHTML, {runScripts: true});

La dicitura "unsafe" nel metodo serve a ricordare agli sviluppatori il potenziale rischio e come potrebbero voler sanificare o limitare gli script, non a dire che questi metodi non dovrebbero essere utilizzati.

Il livello di "non sicurezza" dipende dal livello di affidabilità degli input. I metodi statici Unsafe funzionano tutti con la stringa DOM o TrustedHTML come argomenti html e consentono anche l'utilizzo di sanitizer. Tuttavia, con runScript l'intero intento è consentire gli script, motivo per cui per impostazione predefinita non viene utilizzato alcun sanitizer.

Casi d'uso

Queste nuove API semplificano l'aggiunta di HTML alle pagine esistenti da parte degli sviluppatori, aggiungendo nuove API con nomi e opzioni coerenti. Le API di streaming offrono i vantaggi in termini di prestazioni di non dover attendere che tutti i nuovi contenuti siano disponibili sulla piattaforma.

I casi d'uso includono:

  • Streaming dinamico di aggiornamenti di contenuti di grandi dimensioni nelle app a pagina singola. Come accennato in precedenza, un grande svantaggio dell'attuale architettura SPA è che non sfrutta la natura di streaming dei caricamenti HTML iniziali, almeno fino ad ora.
  • Inserimento di contenuti comuni come i piè di pagina HTML. L'utilizzo delle API JavaScript consente di estrarre i partial e inserirli nella pagina, sfruttando la memorizzazione nella cache, anziché ripeterli in ogni pagina inviata. Tuttavia, data la dipendenza da JavaScript per l'esecuzione, questo attributo deve essere utilizzato solo per i contenuti che non saranno visibili nel caricamento iniziale.

Questi sono solo un paio di esempi e non vediamo l'ora di scoprire cosa inventerete.

Limitazioni e particolarità

Queste nuove API includono anche alcune limitazioni e sottigliezze di cui tenere conto:

  • L'integrazione dello streaming con l'API Trusted Types richiede l'utilizzo di un nuovo metodo createParserOptions che consente di inserire un sanitizer in qualsiasi operazione di impostazione HTML. Per maggiori dettagli sull'integrazione dei tipi attendibili, consulta la spiegazione.
  • Analogamente a <template for>, lo spostamento di elementi in cui viene eseguito lo streaming può creare conseguenze impreviste o errori di streaming.
  • streamHTMLUnsafe funziona in modo più simile al parser principale in molti modi, tra cui l'elaborazione delle istruzioni <template for> man mano che vengono aggiunte al documento principale e il rinvio degli script defer alla fine dello stream.

Stato della standardizzazione

I metodi di inserimento e streaming più recenti sono in fase di aggiunta allo standard HTML, ma non sono ancora supportati in tutti i browser.

Polyfill

Il team di Chrome ha rilasciato un html-setters-polyfill disponibile su npm per consentire ai siti di utilizzare subito questa nuova funzionalità, anche prima che venga implementata in altri browser.

Tieni presente che questo polyfill non esegue lo streaming, ma memorizza nel buffer e applica i dati al termine. Si tratta più di un polyfill per la forma dell'API che per la funzionalità.

Inoltre, l'impostazione dei contenuti sicuri dipende da setHTML e dall'API Sanitizer, che non è supportata in Safari.

Utilizzali insieme

Anche se si tratta di due API separate, la vera potenza deriva dalla loro combinazione. Se trasmetti in streaming nuovi elementi <template for> nell'HTML, puoi aggiornare dinamicamente diverse parti dei contenuti senza dover scegliere come target ciascuna parte con riferimenti JavaScript separati al DOM.

Un caricamento pagina di base in stile SPA potrebbe essere implementato caricando una pagina di struttura con istruzioni di elaborazione e quindi trasmettendo in streaming i modelli di ogni nuova pagina nella parte inferiore del codice HTML per inserirli in queste istruzioni di elaborazione.

Senza dubbio ci sono più potenzialità e casi d'uso per entrambe queste API, quindi non lasciare che la nostra (limitata!) immaginazione ti freni. Semplificando la gestione degli aggiornamenti parziali, puoi ridurre parte del codice boilerplate, semplificare gli aggiornamenti e sbloccare nuove potenzialità per il web.

Chrome sta lavorando ad altre API nell'ambito del progetto Declarative Partial Updates, ma siamo felici di mettere a tua disposizione queste prime due. Ti aggiorneremo e ti faremo sapere quando saranno disponibili ulteriori informazioni in questo spazio.