Deprecierea Blocurilor Gutenberg: Actualizează Fără a Distruge Conținutul

Rezumat

Actualizarea unui bloc Gutenberg strică adesea postările existente care folosesc versiunea veche. Acest articol îți arată cum să folosești proprietatea deprecated din block.json pentru a menține compatibilitatea inversă. Vei învăța pașii exacti pentru a captura marca actuală a blocului, a defini una sau mai multe versiuni depreciate și a mapa corect atributele. Vom acoperi atât blocurile statice, cât și cele dinamice, cu exemple practice. Articolul contestă și presupunerea că deprecierea este întotdeauna cea mai bună abordare, discutând când o rupere curată ar putea fi mai bună. Până la sfârșit, vei putea actualiza blocurile cu încredere fără a distruge conținutul utilizatorilor tăi.

Scenariul Schimbării Care Strică

Ai lansat acum șase luni un bloc personalizat de testimoniale. Acesta afișează un simplu <div> cu un citat și un nume de autor. Acum clientul tău dorește un nou design: autorul să apară deasupra citatului, cu o clasă CSS diferită. Actualizezi funcția save a blocului și render_callback. Testezi pe o postare nouă—arată grozav. Apoi navighezi la o postare veche care folosește blocul. Dezastru: textul citatului a dispărut, autorul este în locul greșit, iar stilizarea este dereglată. Tocmai ai stricat fiecare pagină care folosește blocul.

Aceasta este problema clasică de "schimbare care strică" în dezvoltarea blocurilor Gutenberg. Blocurile sunt în esență structuri de date combinate cu marcare. Când schimbi marcarea, editorul nu poate mapa automat conținutul vechi la noua structură. Rezultatul este fie o eroare de validare (blocul devine invalid), fie—mai rău—o corupere tăcută unde blocul se afișează incorect.

Ce Este Deprecierea Blocurilor?

Deprecierea blocurilor este mecanismul încorporat al Gutenberg pentru gestionarea schimbărilor de versiune. Prin definirea unui tablou deprecated în block.json-ul blocului tău, îi spui editorului: "Dacă întâlnești un bloc care se potrivește cu una dintre aceste versiuni mai vechi, transformă-l în versiunea curentă." Fiecare intrare depreciată specifică attributes, supports și funcția save anterioare (sau render_callback). Când editorul încarcă un bloc vechi, parcurge tabloul depreciat în ordine și aplică prima transformare care se potrivește.

Această caracteristică este adesea subutilizată deoarece dezvoltatorii presupun că nu vor avea nevoie niciodată să schimbe marcarea unui bloc. Dar în proiecte reale, cerințele evoluează. Dacă sari peste depreciere, fie îi forțezi pe utilizatori să șteargă și să reinsereze blocurile (experiență slabă), fie menții două versiuni separate ale blocului (dezordonat). Manualul oficial al dezvoltatorului WordPress acoperă acest subiect în Block Editor Handbook, dar lipsesc ghidurile practice.

Pasul 1: Captează Starea Curentă

Înainte de a face orice schimbare, înregistrează exact ieșirea save (sau render_callback pentru blocurile dinamice) și attributes pe care blocul tău le folosește în prezent. Gândește-te ca la a face o imagine de moment. Pentru blocurile statice, salvează JSX-ul returnat de funcția save. Pentru blocurile dinamice, salvează marca PHP generată de render_callback.

Creează un fișier nou în pluginul tău numit deprecated.js (sau similar) și stochează funcția save veche acolo. Alternativ, păstrează versiunile depreciate direct în fișierul JavaScript principal al blocului. Cheia este să păstrezi acest cod exact așa cum era când blocul a fost implementat pentru prima dată.

Pasul 2: Definește-ți Versiunile Depreciate

În block.json-ul tău, adaugă un tablou deprecated. Fiecare intrare este un obiect care poate include:

• attributes (obiect): Definițiile anterioare ale atributelor.
• supports (obiect): Orice setări de suport anterioare care s-au schimbat.
• save (funcție sau șir): Funcția save anterioară. Pentru blocurile doar JavaScript, vei importa funcția veche. Pentru blocurile dinamice randate prin PHP, poți folosi migrate și render_callback în schimb.
• migrate (funcție): O funcție care mapează atributele vechi la cele noi (opțional).

Exemplu:

"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>"
  }
]

Notă: Funcția save din block.json este de obicei definită în JavaScript. Dacă folosești un script extern, va trebui să îl înregistrezi și să faci referire la numele funcției. Alternativ, poți include funcția ca șir (deși nu este recomandat pentru blocuri complexe).

Pasul 3: Mapează Atributele

Adesea, schimbi nu doar marcarea, ci și numele atributelor sau sursele. De exemplu, ai putea trece de la stocarea autorului ca șir simplu la un câmp de text bogat. În astfel de cazuri, folosește proprietatea migrate pentru a transforma atributele vechi în cele noi.

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

Dacă nu furnizezi o funcție migrate, editorul va transmite pur și simplu atributele vechi direct noului bloc. Acest lucru poate cauza erori dacă numele atributelor s-au schimbat.

Pasul 4: Testează cu Conținut Real

După ce ai definit versiunea depreciață, testează temeinic. Creează o postare nouă, inserează blocul vechi (poți simula prin lipirea codului serializat al blocului dintr-o postare existentă) și verifică dacă se convertește la noua versiune fără erori de validare. De asemenea, testează editarea și salvarea blocului convertit. Repetă pentru mai multe versiuni depreciate dacă ai.

Pentru blocuri dinamice, procesul este similar, dar cu o întorsătură: funcția save pentru un bloc dinamic returnează de obicei null (blocul se afișează prin PHP). În intrarea depreciață, poți fie seta save la marcarea statică anterioară care era folosită înainte de a trece la randarea dinamică, fie folosi un render_callback în PHP care gestionează atât structurile de atribute vechi, cât și pe cele noi. Acest lucru este mai complex, dar realizabil.

Avertismente și Compromisuri

Deprecierea este puternică, dar are dezavantaje. Fiecare versiune depreciață adaugă cod la pluginul tău. În timp, poți ajunge cu un lanț de cinci sau șase versiuni moștenite care sunt rar folosite, dar trebuie menținute. Echipa de bază WordPress recomandă păstrarea a cel puțin două versiuni înapoi, dar dincolo de asta, ai putea lua în considerare o rupere curată dacă numărul de postări afectate este mic.

O altă nuanță: ordinea intrărilor depreciate contează. Editorul iterează prin tablou de la indexul 0 în sus și folosește prima potrivire. Dacă două versiuni depreciate sunt similare, s-ar putea aplica cea greșită. Întotdeauna listează cea mai recentă versiune depreciață prima (cea care precedă direct versiunea curentă).

În final, deprecierea nu gestionează conținutul care a fost editat folosind o schimbare de stil la nivel de site (de exemplu, prin theme.json). Dacă aspectul blocului tău se baza pe stiluri globale care s-au schimbat între timp, deprecierea nu va ajusta pentru asta. Poate fi necesar să adaugi un script de migrare care rulează la salvare sau printr-un cârlig de actualizare a pluginului.

Când Deprecierea Nu Este Răspunsul

Majoritatea tutorialelor prezintă deprecierea ca fiind obligatorie. În realitate, există situații în care o rupere curată este mai bună. Dacă blocul tău este nou și folosit doar în câteva postări, actualizarea manuală a acestor câteva instanțe ar putea fi mai rapidă decât scrierea și testarea codului de depreciere. Similar, dacă modelul de date subiacent al blocului este fundamental diferit (de exemplu, îmbini două blocuri într-unul singur), este posibil ca deprecierea să nu fie suficient de flexibilă. În acest caz, scrie un script de migrare unic care rulează când pluginul se actualizează, convertind blocurile vechi la noul format.

Un alt punct contrar: deprecierea nu ar trebui folosită ca substitut pentru un design bun. Dacă anticipezi schimbări frecvente, proiectează-ți blocul având în vedere versionarea de la început—de exemplu, prin stocarea unui atribut version și folosirea randării condiționate. Această abordare, discutată în Beyond Basic Blocks, este mai ușoară decât deprecierea, dar necesită previziune.

Concluzie

Deprecierea blocurilor este un instrument esențial pentru orice dezvoltator Gutenberg serios. Îți permite să îți evoluezi blocurile fără a distruge conținutul utilizatorilor. Pașii cheie sunt: captează starea curentă, definește versiunea depreciață în block.json, mapează atributele dacă este necesar și testează cu conținut real. Dar reține că deprecierea vine cu costuri de întreținere. Uneori, o rupere curată sau un design de bloc versionat este mai pragmatic. Folosește deprecierea strategic, nu automat, iar blocurile tale vor rămâne robuste prin multe actualizări.

Pentru o perspectivă mai largă asupra construirii de pluginuri mentenabile, vezi Building Robust WordPress Plugins. Și dacă ești nou în dezvoltarea de blocuri, Beyond Basic Blocks te va ajuta să începi.