Gutenberg Block Deprecatie: Update Zonder Inhoud te Breken

Samenvatting

Het updaten van een Gutenberg-blok breekt vaak bestaande berichten die de oude versie gebruiken. Dit artikel laat u zien hoe u de deprecated eigenschap in block.json kunt gebruiken om achterwaartse compatibiliteit te behouden. U leert de exacte stappen om de huidige blokmarkup vast te leggen, een of meer verouderde versies te definiëren en attributen correct te mappen. We behandelen zowel statische als dynamische blokken, met praktische voorbeelden. Het artikel weerlegt ook de aanname dat deprecatie altijd de beste aanpak is, en bespreekt wanneer een schone breuk beter kan zijn. Uiteindelijk kunt u uw blokken met vertrouwen updaten zonder de inhoud van uw gebruikers te breken.

Het Scenario van de Brekende Verandering

U heeft zes maanden geleden een aangepast testimonial-blok gelanceerd. Het geeft een eenvoudige <div> weer met een citaat en een auteursnaam. Nu wil uw klant een nieuw ontwerp: de auteur moet boven het citaat verschijnen, met een andere CSS-klasse. U werkt de save-functie en render_callback van het blok bij. U test op een nieuw bericht—het ziet er geweldig uit. Vervolgens navigeert u naar een oud bericht dat het blok gebruikt. Ramp: de citattekst is verdwenen, de auteur staat op de verkeerde plaats en de opmaak is verkeerd. U heeft zojuist elke pagina gebroken die het blok gebruikt.

Dit is het klassieke probleem van een "brekende verandering" in Gutenberg-blokontwikkeling. Blokken zijn in wezen datastructuren gecombineerd met markup. Wanneer u de markup wijzigt, kan de editor niet automatisch oude inhoud naar de nieuwe structuur mappen. Het resultaat is ofwel een validatiefout (het blok wordt ongeldig) of—erger—stille corruptie waarbij het blok onjuist wordt weergegeven.

Wat is Blokdeprecatie?

Blokdeprecatie is het ingebouwde mechanisme van Gutenberg voor het afhandelen van versiewijzigingen. Door een deprecated-array in de block.json van uw blok te definiëren, vertelt u de editor: "Als u een blok tegenkomt dat overeenkomt met een van deze oudere versies, transformeer het dan naar de huidige versie." Elke verouderde invoer specificeert de vorige attributes, supports en save-functie (of render_callback). Wanneer de editor een oud blok laadt, doorloopt hij de deprecated-array in volgorde en past de eerste overeenkomende transformatie toe.

Deze functie wordt vaak onderbenut omdat ontwikkelaars aannemen dat ze nooit de markup van een blok hoeven te wijzigen. Maar in echte projecten veranderen de vereisten. Als u deprecatie overslaat, dwingt u gebruikers om blokken te verwijderen en opnieuw in te voegen (slechte ervaring) of onderhoudt u twee aparte versies van het blok (rommelig). De officiële WordPress-ontwikkelaarshandleiding behandelt dit in de Block Editor-handleiding, maar praktische doorlopen ontbreken.

Stap 1: Leg de Huidige Staat Vast

Voordat u wijzigingen aanbrengt, legt u de exacte save-uitvoer (of render_callback voor dynamische blokken) en de attributes vast die uw blok momenteel gebruikt. Zie het als het maken van een snapshot. Voor statische blokken slaat u de JSX op die door de save-functie wordt teruggegeven. Voor dynamische blokken slaat u de PHP-markup op die door render_callback wordt gegenereerd.

Maak een nieuw bestand in uw plugin met de naam deprecated.js (of iets dergelijks) en sla de oude save-functie daarin op. U kunt de verouderde versies ook rechtstreeks in het hoofd JavaScript-bestand van het blok bewaren. Het belangrijkste is om deze code exact te bewaren zoals deze was toen het blok voor het eerst werd geïmplementeerd.

Stap 2: Definieer Uw Verouderde Versies

Voeg in uw block.json een deprecated-array toe. Elke invoer is een object dat kan bevatten:

• attributes (object): De vorige attribuutdefinities.
• supports (object): Eventuele eerdere ondersteuningsinstellingen die zijn gewijzigd.
• save (functie of string): De vorige save-functie. Voor alleen-JavaScript-blokken importeert u de oude functie. Voor PHP-gerenderde dynamische blokken kunt u in plaats daarvan migrate en render_callback gebruiken.
• migrate (functie): Een functie die oude attributen naar nieuwe mapt (optioneel).

Voorbeeld:

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

Let op: De save-functie in block.json wordt meestal gedefinieerd in JavaScript. Als u een extern script gebruikt, moet u het in de wachtrij plaatsen en naar de functienaam verwijzen. U kunt de functie ook inline als string zetten (hoewel dit niet wordt aanbevolen voor complexe blokken).

Stap 3: Attributen Mappen

Vaak wijzigt u niet alleen de markup, maar ook de attribuutnamen of bronnen. U kunt bijvoorbeeld overschakelen van het opslaan van de auteur als een gewone string naar een rich-tekstveld. Gebruik in dergelijke gevallen de migrate-eigenschap om oude attributen naar nieuwe te transformeren.

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

Als u geen migrate-functie opgeeft, zal de editor eenvoudig de oude attributen rechtstreeks doorgeven aan het nieuwe blok. Dit kan fouten veroorzaken als attribuutnamen zijn gewijzigd.

Stap 4: Test met Echte Inhoud

Na het definiëren van de verouderde versie, grondig testen. Maak een nieuw bericht, voeg het oude blok in (u kunt het simuleren door de geserialiseerde blokcode uit een bestaand bericht te plakken) en controleer of het naar de nieuwe versie converteert zonder validatiefouten. Test ook het bewerken en opslaan van het geconverteerde blok. Herhaal dit voor meerdere verouderde versies als u die heeft.

Voor dynamische blokken is het proces vergelijkbaar maar met een twist: de save-functie voor een dynamisch blok retourneert typisch null (het blok wordt via PHP weergegeven). In de verouderde invoer kunt u save instellen op de vorige statische markup die werd gebruikt voordat u overschakelde naar dynamische weergave, of een render_callback in PHP gebruiken die zowel oude als nieuwe attribuutstructuren afhandelt. Dit is complexer maar haalbaar.

Kanttekeningen en Afwegingen

Deprecatie is krachtig, maar heeft nadelen. Elke verouderde versie voegt code toe aan uw plugin. Na verloop van tijd kunt u een keten van vijf of zes oude versies krijgen die zelden worden gebruikt maar toch moeten worden onderhouden. Het WordPress-kernteam raadt aan om ten minste twee versies terug te houden, maar daarboven kunt u een schone breuk overwegen als het aantal getroffen berichten klein is.

Een andere nuance: de volgorde van verouderde invoeren is belangrijk. De editor doorloopt de array van index 0 omhoog en gebruikt de eerste overeenkomst. Als twee verouderde versies vergelijkbaar zijn, kan de verkeerde worden toegepast. Zet altijd de meest recente verouderde versie eerst (degene die direct voorafgaat aan de huidige versie).

Tot slot: deprecatie behandelt geen inhoud die is bewerkt met een site-brede stijlwijziging (bijv. via theme.json). Als het uiterlijk van uw blok afhankelijk was van algemene stijlen die sindsdien zijn gewijzigd, zal de deprecatie dat niet aanpassen. U moet mogelijk een migratiescript toevoegen dat wordt uitgevoerd bij opslaan of via een plugin-updatehook.

Wanneer Deprecatie Niet het Antwoord Is

De meeste tutorials presenteren deprecatie als verplicht. In werkelijkheid zijn er situaties waarin een schone breuk beter is. Als uw blok nieuw is en slechts in een handvol berichten wordt gebruikt, kan het handmatig bijwerken van die enkele exemplaren sneller zijn dan het schrijven en testen van deprecatiecode. Evenzo, als het onderliggende gegevensmodel van het blok fundamenteel anders is (bijv. u voegt twee blokken samen), is deprecatie mogelijk niet flexibel genoeg. Schrijf in dat geval een eenmalig migratiescript dat wordt uitgevoerd wanneer de plugin wordt bijgewerkt, waarbij oude blokken naar het nieuwe formaat worden geconverteerd.

Nog een tegendraads punt: deprecatie mag niet worden gebruikt als vervanging voor goed ontwerp. Als u frequente wijzigingen verwacht, ontwerp uw blok dan vanaf het begin met versiebeheer in gedachten—bijv. door een version-attribuut op te slaan en conditionele weergave te gebruiken. Deze aanpak, besproken in Beyond Basic Blocks, is lichter dan deprecatie maar vereist vooruitziendheid.

Conclusie

Blokdeprecatie is een essentieel hulpmiddel voor elke serieuze Gutenberg-ontwikkelaar. Het stelt u in staat om uw blokken te evolueren zonder de inhoud van gebruikers te breken. De belangrijkste stappen zijn: leg de huidige staat vast, definieer de verouderde versie in block.json, map attributen indien nodig, en test met echte inhoud. Maar onthoud dat deprecatie onderhoudskosten met zich meebrengt. Soms is een schone breuk of een versiebeheerd blokontwerp pragmatischer. Gebruik deprecatie strategisch, niet automatisch, en uw blokken zullen robuust blijven door vele updates heen.

Voor een breder perspectief op het bouwen van onderhoudbare plugins, zie Building Robust WordPress Plugins. En als u nieuw bent in blokontwikkeling, helpt Beyond Basic Blocks u op weg.