Deprekacija Gutenberg blokova: 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 da koristite deprecated svojstvo u block.json da biste održali unazadnu kompatibilnost. Naučićete tačne korake za snimanje trenutne oznake bloka, definisanje jedne ili više zastarelih verzija i pravilno mapiranje atributa. Pokrićemo i statičke i dinamičke blokove, sa praktičnim primerima. Članak takođe dovodi u pitanje pretpostavku da je deprekacija uvek najbolji pristup, raspravljajući kada bi čisti prekid mogao biti bolji. Na kraju, moći ćete da ažurirate svoje blokove sa poverenjem bez lomljenja sadržaja vaših korisnika.

Scenarij lomljive promene

Pokrenuli ste prilagođeni blok svedočanstva pre šest meseci. On prikazuje jednostavan <div> sa citatom i imenom autora. Sada vaš klijent želi novi dizajn: autor treba da se pojavi iznad citata, sa drugačijom 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 mestu, a stilizacija je loša. Upravo ste polomili svaku stranicu koja koristi blok.

Ovo je klasični problem „lomljive promene” u razvoju Gutenberg blokova. Blokovi su suštinski strukture podataka kombinovane sa oznakama. Kada promenite oznaku, uređivač ne može automatski da mapira stari sadržaj na novu strukturu. Rezultat je ili greška validacije (blok postaje nevažeći) ili—još gore—tiho oštećenje gde se blok pogrešno prikazuje.

Šta je deprekacija bloka?

Deprekacija bloka je Gutenberg-ov ugrađeni mehanizam za rukovanje promenama verzija. Definisanjem deprecated niza u vašem blokovom block.json, govorite uređivaču: „Ako naiđeš na blok koji odgovara jednoj od ovih starijih verzija, transformiši ga u trenutnu verziju.” Svaki zastareli unos specificira prethodne attributes, supports i save funkciju (ili render_callback). Kada uređivač učita stari blok, prolazi kroz niz zastarelih unosa po redu i primenjuje prvu podudarnu transformaciju.

Ova funkcija je često nedovoljno korišćena jer programeri pretpostavljaju da nikada neće morati da menjaju oznaku bloka. Ali u stvarnim projektima, zahtevi evoluiraju. Ako preskočite deprekaciju, ili prisiljavate korisnike da brišu i ponovo ubacuju blokove (loše iskustvo) ili održavate dve odvojene verzije bloka (neuredno). Zvanični WordPress-ov priručnik za programere pokriva ovo u Priručniku za uređivač blokova, ali nedostaju praktične upute.

Korak 1: Snimite trenutno stanje

Pre nego što napravite bilo kakve promene, zabeležite tačan save izlaz (ili render_callback za dinamičke blokove) i attributes koje vaš blok trenutno koristi. Zamislite to kao slikanje snimka. Za statičke blokove, sačuvajte JSX koji vraća save funkcija. Za dinamičke blokove, sačuvajte PHP oznaku koju generiše render_callback.

Kreirajte novu datoteku u vašem dodatku pod nazivom deprecated.js (ili slično) i tu smestite staru save funkciju. Alternativno, držite zastarele verzije direktno u glavnoj JavaScript datoteci bloka. Ključ je da sačuvate ovaj kod tačno onakvim kakav je bio kada je blok prvi put primenjen.

Korak 2: Definišite svoje zastarele verzije

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

• attributes (objekat): Prethodne definicije atributa.
• supports (objekat): Bilo koja prethodna podešavanja podrške koja su promenjena.
• save (funkcija ili string): Prethodna save funkcija. Za JavaScript--only blokove, uvezaćete staru funkciju. Za PHP-prikazane dinamičke blokove, možete koristiti migrate i render_callback umesto toga.
• migrate (funkcija): Funkcija koja mapira stare atribute na nove (opciono).

Primer:

"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 definisana u JavaScript-u. Ako koristite eksterni skript, trebaće da ga uvrštite i uputite na ime funkcije. Alternativno, možete ugraditi funkciju kao string (iako se ovo ne preporučuje za složene blokove).

Korak 3: Mapirajte atribute

Često menjate ne samo oznaku već i imena atributa ili izvore. Na primer, možda prelazite sa čuvanja autora kao običnog stringa na bogato polje teksta. U takvim slučajevima, koristite migrate svojstvo da transformišete stare atribute u nove.

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

Ako ne pružite migrate funkciju, uređivač će jednostavno proslediti stare atribute direktno novom bloku. To može izazvati greške ako su se imena atributa promenila.

Korak 4: Testirajte sa stvarnim sadržajem

Nakon definisanja zastarele verzije, temeljno testirajte. Kreirajte novu objavu, ubacite stari blok (možete simulirati lepljenjem serijalizovanog koda bloka iz postojeće objave) i proverite da li se konvertuje u novu verziju bez grešaka validacije. Takođe testirajte uređivanje i čuvanje konvertovanog bloka. Ponovite za više zastarelih verzija ako ih imate.

Za dinamičke blokove, proces je sličan ali sa preokretom: save funkcija za dinamički blok obično vraća null (blok se prikazuje putem PHP-a). U zastarelom unosu, možete postaviti save na prethodnu statičku oznaku koja je korišćena pre nego što ste prešli na dinamičko prikazivanje, ili koristiti render_callback u PHP-u koji rukuje i starim i novim strukturama atributa. Ovo je složenije, ali izvodljivo.

Upozorenja i kompromisi

Deprekacija je moćna, ali ima nedostatke. Svaka zastarela verzija dodaje kod vašem dodatku. Vremenom, možete završiti sa lancem od pet ili šest zastarelih verzija koje se retko koriste ali moraju biti održavane. WordPress core tim preporučuje čuvanje najmanje dve verzije unazad, ali izvan toga, možete razmotriti čisti prekid ako je broj pogođenih objava mali.

Još jedna nijansa: redosled zastarelih unosa je bitan. Uređivač prolazi kroz niz od indeksa 0 naviše i koristi prvo podudaranje. Ako su dve zastarele verzije slične, mogla bi se primeniti pogrešna. Uvek navedite najnoviju zastarelu verziju prvu (onu koja direktno prethodi trenutnoj verziji).

Konačno, deprekacija ne rukuje sadržajem koji je uređivan korišćenjem promena stila na nivou sajta (npr. putem theme.json). Ako je izgled vašeg bloka zavisio od globalnih stilova koji su se od tada promenili, deprekacija se neće prilagoditi tome. Možda ćete morati da dodate skriptu za migraciju koja se pokreće pri čuvanju ili putem kuka ažuriranja dodatka.

Kada deprekacija nije rešenje

Većina tutorijala prikazuje deprekaciju kao obaveznu. U stvarnosti, postoje situacije gde je čisti prekid bolji. Ako je vaš blok nov i korišćen u samo nekoliko objava, ručno ažuriranje tih nekoliko slučajeva može biti brže od pisanja i testiranja koda za deprekaciju. Slično, ako je osnovni model podataka bloka suštinski drugačiji (npr. spajate dva bloka u jedan), deprekacija možda neće biti dovoljno fleksibilna. U tom slučaju, napišite jednokratnu skriptu za migraciju koja se pokreće kada se dodatak ažurira, pretvarajući stare blokove u novi format.

Još jedna kontrarna tačka: deprekacija ne bi trebalo da se koristi kao zamena za dobar dizajn. Ako očekujete česte promene, dizajnirajte svoj blok sa verzionisanjem na umu od početka—npr. čuvanjem version atributa i korišćenjem uslovnog prikazivanja. Ovaj pristup, opisan u Izvan osnovnih blokova, lakši je od deprekacije ali zahteva predviđanje.

Zaključak

Deprekacija bloka je esencijalni alat za svakog ozbiljnog Gutenberg programera. Omogućava vam da razvijate svoje blokove bez lomljenja sadržaja korisnika. Ključni koraci su: snimite trenutno stanje, definišite zastarelu verziju u block.json, mapirajte atribute ako je potrebno i testirajte sa stvarnim sadržajem. Ali zapamtite da deprekacija nosi troškove održavanja. Ponekad je čisti prekid ili dizajn bloka sa verzionisanjem 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 počnete.