Deprekacija Gutenberg bloka: Ažurirajte bez lomljenja sadržaja

Sažetak

Ažuriranje Gutenberg bloka često lomi postojeće objave koje koriste staru verziju. Ovaj članak vam pokazuje kako koristiti deprecated svojstvo u block.json za održavanje unazadne kompatibilnosti. Naučit ćete tačne korake za snimanje trenutnog markup-a bloka, definiranje jedne ili više depreciranih verzija i pravilno mapiranje atributa. Pokrit ćemo i statičke i dinamičke blokove, s praktičnim primjerima. Članak također dovodi u pitanje pretpostavku da je deprekacija uvijek najbolji pristup, raspravljajući kada bi čisti prekid mogao biti bolji. Do kraja, moći ćete ažurirati svoje blokove s povjerenjem bez lomljenja sadržaja vaših korisnika.

Scenarij lomljenja promjena

Pokrenuli ste prilagođeni blok za izjave prije šest mjeseci. On ispisuje jednostavan <div> s citatom i imenom autora. Sada vaš klijent želi novi dizajn: autor bi se trebao pojaviti iznad citata, s drugačijom CSS klasom. Ažurirate block-ovu save funkciju i render_callback. Testirate na svježoj objavi—izgleda odlično. Zatim odete na staru objavu koja koristi blok. Katastrofa: tekst citata je nestao, autor je na pogrešnom mjestu, a stilizacija je loša. Upravo ste pokvarili svaku stranicu koja koristi blok.

Što je deprekacija bloka?

Deprekacija bloka je ugrađeni mehanizam Gutenberg-a za rukovanje promjenama verzija. Definiranjem niza deprecated u vašem block.json, kažete editoru: "Ako naiđete na blok koji odgovara jednoj od ovih starijih verzija, pretvorite ga u trenutnu verziju." Svaki deprecirani unos specificira prethodne attributes, supports i save funkciju (ili render_callback). Kada editor učita stari blok, prolazi kroz niz depreciranih unosa po redu i primjenjuje prvo podudarno pretvaranje.

Ova se značajka često ne koristi jer programeri pretpostavljaju da nikada neće trebati mijenjati markup bloka. Ali u stvarnim projektima, zahtjevi se mijenjaju. Ako preskočite deprekaciju, ili prisiljavate korisnike da brišu i ponovno umeću blokove (loše iskustvo) ili održavate dvije odvojene verzije bloka (neuredno). Službeni WordPress priručnik za programere ovo pokriva u Priručniku za editor blokova, ali nedostaju praktični vodiči korak po korak.

Korak 1: Snimite trenutno stanje

Prije bilo kakvih promjena, zabilježite tačan save izlaz (ili render_callback za dinamičke blokove) i attributes koje vaš blok trenutno koristi. Zamislite to kao snimanje slike. Za statičke blokove, sačuvajte JSX koji vraća save funkcija. Za dinamičke blokove, sačuvajte PHP markup generiran od render_callback.

Kreirajte novu datoteku u svom dodatku nazvanu deprecated.js (ili slično) i tu pohranite staru save funkciju. Alternativno, držite deprecirane verzije direktno u glavnoj JavaScript datoteci bloka. Ključ je da sačuvate ovaj kod tačno onako kako je bio kada je blok prvi put deployiran.

Korak 2: Definirajte svoje deprecirane verzije

U vašem block.json, dodajte niz deprecated. Svaki unos je objekt koji može uključivati:

• attributes (object): Prethodne definicije atributa.
• supports (object): Bilo koje prethodne postavke podrške koje su se promijenile.
• save (function or string): Prethodna save funkcija.
• migrate (function): Funkcija koja mapira stare atribute na nove (opcionalno).

Primjer:

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

Napomena: save funkcija u block.json obično se definira u JavaScript-u. Ako koristite vanjski skript, morat ćete ga dodati i referencirati ime funkcije. Alternativno, možete funkciju upisati kao string (iako se to ne preporučuje za složene blokove).

Korak 3: Mapirajte atribute

Često ne mijenjate samo markup, već i imena atributa ili izvore. Na primjer, možete preći s pohranjivanja autora kao običnog stringa na polje bogatog teksta. U takvim slučajevima, koristite svojstvo migrate za transformaciju starih atributa u nove.

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

Ako ne navedete migrate funkciju, editor će jednostavno proslijediti stare atribute direktno novom bloku. To može uzrokovati greške ako su se imena atributa promijenila.

Korak 4: Testirajte sa stvarnim sadržajem

Nakon što definirate depreciranu verziju, temeljito testirajte. Kreirajte novu objavu, umetnite stari blok (možete simulirati lijepljenjem serijaliziranog koda bloka iz postojeće objave) i provjerite pretvara li se u novu verziju bez grešaka validacije. Također testirajte uređivanje i spremanje pretvorenog bloka. Ponovite za više depreciranih verzija ako ih imate.

Za dinamičke blokove, proces je sličan, ali s obrtom: save funkcija za dinamički blok obično vraća null (blok se renderira putem PHP-a). U depreciranom unosu možete postaviti save na prethodni statički markup koji je korišten prije nego što ste prešli na dinamičko renderiranje, ili koristiti render_callback u PHP-u koji rukuje i starim i novim strukturama atributa. To je složenije, ali izvodljivo.

Ograničenja i kompromisi

Deprekacija je moćna, ali ima nedostatke. Svaka deprecirana verzija dodaje kod vašem dodatku. Vremenom, možete završiti s lancem od pet ili šest naslijeđenih verzija koje se rijetko koriste, ali se moraju održavati. WordPress core tim preporučuje da držite najmanje dvije verzije unazad, ali nakon toga, možda biste trebali razmotriti čisti prekid ako je broj pogođenih objava mali.

Druga nijansa: redoslijed depreciranih unosa je važan. Editor prolazi kroz niz od indeksa 0 naviše i koristi prvo podudaranje. Ako su dvije deprecirane verzije slične, može se primijeniti pogrešna. Uvijek navodite najnoviju depreciranu verziju prvu (onu koja neposredno prethodi trenutnoj verziji).

Konačno, deprekacija ne rukuje sadržajem koji je uređivan korištenjem promjene stila na nivou sajta (npr. putem theme.json). Ako je izgled vašeg bloka ovisio o globalnim stilovima koji su se promijenili, deprekacija to neće prilagoditi. Možda ćete morati dodati migracijski skript koji se pokreće prilikom spremanja ili putem hook-a za ažuriranje dodatka.

Kada deprekacija nije rješenje

Većina tutorijala prikazuje deprekaciju kao obaveznu. U stvarnosti, postoje situacije u kojima je čisti prekid bolji. Ako je vaš blok nov i koristi se u samo nekoliko objava, ručno ažuriranje tih nekoliko instanci može biti brže od pisanja i testiranja koda za deprekaciju. Slično tome, ako je podatkovni model bloka fundamentalno drugačiji (npr. spajate dva bloka u jedan), deprekacija možda neće biti dovoljno fleksibilna. U tom slučaju, napišite jednokratni migracijski skript koji se pokreće kada se dodatak ažurira, pretvarajući stare blokove u novi format.

Još jedna kontrarna tačka: deprekaciju ne treba koristiti kao zamjenu za dobar dizajn. Ako očekujete česte promjene, dizajnirajte svoj blok s verzioniranjem na umu od početka—npr. pohranjivanjem atributa version i korištenjem uvjetnog renderiranja. Ovaj pristup, o kojem se raspravlja u Izvan osnovnih blokova, lakši je od deprekacije, ali zahtijeva predviđanje.

Zaključak

Deprekacija bloka je esencijalan alat za svakog ozbiljnog Gutenberg programera. Omogućuje vam da razvijate svoje blokove bez lomljenja sadržaja korisnika. Ključni koraci su: snimite trenutno stanje, definirajte depreciranu verziju u block.json, mapirajte atribute ako je potrebno i testirajte sa stvarnim sadržajem. Ali zapamtite da deprekacija dolazi s troškovima održavanja. Ponekad je čisti prekid ili verzionirani dizajn bloka pragmatičniji. Koristite deprekaciju strateški, ne automatski, i vaši blokovi će ostati robusni kroz mnoga ažuriranja.

Za širu perspektivu o izgradnji održivih dodataka, pogledajte Izgradnja robusnih WordPress dodataka. A ako ste novi u razvoju blokova, Izvan osnovnih blokova će vam pomoći da započnete.