Gutenberg blokk elavulás: Frissítés a tartalom megtörése nélkül

Összefoglalás

Egy Gutenberg blokk frissítése gyakran megtöri a régi verziót használó meglévő bejegyzéseket. Ez a cikk bemutatja, hogyan használhatja a deprecated tulajdonságot a block.json fájlban a visszamenőleges kompatibilitás fenntartásához. Megtanulja a pontos lépéseket a jelenlegi blokk jelölésének rögzítéséhez, egy vagy több elavult verzió meghatározásához és az attribútumok helyes leképezéséhez. Lefedjük a statikus és dinamikus blokkokat is, gyakorlati példákkal. A cikk ellentmond annak a feltételezésnek, hogy az elavítás mindig a legjobb megközelítés, és tárgyalja, mikor lehet jobb egy tiszta szakítás. A végére magabiztosan frissítheti blokkjait anélkül, hogy megtörné a felhasználók tartalmát.

A törő változás forgatókönyve

Hat hónapja elindított egy egyedi ajánló blokkot. Egy egyszerű <div>-et ad ki egy idézettel és a szerző nevével. Most az ügyfele új dizájnt szeretne: a szerző az idézet felett jelenjen meg, más CSS osztállyal. Frissíti a blokk save függvényét és render_callback-jét. Teszteli egy új bejegyzésen – remekül néz ki. Aztán megnyit egy régi bejegyzést, amely a blokkot használja. Katasztrófa: az idézet szövege eltűnt, a szerző rossz helyen van, a stílus pedig hibás. Ezzel eltörte az összes oldalt, amely a blokkot használja.

Ez a klasszikus "törő változás" probléma a Gutenberg blokk fejlesztésben. A blokkok lényegében adatstruktúrák és jelölés kombinációi. Amikor megváltoztatja a jelölést, a szerkesztő nem tudja automatikusan leképezni a régi tartalmat az új szerkezetre. Az eredmény vagy egy érvényesítési hiba (a blokk érvénytelenné válik), vagy – ami rosszabb – néma adatsérülés, ahol a blokk helytelenül jelenik meg.

Mi az a blokk elavítás?

A blokk elavítás a Gutenberg beépített mechanizmusa a verzióváltozások kezelésére. A deprecated tömb megadásával a blokk block.json fájljában azt mondja a szerkesztőnek: "Ha találkozol egy blokkal, amely megfelel ezen régebbi verziók valamelyikének, alakítsd át a jelenlegi verzióra." Minden elavult bejegyzés megadja az előző attributes, supports és save függvényt (vagy render_callback-et). Amikor a szerkesztő betölt egy régi blokkot, végigmegy az elavult tömbön sorrendben, és az első egyező átalakítást alkalmazza.

Ezt a funkciót gyakran alulhasználják, mert a fejlesztők feltételezik, hogy soha nem kell megváltoztatniuk egy blokk jelölését. De a valós projektekben a követelmények fejlődnek. Ha kihagyja az elavítást, akkor vagy arra kényszeríti a felhasználókat, hogy töröljék és újra beszúrják a blokkokat (rossz élmény), vagy két külön verziót tart fenn a blokkból (rendetlen). A hivatalos WordPress fejlesztői kézikönyv ezt a Blokk szerkesztő kézikönyv oldalon tárgyalja, de hiányoznak a gyakorlati útmutatók.

1. lépés: A jelenlegi állapot rögzítése

Mielőtt bármilyen változtatást végezne, jegyezze fel a pontos save kimenetet (vagy a dinamikus blokkoknál a render_callback-et) és a blokk által jelenleg használt attributes-eket. Tekintse úgy, mint egy pillanatkép készítését. Statikus blokkoknál mentse el a save függvény által visszaadott JSX-et. Dinamikus blokkoknál mentse el a render_callback által generált PHP jelölést.

Hozzon létre egy új fájlt a bővítményében deprecated.js néven (vagy hasonló), és tárolja ott a régi save függvényt. Alternatívaként tartsa meg az elavult verziókat közvetlenül a blokk fő JavaScript fájljában. A lényeg, hogy pontosan úgy őrizze meg ezt a kódot, ahogy a blokk első telepítésekor volt.

2. lépés: Az elavult verziók meghatározása

A block.json fájlban adjon hozzá egy deprecated tömböt. Minden bejegyzés egy objektum, amely a következőket tartalmazhatja:

• attributes (objektum): Az előző attribútumdefiníciók.
• supports (objektum): Bármely korábbi támogatási beállítás, ami megváltozott.
• save (függvény vagy karakterlánc): Az előző save függvény. JavaScript-only blokkoknál importálni fogja a régi függvényt. PHP-vel renderelt dinamikus blokkoknál használhatja a migrate és a render_callback helyette.
• migrate (függvény): Egy függvény, amely leképezi a régi attribútumokat az újakra (opcionális).

Példa:

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

Megjegyzés: A save függvény a block.json fájlban általában JavaScript-ben van definiálva. Ha külső szkriptet használ, akkor be kell sorakoztatnia és hivatkoznia kell a függvény nevére. Alternatívaként beágyazhatja a függvényt karakterláncként (bár ez nem ajánlott összetett blokkok esetén).

3. lépés: Attribútumok leképezése

Gyakran nemcsak a jelölést, hanem az attribútumok neveit vagy forrásait is megváltoztatja. Például átválthat a szerző egyszerű karakterláncként való tárolásáról egy gazdag szöveg mezőre. Ilyen esetekben használja a migrate tulajdonságot a régi attribútumok átalakításához az újakra.

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

Ha nem ad meg migrate függvényt, a szerkesztő egyszerűen átadja a régi attribútumokat közvetlenül az új blokknak. Ez hibákat okozhat, ha az attribútumnevek megváltoztak.

4. lépés: Tesztelés valós tartalommal

Az elavult verzió meghatározása után alaposan teszteljen. Hozzon létre egy új bejegyzést, illessze be a régi blokkot (szimulálhatja egy meglévő bejegyzés sorosított blokk kódjának beillesztésével), és ellenőrizze, hogy érvényesítési hibák nélkül átalakul az új verzióra. Tesztelje a konvertált blokk szerkesztését és mentését is. Ismételje meg több elavult verzió esetén, ha vannak ilyenek.

A dinamikus blokkok esetében a folyamat hasonló, de van egy csavar: a dinamikus blokk save függvénye általában null-t ad vissza (a blokk PHP-n keresztül renderelődik). Az elavult bejegyzésben beállíthatja a save-et a korábbi statikus jelölésre, amelyet a dinamikus renderelésre váltás előtt használt, vagy használhat egy render_callback-et PHP-ben, amely kezeli mind a régi, mind az új attribútumszerkezeteket. Ez bonyolultabb, de megvalósítható.

Figyelmeztetések és kompromisszumok

Az elavítás erőteljes, de vannak hátrányai. Minden elavult verzió kódot ad a bővítményhez. Idővel akár öt vagy hat örökölt verzióból álló lánc is kialakulhat, amelyeket ritkán használnak, de karban kell tartani. A WordPress alapcsapat legalább két verzió visszamenőleges megtartását javasolja, de ezen túl fontolóra vehet egy tiszta szakítást, ha az érintett bejegyzések száma kicsi.

Egy másik árnyalat: az elavult bejegyzések sorrendje számít. A szerkesztő a tömbön a 0. indextől felfelé haladva iterál, és az első egyezést használja. Ha két elavult verzió hasonló, akkor a rossz kerülhet alkalmazásra. Mindig a legfrissebb elavult verziót listázza először (azt, amely közvetlenül megelőzi a jelenlegi verziót).

Végül, az elavítás nem kezeli a webhelyszintű stílusváltoztatással (pl. theme.json-en keresztül) szerkesztett tartalmat. Ha a blokk megjelenése olyan globális stílusokon alapult, amelyek azóta megváltoztak, az elavítás nem igazítja ki azt. Lehet, hogy hozzá kell adnia egy migrációs szkriptet, amely mentéskor vagy egy bővítményfrissítési hookon keresztül fut.

Amikor az elavítás nem a megoldás

A legtöbb oktatóanyag kötelezőként állítja be az elavítást. A valóságban vannak olyan helyzetek, amikor a tiszta szakítás jobb. Ha a blokk új, és csak néhány bejegyzésben használják, a néhány példány manuális frissítése gyorsabb lehet, mint az elavítási kód megírása és tesztelése. Hasonlóképpen, ha a blokk mögöttes adatmodell alapvetően különbözik (pl. két blokkot egyesít egybe), az elavítás nem biztos, hogy elég rugalmas. Ebben az esetben írjon egy egyszeri migrációs szkriptet, amely a bővítmény frissítésekor fut, és átalakítja a régi blokkokat az új formátumba.

Egy másik ellentmondásos nézőpont: az elavítást nem szabad a jó tervezés helyettesítőjeként használni. Ha gyakori változásokra számít, tervezze meg a blokkot a verziókezelés figyelembevételével a kezdetektől fogva – például egy version attribútum tárolásával és feltételes renderelés használatával. Ez a megközelítés, amelyet a Túl az alap blokkokon című cikk tárgyal, könnyebb, mint az elavítás, de előrelátást igényel.

Összegzés

A blokk elavítás elengedhetetlen eszköz bármely komoly Gutenberg fejlesztő számára. Lehetővé teszi, hogy blokkjait fejlessze anélkül, hogy megtörné a felhasználók tartalmát. A legfontosabb lépések: rögzítse a jelenlegi állapotot, határozza meg az elavult verziót a block.json fájlban, szükség esetén képezze le az attribútumokat, és teszteljen valós tartalommal. De ne feledje, hogy az elavítás karbantartási költségekkel jár. Néha egy tiszta szakítás vagy egy verziószámozott blokk tervezés pragmatikusabb. Használja az elavítást stratégiailag, ne automatikusan, és blokkjai robusztusak maradnak számos frissítés során.

A karbantartható bővítmények építésének szélesebb körű áttekintéséhez lásd: Robusztus WordPress bővítmények építése. Ha pedig új a blokkfejlesztésben, a Túl az alap blokkokon segít elindulni.