Deprecazione dei blocchi Gutenberg: aggiorna senza rompere i contenuti

Riepilogo

Aggiornare un blocco Gutenberg spesso rompe i post esistenti che utilizzano la vecchia versione. Questo articolo mostra come usare la proprietà deprecated in block.json per mantenere la retrocompatibilità. Imparerai i passaggi esatti per catturare il markup corrente del blocco, definire una o più versioni deprecate e mappare correttamente gli attributi. Tratteremo sia i blocchi statici che dinamici, con esempi pratici. L'articolo mette anche in discussione l'assunto che la deprecazione sia sempre l'approccio migliore, discutendo quando una rottura netta potrebbe essere preferibile. Alla fine, sarai in grado di aggiornare i tuoi blocchi con sicurezza senza rompere i contenuti dei tuoi utenti.

Lo scenario di modifica che rompe

Sei mesi fa hai lanciato un blocco personalizzato per le testimonianze. Emette un semplice <div> con una citazione e un nome autore. Ora il tuo cliente vuole un nuovo design: l'autore deve apparire sopra la citazione, con una classe CSS diversa. Aggiorni la funzione save del blocco e render_callback. Provi su un nuovo post—sembra perfetto. Poi navighi verso un vecchio post che usa il blocco. Disastro: il testo della citazione è scomparso, l'autore è nel posto sbagliato e lo stile è fuori posto. Hai appena rotto ogni pagina che usa il blocco.

Questo è il classico problema della "modifica che rompe" nello sviluppo dei blocchi Gutenberg. I blocchi sono essenzialmente strutture dati combinate con markup. Quando cambi il markup, l'editor non può mappare automaticamente il vecchio contenuto alla nuova struttura. Il risultato è o un errore di validazione (il blocco diventa non valido) o—peggio—una corruzione silenziosa in cui il blocco viene renderizzato in modo errato.

Cos'è la deprecazione dei blocchi?

La deprecazione dei blocchi è il meccanismo integrato di Gutenberg per gestire i cambi di versione. Definendo un array deprecated nel block.json del tuo blocco, dici all'editor: "Se incontri un blocco che corrisponde a una di queste versioni più vecchie, trasformalo nella versione corrente." Ogni voce deprecata specifica i precedenti attributes, supports e la funzione save (o render_callback). Quando l'editor carica un vecchio blocco, scorre l'array deprecato in ordine e applica la prima trasformazione corrispondente.

Questa funzionalità è spesso sottoutilizzata perché gli sviluppatori presumono che non dovranno mai cambiare il markup di un blocco. Ma nei progetti reali, i requisiti evolvono. Se salti la deprecazione, o costringi gli utenti a eliminare e reinserire i blocchi (esperienza scadente) o mantieni due versioni separate del blocco (disordine). Il manuale ufficiale di WordPress per sviluppatori lo tratta nel Manuale dell'editor di blocchi, ma mancano guide pratiche.

Passaggio 1: Catturare lo stato corrente

Prima di apportare qualsiasi modifica, registra l'esatto output save (o render_callback per i blocchi dinamici) e gli attributes che il tuo blocco usa attualmente. Pensalo come fare una foto. Per i blocchi statici, salva il JSX restituito dalla funzione save. Per i blocchi dinamici, salva il markup PHP generato da render_callback.

Crea un nuovo file nel tuo plugin chiamato deprecated.js (o simile) e archivia lì la vecchia funzione save. In alternativa, mantieni le versioni deprecate direttamente nel file JavaScript principale del blocco. La chiave è preservare questo codice esattamente com'era quando il blocco è stato distribuito per la prima volta.

Passaggio 2: Definire le versioni deprecate

Nel tuo block.json, aggiungi un array deprecated. Ogni voce è un oggetto che può includere:

• attributes (oggetto): Le precedenti definizioni degli attributi.
• supports (oggetto): Eventuali impostazioni di supporto precedenti che sono cambiate.
• save (funzione o stringa): La precedente funzione save. Per i blocchi solo JavaScript, importerai la vecchia funzione. Per i blocchi dinamici renderizzati in PHP, puoi usare migrate e render_callback invece.
• migrate (funzione): Una funzione che mappa i vecchi attributi a quelli nuovi (opzionale).

Esempio:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

Nota: La funzione save in block.json è tipicamente definita in JavaScript. Se stai usando uno script esterno, dovrai accodarlo e fare riferimento al nome della funzione. In alternativa, puoi incorporare la funzione come stringa (anche se non è raccomandato per blocchi complessi).

Passaggio 3: Mappare gli attributi

Spesso cambi non solo il markup ma anche i nomi degli attributi o le sorgenti. Ad esempio, potresti passare da memorizzare l'autore come stringa semplice a un campo di testo ricco. In questi casi, usa la proprietà migrate per trasformare i vecchi attributi in quelli nuovi.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

Se non fornisci una funzione migrate, l'editor passerà semplicemente i vecchi attributi direttamente al nuovo blocco. Ciò potrebbe causare errori se i nomi degli attributi sono cambiati.

Passaggio 4: Testare con contenuti reali

Dopo aver definito la versione deprecata, testa accuratamente. Crea un nuovo post, inserisci il vecchio blocco (puoi simulare incollando il codice serializzato del blocco da un post esistente) e verifica che si converta nella nuova versione senza errori di validazione. Testa anche la modifica e il salvataggio del blocco convertito. Ripeti per più versioni deprecate se ne hai.

Per i blocchi dinamici, il processo è simile ma con una particolarità: la funzione save per un blocco dinamico tipicamente restituisce null (il blocco viene renderizzato via PHP). Nella voce deprecata, puoi impostare save al precedente markup statico che era usato prima di passare al rendering dinamico, o usare un render_callback in PHP che gestisca sia le vecchie che le nuove strutture degli attributi. Questo è più complesso ma fattibile.

Avvertenze e compromessi

La deprecazione è potente, ma ha svantaggi. Ogni versione deprecata aggiunge codice al tuo plugin. Nel tempo, potresti ritrovarti con una catena di cinque o sei versioni legacy che sono usate raramente ma devono essere mantenute. Il team core di WordPress consiglia di mantenere almeno due versioni indietro, ma oltre a ciò, potresti considerare una rottura netta se il numero di post interessati è piccolo.

Un'altra sfumatura: l'ordine delle voci deprecate è importante. L'editor scorre l'array dall'indice 0 verso l'alto e usa la prima corrispondenza. Se due versioni deprecate sono simili, potrebbe essere applicata quella sbagliata. Elenca sempre la versione deprecata più recente per prima (quella che precede direttamente la versione corrente).

Infine, la deprecazione non gestisce i contenuti modificati usando una modifica di stile a livello di sito (ad esempio, tramite theme.json). Se l'aspetto del tuo blocco si basava su stili globali che sono cambiati, la deprecazione non si adatterà. Potresti dover aggiungere uno script di migrazione che viene eseguito al salvataggio o tramite un hook di aggiornamento del plugin.

Quando la deprecazione non è la risposta

La maggior parte dei tutorial presenta la deprecazione come obbligatoria. In realtà, ci sono situazioni in cui una rottura netta è migliore. Se il tuo blocco è nuovo e usato solo in una manciata di post, aggiornare manualmente quelle poche istanze potrebbe essere più veloce che scrivere e testare il codice di deprecazione. Allo stesso modo, se il modello di dati sottostante del blocco è fondamentalmente diverso (ad esempio, stai unendo due blocchi in uno), la deprecazione potrebbe non essere abbastanza flessibile. In tal caso, scrivi uno script di migrazione una tantum che viene eseguito quando il plugin si aggiorna, convertendo i vecchi blocchi nel nuovo formato.

Un altro punto controverso: la deprecazione non dovrebbe essere usata come sostituto di una buona progettazione. Se prevedi cambi frequenti, progetta il tuo blocco con il versionamento in mente fin dall'inizio—ad esempio, memorizzando un attributo version e usando il rendering condizionale. Questo approccio, discusso in Oltre i blocchi di base, è più leggero della deprecazione ma richiede previdenza.

Conclusione

La deprecazione dei blocchi è uno strumento essenziale per qualsiasi sviluppatore Gutenberg serio. Ti permette di far evolvere i tuoi blocchi senza rompere i contenuti degli utenti. I passaggi chiave sono: catturare lo stato corrente, definire la versione deprecata in block.json, mappare gli attributi se necessario e testare con contenuti reali. Ma ricorda che la deprecazione comporta costi di manutenzione. A volte una rottura netta o un design con versionamento del blocco è più pragmatico. Usa la deprecazione strategicamente, non automaticamente, e i tuoi blocchi rimarranno solidi attraverso molti aggiornamenti.

Per una prospettiva più ampia sulla creazione di plugin manutenibili, vedi Costruire plugin WordPress robusti. E se sei nuovo allo sviluppo di blocchi, Oltre i blocchi di base ti aiuterà a iniziare.