Zastarávání bloků Gutenberg: Aktualizujte bez narušení obsahu

Shrnutí

Aktualizace bloku Gutenberg často rozbije existující příspěvky, které používají starou verzi. Tento článek ukazuje, jak použít vlastnost deprecated v block.json k zachování zpětné kompatibility. Dozvíte se přesné kroky k zachycení aktuálního značení bloku, definování jedné nebo více zastaralých verzí a správnému mapování atributů. Probereme statické i dynamické bloky s praktickými příklady. Článek také zpochybňuje předpoklad, že zastarávání je vždy tím nejlepším přístupem, a diskutuje, kdy může být čistý zlom lepší. Nakonec budete schopni aktualizovat své bloky s důvěrou, aniž byste narušili obsah uživatelů.

Scénář zlomové změny

Před šesti měsíci jste spustili vlastní blok posudku. Výstupem je jednoduchý <div> s citátem a jménem autora. Nyní váš klient chce nový design: autor by se měl objevit nad citátem s jinou CSS třídou. Aktualizujete funkci save a render_callback bloku. Otestujete na novém příspěvku – vypadá skvěle. Pak přejdete na starý příspěvek, který blok používá. Katastrofa: text citátu je pryč, autor je na špatném místě a stylování je rozhozené. Právě jste rozbili každou stránku, která blok používá.

Toto je klasický problém „zlomové změny“ ve vývoji bloků Gutenberg. Bloky jsou v podstatě datové struktury kombinované se značením. Když změníte značení, editor nemůže automaticky mapovat starý obsah na novou strukturu. Výsledkem je buď validační chyba (blok se stane neplatným), nebo – hůře – tichá korupce, kdy se blok vykresluje nesprávně.

Co je zastarávání bloků?

Zastarávání bloků je vestavěný mechanismus Gutenbergu pro správu změn verzí. Definováním pole deprecated v block.json vašeho bloku sdělujete editoru: „Pokud narazíš na blok, který odpovídá jedné z těchto starších verzí, transformuj ho na aktuální verzi.“ Každá položka zastarání specifikuje předchozí attributes, supports a funkci save (nebo render_callback). Když editor načte starý blok, projde pole zastarání v pořadí a použije první odpovídající transformaci.

Tato funkce je často nedostatečně využívána, protože vývojáři předpokládají, že nikdy nebudou muset měnit značení bloku. Ale v reálných projektech se požadavky vyvíjejí. Pokud zastarávání přeskočíte, buď donutíte uživatele mazat a znovu vkládat bloky (špatná zkušenost), nebo udržovat dvě samostatné verze bloku (nepřehledné). Oficiální příručka vývojáře WordPressu toto pokrývá v Příručce editoru bloků, ale praktické návody chybí.

Krok 1: Zachyťte aktuální stav

Před jakýmikoli změnami zaznamenejte přesný výstup save (nebo render_callback pro dynamické bloky) a attributes, které váš blok aktuálně používá. Berte to jako pořízení snímku. U statických bloků uložte JSX vrácené funkcí save. U dynamických bloků uložte PHP značení vygenerované render_callback.

Vytvořte nový soubor ve svém pluginu s názvem deprecated.js (nebo podobně) a uložte tam starou funkci save. Případně ponechte zastaralé verze přímo v hlavním JavaScriptovém souboru bloku. Klíčové je zachovat tento kód přesně tak, jak byl, když byl blok poprvé nasazen.

Krok 2: Definujte své zastaralé verze

Do block.json přidejte pole deprecated. Každá položka je objekt, který může obsahovat:

• attributes (objekt): Předchozí definice atributů.
• supports (objekt): Jakákoli předchozí nastavení podpory, která se změnila.
• save (funkce nebo řetězec): Předchozí funkce save. U JavaScriptových bloků naimportujete starou funkci. U PHP vykreslovaných dynamických bloků můžete místo toho použít migrate a render_callback.
• migrate (funkce): Funkce, která mapuje staré atributy na nové (volitelné).

Pří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: Funkce save v block.json je obvykle definována v JavaScriptu. Pokud používáte externí skript, budete ho muset zařadit a odkazovat na název funkce. Případně můžete funkci vložit jako řetězec (i když to není doporučeno pro složité bloky).

Krok 3: Mapujte atributy

Často měníte nejen značení, ale také názvy atributů nebo zdroje. Například můžete přejít od ukládání autora jako prostého řetězce k poli formátovaného textu. V takových případech použijte vlastnost migrate k transformaci starých atributů na nové.

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

Pokud neposkytnete funkci migrate, editor jednoduše předá staré atributy přímo novému bloku. To může způsobit chyby, pokud se názvy atributů změnily.

Krok 4: Testujte s reálným obsahem

Po definování zastaralé verze důkladně otestujte. Vytvořte nový příspěvek, vložte starý blok (můžete simulovat vložením serializovaného kódu bloku z existujícího příspěvku) a ověřte, že se převede na novou verzi bez validačních chyb. Také otestujte úpravu a uložení převedeného bloku. Opakujte pro více zastaralých verzí, pokud je máte.

Pro dynamické bloky je proces podobný, ale s odlišností: funkce save u dynamického bloku obvykle vrací null (blok se vykresluje přes PHP). V položce zastarání můžete buď nastavit save na předchozí statické značení, které bylo použito před přechodem na dynamické vykreslování, nebo použít render_callback v PHP, který zpracovává staré i nové struktury atributů. To je složitější, ale proveditelné.

Výhrady a kompromisy

Zastarávání je mocný nástroj, ale má své nevýhody. Každá zastaralá verze přidává kód do vašeho pluginu. Postupem času můžete skončit s řetězcem pěti nebo šesti starých verzí, které se zřídka používají, ale musí být udržovány. Tým WordPress Core doporučuje zachovávat alespoň dvě verze zpět, ale za tímto bodem můžete zvážit čistý zlom, pokud je počet ovlivněných příspěvků malý.

Další nuance: pořadí položek zastarání je důležité. Editor prochází pole od indexu 0 nahoru a použije první shodu. Pokud jsou dvě zastaralé verze podobné, může být použita nesprávná. Vždy uvádějte nejnovější zastaralou verzi jako první (tu, která bezprostředně předchází aktuální verzi).

A konečně, zastarávání nezpracovává obsah, který byl upraven pomocí celostylové změny (např. prostřednictvím theme.json). Pokud vzhled vašeho bloku spoléhal na globální styly, které se od té doby změnily, zastarávání to neupraví. Možná budete muset přidat migrační skript, který se spustí při uložení nebo pomocí háku při aktualizaci pluginu.

Kdy zastarávání není odpovědí

Většina tutoriálů prezentuje zastarávání jako povinné. Ve skutečnosti existují situace, kdy je lepší čistý zlom. Pokud je váš blok nový a používaný jen v hrstce příspěvků, ruční aktualizace těchto několika instancí může být rychlejší než psaní a testování kódu zastarání. Podobně, pokud je základní datový model bloku zásadně odlišný (např. slučujete dva bloky do jednoho), zastarávání nemusí být dostatečně flexibilní. V takovém případě napište jednorázový migrační skript, který se spustí při aktualizaci pluginu a převede staré bloky do nového formátu.

Další opoziční bod: zastarávání by nemělo být používáno jako náhrada za dobrý design. Pokud očekáváte časté změny, navrhněte svůj blok s ohledem na verzování od začátku – například uložením atributu version a použitím podmíněného vykreslování. Tento přístup, popsaný v Nad rámec základních bloků, je lehčí než zastarávání, ale vyžaduje předvídavost.

Závěr

Zastarávání bloků je nezbytným nástrojem pro každého seriózního vývojáře Gutenbergu. Umožňuje vám vyvíjet vaše bloky, aniž byste narušili obsah uživatelů. Klíčové kroky jsou: zachycení aktuálního stavu, definice zastaralé verze v block.json, mapování atributů, pokud je to nutné, a testování s reálným obsahem. Ale pamatujte, že zastarávání s sebou nese náklady na údržbu. Někdy je pragmatičtější čistý zlom nebo blok s verzováním. Používejte zastarávání strategicky, ne automaticky, a vaše bloky zůstanou robustní během mnoha aktualizací.

Pro širší pohled na budování udržovatelných pluginů se podívejte na Building Robust WordPress Plugins. A pokud jste nováčkem ve vývoji bloků, Nad rámec základních bloků vám pomůže začít.