Zavrhovanie blokov Gutenberg: Aktualizujte bez narušenia obsahu

Zhrnutie

Aktualizácia bloku Gutenberg často rozbije existujúce príspevky, ktoré používajú starú verziu. Tento článok vám ukáže, ako použiť vlastnosť deprecated v block.json na zachovanie spätnej kompatibility. Naučíte sa presné kroky na zachytenie aktuálneho označenia bloku, definovanie jednej alebo viacerých zavrhovaných verzií a správne mapovanie atribútov. Preberieme statické aj dynamické bloky s praktickými príkladmi. Článok tiež spochybňuje predpoklad, že zavrhovanie je vždy najlepší prístup, a diskutuje o tom, kedy môže byť lepší úplný zlom. Na konci budete schopní aktualizovať svoje bloky bez obáv z narušenia obsahu používateľov.

Scenár zmeny, ktorá narúša obsah

Pred šiestimi mesiacmi ste spustili vlastný blok s posudkom. Vytvára jednoduchý <div> s citátom a menom autora. Teraz váš klient chce nový dizajn: autor by sa mal zobraziť nad citátom s inou CSS triedou. Aktualizujete funkciu save bloku a render_callback. Otestujete na novom príspevku – vyzerá skvele. Potom prejdete na starý príspevok, ktorý používa blok. Katastrofa: text citátu je preč, autor je na nesprávnom mieste a štýl je pokazený. Práve ste rozbili každú stránku, ktorá blok používa.

Toto je klasický problém „zmeny, ktorá narúša obsah“ pri vývoji blokov Gutenberg. Bloky sú v podstate dátové štruktúry kombinované so značkami. Keď zmeníte značky, editor nedokáže automaticky mapovať starý obsah na novú štruktúru. Výsledkom je buď chyba overenia (blok sa stane neplatným), alebo – horšie – tichá korupcia, kde sa blok vykresľuje nesprávne.

Čo je zavrhovanie blokov?

Zavrhovanie blokov je vstavaný mechanizmus Gutenbergu na riešenie zmien verzií. Definovaním poľa deprecated v block.json svojho bloku poviete editoru: „Ak narazíš na blok, ktorý zodpovedá niektorej z týchto starších verzií, transformuj ho na aktuálnu verziu.“ Každý záznam zavrhovania špecifikuje predchádzajúce attributes, supports a funkciu save (alebo render_callback). Keď editor načíta starý blok, prechádza pole zavrhovaných v poradí a použije prvú zodpovedajúcu transformáciu.

Táto funkcia je často nevyužitá, pretože vývojári predpokladajú, že nikdy nebudú musieť meniť značky bloku. Ale v reálnych projektoch sa požiadavky vyvíjajú. Ak vynecháte zavrhovanie, buď nútime používateľov mazať a znovu vkladať bloky (zlá skúsenosť), alebo udržiavať dve samostatné verzie bloku (neporiadok). Oficiálna príručka vývojára WordPressu to pokrýva v Príručka editora blokov, ale chýbajú praktické návody.

Krok 1: Zachyťte aktuálny stav

Pred vykonaním akýchkoľvek zmien zaznamenajte presný výstup save (alebo render_callback pre dynamické bloky) a attributes, ktoré váš blok momentálne používa. Myslite na to ako na vytvorenie snímku. Pre statické bloky uložte JSX vrátené funkciou save. Pre dynamické bloky uložte PHP značky generované render_callback.

Vytvorte nový súbor vo svojom plugine s názvom deprecated.js (alebo podobne) a uložte tam starú funkciu save. Prípadne môžete zavrhované verzie uchovávať priamo v hlavnom JavaScript súbore bloku. Kľúčové je zachovať tento kód presne tak, ako bol, keď bol blok prvýkrát nasadený.

Krok 2: Definujte svoje zavrhované verzie

V block.json pridajte pole deprecated. Každý záznam je objekt, ktorý môže obsahovať:

• attributes (objekt): Predchádzajúce definície atribútov.
• supports (objekt): Všetky predchádzajúce nastavenia podpory, ktoré sa zmenili.
• save (funkcia alebo reťazec): Predchádzajúca funkcia save. Pre bloky len v JavaScripte importujete starú funkciu. Pre dynamické bloky vykresľované v PHP môžete namiesto toho použiť migrate a render_callback.
• migrate (funkcia): Funkcia, ktorá mapuje staré atribúty na nové (voliteľné).

Príklad:

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

Poznámka: Funkcia save v block.json je zvyčajne definovaná v JavaScripte. Ak používate externý skript, budete ho musieť zaradiť a odkazovať na názov funkcie. Prípadne môžete funkciu vložiť ako reťazec (aj keď sa to neodporúča pre zložité bloky).

Krok 3: Mapovanie atribútov

Často meníte nielen značky, ale aj názvy atribútov alebo zdroje. Napríklad by ste mohli prejsť od ukladania autora ako obyčajného reťazca k bohatému textovému poľu. V takýchto prípadoch použite vlastnosť migrate na transformáciu starých atribútov na nové.

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

Ak neposkytnete funkciu migrate, editor jednoducho odovzdá staré atribúty priamo novému bloku. To môže spôsobiť chyby, ak sa názvy atribútov zmenili.

Krok 4: Testujte s reálnym obsahom

Po definovaní zavrhovanej verzie dôkladne testujte. Vytvorte nový príspevok, vložte starý blok (môžete simulovať vložením serializovaného kódu bloku z existujúceho príspevku) a overte, či sa skonvertuje na novú verziu bez chýb overenia. Tiež otestujte úpravu a uloženie konvertovaného bloku. Opakujte pre viacero zavrhovaných verzií, ak ich máte.

Pre dynamické bloky je proces podobný, ale s odlišnosťou: funkcia save pre dynamický blok zvyčajne vracia null (blok sa vykresľuje cez PHP). V zavrhovanom zázname môžete buď nastaviť save na predchádzajúce statické značky, ktoré sa používali pred prepnutím na dynamické vykresľovanie, alebo použiť render_callback v PHP, ktorý spracúva staré aj nové štruktúry atribútov. Je to zložitejšie, ale uskutočniteľné.

Výhrady a kompromisy

Zavrhovanie je výkonné, ale má nevýhody. Každá zavrhovaná verzia pridáva kód do vášho pluginu. Postupom času môžete skončiť s reťazcom piatich alebo šiestich starších verzií, ktoré sa zriedka používajú, ale musia byť udržiavané. Tím WordPress core odporúča zachovať aspoň dve verzie späť, ale za týmto bodom môžete zvážiť úplný zlom, ak je počet ovplyvnených príspevkov malý.

Ďalšia nuansa: poradie zavrhovaných záznamov je dôležité. Editor iteruje cez pole od indexu 0 nahor a použije prvú zhodu. Ak sú dve zavrhované verzie podobné, mohla by sa použiť nesprávna. Vždy uvádzajte najnovšiu zavrhovanú verziu ako prvú (tú, ktorá bezprostredne predchádza aktuálnej verzii).

Nakoniec, zavrhovanie nerieši obsah, ktorý bol upravený pomocou celoplošnej zmeny štýlu (napr. cez theme.json). Ak vzhľad vášho bloku závisel od globálnych štýlov, ktoré sa odvtedy zmenili, zavrhovanie to neupraví. Možno budete musieť pridať migračný skript, ktorý sa spustí pri uložení alebo prostredníctvom háku aktualizácie pluginu.

Kedy zavrhovanie nie je odpoveďou

Väčšina tutoriálov zobrazuje zavrhovanie ako povinné. V skutočnosti existujú situácie, keď je lepší úplný zlom. Ak je váš blok nový a používa sa len v niekoľkých príspevkoch, manuálna aktualizácia týchto niekoľkých inštancií môže byť rýchlejšia ako písanie a testovanie kódu zavrhovania. Podobne, ak je dátový model bloku zásadne odlišný (napr. spájate dva bloky do jedného), zavrhovanie nemusí byť dostatočne flexibilné. V takom prípade napíšte jednorazový migračný skript, ktorý sa spustí pri aktualizácii pluginu a konvertuje staré bloky na nový formát.

Ďalší kontroverzný bod: zavrhovanie by sa nemalo používať ako náhrada za dobrý dizajn. Ak očakávate časté zmeny, navrhnite blok od začiatku s verzovaním – napríklad uložením atribútu version a použitím podmieneného vykresľovania. Tento prístup, diskutovaný v Beyond Basic Blocks, je ľahší ako zavrhovanie, ale vyžaduje predvídavosť.

Záver

Zavrhovanie blokov je nevyhnutný nástroj pre každého vážneho vývojára Gutenbergu. Umožňuje vám vyvíjať bloky bez narušenia obsahu používateľov. Kľúčové kroky sú: zachyťte aktuálny stav, definujte zavrhovanú verziu v block.json, mapujte atribúty podľa potreby a testujte s reálnym obsahom. Ale pamätajte, že zavrhovanie prináša náklady na údržbu. Niekedy je úplný zlom alebo verzovaný dizajn bloku pragmatickejší. Používajte zavrhovanie strategicky, nie automaticky, a vaše bloky zostanú robustné počas mnohých aktualizácií.

Pre širší pohľad na budovanie udržateľných pluginov si pozrite Building Robust WordPress Plugins. A ak ste nováčikom vo vývoji blokov, Beyond Basic Blocks vám pomôže začať.