Utfasning av Gutenberg-block: Uppdatera utan att bryta innehåll

Sammanfattning

Att uppdatera ett Gutenberg-block bryter ofta befintliga inlägg som använder den gamla versionen. Den här artikeln visar hur du använder egenskapen deprecated i block.json för att bibehålla bakåtkompatibilitet. Du lär dig exakt hur du fångar den aktuella blockmarkeringen, definierar en eller flera föråldrade versioner och mappar attribut korrekt. Vi täcker både statiska och dynamiska block med praktiska exempel. Artikeln ifrågasätter också antagandet att utfasning alltid är bäst och diskuterar när en ren brytning kan vara bättre. I slutet kommer du att kunna uppdatera dina block med självförtroende utan att bryta dina användares innehåll.

Scenariot med brytande förändring

Du lanserade ett anpassat vittnesmålblock för sex månader sedan. Det genererar en enkel <div> med ett citat och ett författarnamn. Nu vill din kund ha en ny design: författaren ska visas ovanför citatet, med en annan CSS-klass. Du uppdaterar blockets save-funktion och render_callback. Du testar på ett nytt inlägg – det ser bra ut. Sedan navigerar du till ett gammalt inlägg som använder blocket. Katastrof: citattexten är borta, författaren är på fel plats och stilen är fel. Du har precis brutit varje sida som använder blocket.

Detta är det klassiska problemet med brytande förändringar i Gutenberg-blockutveckling. Block är i princip datastrukturer kombinerade med markup. När du ändrar markup kan redigeraren inte automatiskt mappa gammalt innehåll till den nya strukturen. Resultatet är antingen ett valideringsfel (blocket blir ogiltigt) eller – värre – tyst korruption där blocket renderas felaktigt.

Vad är blockutfasning?

Blockutfasning är Gutenbergs inbyggda mekanism för att hantera versionsförändringar. Genom att definiera en deprecated-array i blockets block.json talar du om för redigeraren: "Om du stöter på ett block som matchar en av dessa äldre versioner, transformera det till den aktuella versionen." Varje utfasningspost specificerar de tidigare attributes, supports och save-funktionen (eller render_callback). När redigeraren laddar ett gammalt block går den igenom utfasningsarrayen i ordning och tillämpar den första matchande transformationen.

Denna funktion är ofta underutnyttjad eftersom utvecklare antar att de aldrig kommer att behöva ändra ett blocks markup. Men i verkliga projekt utvecklas kraven. Om du hoppar över utfasning tvingar du antingen användare att ta bort och återinfoga block (dålig upplevelse) eller underhålla två separata versioner av blocket (rörigt). Den officiella WordPress-utvecklarhandboken täcker detta i Block Editor Handbook, men praktiska genomgångar saknas.

Steg 1: Fånga det aktuella tillståndet

Innan du gör några ändringar, registrera exakt save-utdata (eller render_callback för dynamiska block) och de attributes som ditt block för närvarande använder. Se det som att ta en ögonblicksbild. För statiska block, spara JSX som returneras av save-funktionen. För dynamiska block, spara PHP-markup som genereras av render_callback.

Skapa en ny fil i ditt plugin som heter deprecated.js (eller liknande) och lagra den gamla save-funktionen där. Alternativt kan du behålla de föråldrade versionerna direkt i blockets huvud-JavaScript-fil. Nyckeln är att bevara denna kod exakt som den var när blocket först distribuerades.

Steg 2: Definiera dina föråldrade versioner

I din block.json, lägg till en deprecated-array. Varje post är ett objekt som kan innehålla:

• attributes (objekt): De tidigare attributdefinitionerna.
• supports (objekt): Eventuella tidigare supportinställningar som ändrats.
• save (funktion eller sträng): Den tidigare save-funktionen. För JavaScript-only-block importerar du den gamla funktionen. För PHP-renderade dynamiska block kan du använda migrate och render_callback istället.
• migrate (funktion): En funktion som mappar gamla attribut till nya (valfritt).

Exempel:

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

Observera: save-funktionen i block.json definieras vanligtvis i JavaScript. Om du använder ett externt skript måste du köa det och referera till funktionsnamnet. Alternativt kan du infoga funktionen som en sträng (men detta rekommenderas inte för komplexa block).

Steg 3: Mappa attribut

Ofta ändrar du inte bara markup utan även attributnamn eller källor. Till exempel kan du byta från att lagra författaren som en vanlig sträng till ett rikt textfält. I sådana fall använder du egenskapen migrate för att transformera gamla attribut till nya.

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

Om du inte tillhandahåller en migrate-funktion kommer redigeraren helt enkelt att skicka de gamla attributen direkt till det nya blocket. Det kan orsaka fel om attributnamn ändrats.

Steg 4: Testa med verkligt innehåll

Efter att ha definierat den föråldrade versionen, testa noggrant. Skapa ett nytt inlägg, infoga det gamla blocket (du kan simulera genom att klistra in den serialiserade blockkoden från ett befintligt inlägg) och verifiera att det konverteras till den nya versionen utan valideringsfel. Testa också att redigera och spara det konverterade blocket. Upprepa för flera föråldrade versioner om du har dem.

För dynamiska block är processen liknande men med en twist: save-funktionen för ett dynamiskt block returnerar vanligtvis null (blocket renderas via PHP). I utfasningsposten kan du antingen ställa in save på den tidigare statiska markup som användes innan du bytte till dynamisk rendering, eller använda en render_callback i PHP som hanterar både gamla och nya attributstrukturer. Detta är mer komplext men görbart.

Varningar och avvägningar

Utfasning är kraftfullt, men har nackdelar. Varje föråldrad version lägger till kod i ditt plugin. Med tiden kan du hamna med en kedja av fem eller sex äldre versioner som sällan används men måste underhållas. WordPress kärnteam rekommenderar att hålla minst två versioner bakåt, men utöver det kan du överväga en ren brytning om antalet påverkade inlägg är litet.

En annan nyans: ordningen på utfasningsposter spelar roll. Redigeraren itererar genom arrayen från index 0 och uppåt och använder den första matchningen. Om två föråldrade versioner är lika kan fel en tillämpas. Lista alltid den senaste föråldrade versionen först (den som direkt föregår den aktuella versionen).

Slutligen hanterar utfasning inte innehåll som redigerats med en webbplatsövergripande stiländring (t.ex. via theme.json). Om ditt blocks utseende förlitade sig på globala stilar som sedan ändrats, kommer utfasningen inte att justera för det. Du kan behöva lägga till ett migreringsskript som körs vid sparning eller via en plugin-uppdateringskrok.

När utfasning inte är svaret

De flesta handledningar framställer utfasning som obligatorisk. I verkligheten finns det situationer där en ren brytning är bättre. Om ditt block är nytt och används i endast en handfull inlägg, kan manuell uppdatering av dessa få instanser vara snabbare än att skriva och testa utfasningskod. På samma sätt, om blockets underliggande datamodell är fundamentalt annorlunda (t.ex. slår du samman två block till ett), kanske utfasning inte är tillräckligt flexibel. I så fall, skriv ett engångsmigreringsskript som körs när pluginen uppdateras, och konverterar gamla block till det nya formatet.

En annan kontroversiell punkt: utfasning bör inte användas som ersättning för god design. Om du förutser frekventa ändringar, designa ditt block med versionshantering i åtanke från början – t.ex. genom att lagra en version-attribut och använda villkorlig rendering. Detta tillvägagångssätt, diskuterat i Beyond Basic Blocks, är lättare än utfasning men kräver framförhållning.

Slutsats

Blockutfasning är ett viktigt verktyg för alla seriösa Gutenberg-utvecklare. Det låter dig utveckla dina block utan att bryta användarnas innehåll. De viktigaste stegen är: fånga det aktuella tillståndet, definiera den föråldrade versionen i block.json, mappa attribut om det behövs och testa med verkligt innehåll. Men kom ihåg att utfasning medför underhållskostnader. Ibland är en ren brytning eller ett versionshanterat blockdesign mer pragmatiskt. Använd utfasning strategiskt, inte automatiskt, så kommer dina block att förbli robusta genom många uppdateringar.

För ett bredare perspektiv på att bygga underhållbara plugins, se Building Robust WordPress Plugins. Och om du är ny inom blockutveckling, hjälper Beyond Basic Blocks dig att komma igång.