Gutenberg Block Deprecation: Ažurirajte bez narušavanja sadržaja

Sažetak

Ažuriranje Gutenberg bloka često lomi postojeće objave koje koriste staru verziju. Ovaj članak pokazuje kako koristiti svojstvo deprecated u block.json za održavanje unatrag kompatibilnosti. Naučit ćete točne korake za snimanje trenutnog markupa bloka, definiranje jedne ili više zastarjelih verzija i ispravno mapiranje atributa. Obradit ćemo i statičke i dinamičke blokove, s praktičnim primjerima. Članak se također suprotstavlja pretpostavci da je deprecation uvijek najbolji pristup, raspravljajući kada je čišći prekid bolji. Na kraju ćete moći samouvjereno ažurirati svoje blokove bez narušavanja korisničkog sadržaja.

Scenarij promjene koja lomi

Prije šest mjeseci lansirali ste prilagođeni blok za svjedočanstva. On ispisuje jednostavan <div> s citatom i imenom autora. Sada vaš klijent želi novi dizajn: autor bi se trebao pojaviti iznad citata, s drugom CSS klasom. Ažurirate blokovu save funkciju i render_callback. Testirate na novoj 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 slomili svaku stranicu koja koristi blok.

Ovo je klasični problem "promjene koja lomi" u razvoju Gutenberg blokova. Blokovi su u suštini strukture podataka kombinirane s markupom. Kada promijenite markup, uređivač ne može automatski mapirati stari sadržaj u novu strukturu. Rezultat je ili pogreška validacije (blok postaje nevažeći) ili – još gore – tiho oštećenje gdje se blok prikazuje pogrešno.

Što je deprecation bloka?

Deprecation bloka je Gutenbergov ugrađeni mehanizam za rukovanje promjenama verzija. Definiranjem niza deprecated u blokovom block.json govorite uređivaču: "Ako naiđeš na blok koji odgovara jednoj od ovih starijih verzija, pretvori ga u trenutnu verziju." Svaki unos zastarjele verzije specificira prethodne attributes, supports i save funkciju (ili render_callback). Kada uređivač učita stari blok, prolazi kroz niz zastarjelih verzija redom i primjenjuje prvu koja se podudara.

Ova značajka je često nedovoljno korištena jer programeri pretpostavljaju da nikada neće trebati mijenjati markup bloka. Ali u stvarnim projektima zahtjevi se razvijaju. Ako preskočite deprecation, ili prisiljavate korisnike da brišu i ponovno umeću blok (loše korisničko iskustvo) ili održavate dvije odvojene verzije bloka (neuredno). Službeni WordPress priručnik za programere pokriva ovo u Priručniku za uređivač blokova, ali nedostaju praktični primjeri.

Korak 1: Snimite trenutno stanje

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

Kreirajte novu datoteku u svom dodatku pod nazivom deprecated.js (ili slično) i tamo pohranite staru save funkciju. Alternativno, zadržite zastarjele verzije izravno u glavnoj JavaScript datoteci bloka. Ključno je sačuvati ovaj kod točno onakvim kakav je bio kada je blok prvi put postavljen.

Korak 2: Definirajte svoje zastarjele verzije

U svom block.json dodajte niz deprecated. Svaki unos je objekt koji može uključivati:

• attributes (objekt): Prethodne definicije atributa.
• supports (objekt): Bilo koje prethodne postavke podrške koje su se promijenile.
• save (funkcija ili string): Prethodna save funkcija. Za JavaScript-only blokove, uvest ćete staru funkciju. Za PHP-rendered dinamičke blokove, možete koristiti migrate i render_callback umjesto toga.
• migrate (funkcija): Funkcija koja mapira stare atribute u 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 je obično definirana u JavaScriptu. Ako koristite vanjski skript, morat ćete ga uključiti i referencirati ime funkcije. Alternativno, možete inline funkciju kao string (iako se to ne preporučuje za složene blokove).

Korak 3: Mapirajte atribute

Često mijenjate ne samo markup već i nazive atributa ili izvore. Na primjer, možete prijeći s pohrane autora kao običnog stringa na bogato polje 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 pružite funkciju migrate, uređivač će jednostavno proslijediti stare atribute izravno novom bloku. To može uzrokovati pogreške ako su se nazivi atributa promijenili.

Korak 4: Testirajte sa stvarnim sadržajem

Nakon što definirate zastarjelu verziju, testirajte temeljito. 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 pogrešaka validacije. Također testirajte uređivanje i spremanje pretvorenog bloka. Ponovite za više zastarjelih verzija ako ih imate.

Za dinamičke blokove, postupak je sličan, ali s obratom: save funkcija za dinamički blok obično vraća null (blok se prikazuje putem PHP-a). U zastarjelom 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. Ovo je složenije, ali izvedivo.

Oprez i kompromisi

Deprecation je moćan, ali ima nedostatke. Svaka zastarjela verzija dodaje kod vašem dodatku. S vremenom možete završiti s lancem od pet ili šest naslijeđenih verzija koje se rijetko koriste, ali ih treba održavati. WordPress core tim preporučuje zadržavanje najmanje dvije verzije unatrag, ali dalje od toga možda biste trebali razmisliti o čišćem prekidu ako je broj pogođenih objava mali.

Druga nijansa: redoslijed zastarjelih unosa je važan. Uređivač prolazi kroz niz od indeksa 0 prema gore i koristi prvo podudaranje. Ako su dvije zastarjele verzije slične, mogla bi se primijeniti pogrešna. Uvijek navedite najnoviju zastarjelu verziju prvu (onu koja izravno prethodi trenutnoj verziji).

Konačno, deprecation ne rukuje sadržajem koji je uređivan pomoću promjene stila na razini cijelog weba (npr. putem theme.json). Ako je izgled vašeg bloka ovisio o globalnim stilovima koji su se od tada promijenili, deprecation se neće prilagoditi tome. Možda ćete morati dodati migracijski skript koji se izvodi prilikom spremanja ili putem kuke za ažuriranje dodatka.

Kada deprecation nije odgovor

Većina tutorijala prikazuje deprecation kao obavezan. U stvarnosti, postoje situacije gdje je čišći prekid bolji. Ako je vaš blok nov i korišten u samo nekoliko objava, ručno ažuriranje tih nekoliko instanci moglo bi biti brže od pisanja i testiranja koda za deprecation. Slično tome, ako je temeljni model podataka bloka bitno drugačiji (npr. spajate dva bloka u jedan), deprecation možda neće biti dovoljno fleksibilan. 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 točka: deprecation se ne smije koristiti kao zamjena za dobar dizajn. Ako predviđate česte promjene, dizajnirajte svoj blok s verzioniranjem na umu od samog početka – npr. pohranjivanjem atributa version i korištenjem uvjetnog renderiranja. Ovaj pristup, obrađen u Beyond Basic Blocks, lakši je od deprecation, ali zahtijeva predviđanje.

Zaključak

Deprecation bloka je neophodan alat za svakog ozbiljnog Gutenberg programera. Omogućuje vam da razvijate svoje blokove bez narušavanja korisničkog sadržaja. Ključni koraci su: snimite trenutno stanje, definirajte zastarjelu verziju u block.json, mapirajte atribute ako je potrebno i testirajte sa stvarnim sadržajem. Ali zapamtite da deprecation nosi troškove održavanja. Ponekad je čišći prekid ili dizajn bloka s verzioniranjem pragmatičniji. Koristite deprecation strateški, ne automatski, i vaši će blokovi ostati robusni kroz mnoga ažuriranja.

Za širu perspektivu o izgradnji održivih dodataka, pogledajte Building Robust WordPress Plugins. A ako ste novi u razvoju blokova, Beyond Basic Blocks pomoći će vam započeti.