Opustitev blokov Gutenberg: Posodobite brez uničenja vsebine

Povzetek

Posodabljanje bloka Gutenberg pogosto pokvari obstoječe objave, ki uporabljajo staro različico. Ta članek vam pokaže, kako uporabiti lastnost deprecated v block.json za ohranitev nazaj združljivosti. Naučili se boste natančnih korakov za zajem trenutne označbe bloka, določitev ene ali več opuščenih različic in pravilno preslikavo atributov. Pokrili bomo tako statične kot dinamične bloke s praktičnimi primeri. Članek tudi nasprotuje predpostavki, da je opustitev vedno najboljši pristop, in razpravlja o tem, kdaj je čista prekinitev morda boljša. Na koncu boste lahko samozavestno posodabljali svoje bloke, ne da bi pri tem pokvarili vsebino uporabnikov.

Scenarij prelomne spremembe

Pred šestimi meseci ste lansirali blok po meri za pričevanja. Izpisuje preprost <div> s citatom in imenom avtorja. Zdaj vaša stranka želi novo zasnovo: avtor naj bo nad citatom, z drugim razredom CSS. Posodobite funkcijo save bloka in render_callback. Preizkusite na sveži objavi – izgleda odlično. Nato se pomaknete na staro objavo, ki uporablja blok. Katastrofa: besedilo citata je izginilo, avtor je na napačnem mestu in slog je pokvarjen. Pravkar ste pokvarili vsako stran, ki uporablja ta blok.

To je klasičen problem "prelomne spremembe" pri razvoju blokov Gutenberg. Bloki so v bistvu podatkovne strukture, združene z oznako. Ko spremenite oznako, urejevalnik ne more samodejno preslikati stare vsebine v novo strukturo. Rezultat je bodisi napaka pri preverjanju (blok postane neveljaven) ali – še huje – tiho uničenje, kjer se blok napačno prikaže.

Kaj je opustitev bloka?

Opustitev bloka je vgrajeni mehanizem Gutenberg za obvladovanje sprememb različic. Z definiranjem niza deprecated v block.json bloka poveste urejevalniku: "Če naletiš na blok, ki ustreza eni od teh starejših različic, ga pretvori v trenutno različico." Vsak opuščeni vnos določa prejšnje attributes, supports in funkcijo save (ali render_callback). Ko urejevalnik naloži star blok, zaporedno preveri niz opuščenih vnosov in uporabi prvo ujemanje.

Ta funkcija je pogosto premalo uporabljena, ker razvijalci domnevajo, da nikoli ne bodo potrebovali spremembe oznake bloka. Toda v resničnih projektih se zahteve razvijajo. Če izpustite opustitev, bodisi prisilite uporabnike k brisanju in ponovnemu vstavljanju blokov (slaba izkušnja) bodisi vzdržujete dve ločeni različici bloka (nerodno). Uradni priročnik za razvijalce WordPressa to obravnava v Priročniku za urejevalnik blokov, vendar so praktični vodiči pomanjkljivi.

Korak 1: Zajemite trenutno stanje

Pred kakršnimi koli spremembami zabeležite natančen izhod save (ali render_callback za dinamične bloke) in attributes, ki jih blok trenutno uporablja. Pomislite na to kot na posnetek. Za statične bloke shranite JSX, ki ga vrne funkcija save. Za dinamične bloke shranite PHP oznako, ki jo ustvari render_callback.

V svojem vtičniku ustvarite novo datoteko z imenom deprecated.js (ali podobno) in tam shranite staro funkcijo save. Druga možnost je, da opuščene različice hranite neposredno v glavni JavaScript datoteki bloka. Ključno je, da to kodo ohranite natančno tako, kot je bila, ko je bil blok prvič nameščen.

Korak 2: Določite svoje opuščene različice

V block.json dodajte niz deprecated. Vsak vnos je objekt, ki lahko vključuje:

• attributes (objekt): Prejšnje definicije atributov.
• supports (objekt): Morebitne prejšnje nastavitve podpore, ki so se spremenile.
• save (funkcija ali niz): Prejšnja funkcija save. Za bloke samo v JavaScriptu boste uvozili staro funkcijo. Za dinamične bloke, prikazane s PHP, lahko namesto tega uporabite migrate in render_callback.
• migrate (funkcija): Funkcija, ki preslika stare atribute v nove (izbirno).

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

Opomba: Funkcija save v block.json je običajno definirana v JavaScriptu. Če uporabljate zunanjo skripto, jo boste morali vključiti in se sklicevati na ime funkcije. Druga možnost je, da funkcijo vnesete kot niz (čeprav to ni priporočljivo za zapletene bloke).

Korak 3: Preslikajte atribute

Pogosto spremenite ne le oznako, ampak tudi imena ali vire atributov. Na primer, preklopite s shranjevanja avtorja kot preprostega niza na polje obogatenega besedila. V takih primerih uporabite lastnost migrate za pretvorbo starih atributov v nove.

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

Če ne zagotovite funkcije migrate, bo urejevalnik preprosto posredoval stare atribute neposredno novemu bloku. To lahko povzroči napake, če so se imena atributov spremenila.

Korak 4: Preizkusite z resnično vsebino

Po določitvi opuščene različice temeljito preizkusite. Ustvarite novo objavo, vstavite stari blok (lahko simulirate s prilepljanjem serializirane kode bloka iz obstoječe objave) in preverite, ali se pretvori v novo različico brez napak pri preverjanju. Prav tako preizkusite urejanje in shranjevanje pretvorjenega bloka. Ponovite za več opuščenih različic, če jih imate.

Za dinamične bloke je postopek podoben, vendar z zapletom: funkcija save za dinamični blok običajno vrne null (blok se prikaže prek PHP). V opuščenem vnosu lahko nastavite save na prejšnjo statično oznako, ki je bila uporabljena, preden ste preklopili na dinamično prikazovanje, ali uporabite render_callback v PHP, ki obravnava tako stare kot nove strukture atributov. To je bolj zapleteno, a izvedljivo.

Opozorila in kompromisi

Opustitev je močna, vendar ima slabosti. Vsaka opuščena različica doda kodo vašemu vtičniku. Sčasoma lahko dobite verigo petih ali šestih zapuščenih različic, ki se redko uporabljajo, vendar jih je treba vzdrževati. Jedrna ekipa WordPress priporoča, da obdržite vsaj dve različici nazaj, vendar lahko po tem razmislite o čisti prekinitvi, če je število prizadetih objav majhno.

Druga podrobnost: vrstni red opuščenih vnosov je pomemben. Urejevalnik prečka niz od indeksa 0 navzgor in uporabi prvo ujemanje. Če sta si dve opuščeni različici podobni, se lahko uporabi napačna. Vedno navedite najprej najnovejšo opuščeno različico (tisto, ki neposredno predhodi trenutni različici).

Nazadnje, opustitev ne obravnava vsebine, ki je bila urejena s spremembo sloga na celotnem spletnem mestu (npr. prek theme.json). Če je bil videz vašega bloka odvisen od globalnih slogov, ki so se od takrat spremenili, opustitev tega ne bo prilagodila. Morda boste morali dodati migracijsko skripto, ki se zažene ob shranjevanju ali prek kljuke za posodobitev vtičnika.

Ko opustitev ni odgovor

Večina vodičev opustitev predstavlja kot obvezno. V resnici obstajajo situacije, ko je čista prekinitev boljša. Če je vaš blok nov in se uporablja le v peščici objav, je ročno posodabljanje teh nekaj primerov morda hitrejše od pisanja in testiranja kode za opustitev. Podobno, če je osnovni podatkovni model bloka bistveno drugačen (npr. združujete dva bloka v enega), opustitev morda ne bo dovolj prilagodljiva. V tem primeru napišite enkratno migracijsko skripto, ki se zažene ob posodobitvi vtičnika in pretvori stare bloke v novo obliko.

Druga nasprotna točka: opustitev ne bi smela biti nadomestilo za dobro zasnovo. Če pričakujete pogoste spremembe, od začetka načrtujte blok z različicami – na primer s shranjevanjem atributa version in uporabo pogojnega prikazovanja. Ta pristop, obravnavan v Beyond Basic Blocks, je lažji od opustitve, vendar zahteva predvidevanje.

Zaključek

Opustitev blokov je bistveno orodje za vsakega resnega razvijalca Gutenberg. Omogoča vam razvijanje blokov brez uničenja vsebine uporabnikov. Ključni koraki so: zajemite trenutno stanje, določite opuščeno različico v block.json, po potrebi preslikajte atribute in preizkusite z resnično vsebino. Ne pozabite pa, da ima opustitev stroške vzdrževanja. Včasih je čista prekinitev ali zasnova bloka z različicami bolj pragmatična. Uporabljajte opustitev strateško, ne samodejno, in vaši bloki bodo ostali robustni skozi številne posodobitve.

Za širšo perspektivo o gradnji vzdržljivih vtičnikov si oglejte Building Robust WordPress Plugins. In če ste novi v razvoju blokov, vam bo Beyond Basic Blocks pomagal začeti.