Gutenberg-blok-udfasning: Opdater uden at ødelægge indhold

Resumé

Opdatering af en Gutenberg-blok bryder ofte eksisterende indlæg, der bruger den gamle version. Denne artikel viser dig, hvordan du bruger egenskaben deprecated i block.json for at opretholde bagudkompatibilitet. Du lærer de præcise trin til at fange det aktuelle blokmarkup, definere en eller flere udfasede versioner og kortlægge attributter korrekt. Vi dækker både statiske og dynamiske blokke med praktiske eksempler. Artiklen tager også afstand fra antagelsen om, at udfasning altid er den bedste tilgang, og diskuterer, hvornår et rent brud kan være bedre. Når du er færdig, vil du være i stand til at opdatere dine blokke med selvtillid uden at ødelægge dine brugeres indhold.

Scenariet med den brydende ændring

Du lancerede en tilpasset testimonial-blok for seks måneder siden. Den udskriver en simpel <div> med et citat og et forfatternavn. Nu ønsker din kunde et nyt design: forfatteren skal vises over citatet med en anden CSS-klasse. Du opdaterer blokkens save-funktion og render_callback. Du tester på et nyt indlæg – det ser godt ud. Så navigerer du til et gammelt indlæg, der bruger blokken. Katastrofe: citatteksten er væk, forfatteren er forkert placeret, og stylingen er forkert. Du har netop ødelagt hver side, der bruger blokken.

Dette er det klassiske problem med "brydende ændringer" i Gutenberg-blokudvikling. Blokke er i bund og grund datastrukturer kombineret med markup. Når du ændrer markup, kan editoren ikke automatisk kortlægge gammelt indhold til den nye struktur. Resultatet er enten en valideringsfejl (blokken bliver ugyldig) eller – værre – stille korruption, hvor blokken gengives forkert.

Hvad er blokudfasning?

Blokudfasning er Gutenbergs indbyggede mekanisme til at håndtere versionsændringer. Ved at definere et deprecated-array i din bloks block.json fortæller du editoren: 'Hvis du støder på en blok, der matcher en af disse ældre versioner, omdanner du den til den aktuelle version.' Hver udfaset post specificerer de tidligere attributes, supports og save-funktion (eller render_callback). Når editoren indlæser en gammel blok, gennemgår den det udfasede array i rækkefølge og anvender den første matchende transformation.

Denne funktion bruges ofte ikke nok, fordi udviklere antager, at de aldrig får brug for at ændre en bloks markup. Men i virkelige projekter udvikler kravene sig. Hvis du springer udfasning over, tvinger du enten brugere til at slette og genindsætte blokke (dårlig oplevelse) eller vedligeholder to separate versioner af blokken (rodet). Den officielle WordPress-udviklerhåndbog dækker dette i Block Editor-håndbogen, men praktiske vejledninger mangler.

Trin 1: Fang den aktuelle tilstand

Før du foretager ændringer, skal du optage den nøjagtige save-output (eller render_callback for dynamiske blokke) og de attributes, din blok i øjeblikket bruger. Tænk på det som at tage et snapshot. For statiske blokke skal du gemme JSX, der returneres af save-funktionen. For dynamiske blokke skal du gemme PHP-markup, der genereres af render_callback.

Opret en ny fil i dit plugin kaldet deprecated.js (eller lignende) og gem den gamle save-funktion der. Alternativt kan du beholde de udfasede versioner direkte i blokkens hoved-JavaScript-fil. Nøglen er at bevare denne kode nøjagtigt, som den var, da blokken først blev implementeret.

Trin 2: Definer dine udfasede versioner

I din block.json tilføjer du et deprecated-array. Hver post er et objekt, der kan indeholde:

• attributes (objekt): De tidligere attributdefinitioner.
• supports (objekt): Eventuelle tidligere supportindstillinger, der er ændret.
• save (funktion eller streng): Den tidligere save-funktion. For JavaScript-only-blokke importerer du den gamle funktion. For PHP-gengivede dynamiske blokke kan du bruge migrate og render_callback i stedet.
• migrate (funktion): En funktion, der kortlægger gamle attributter til nye (valgfri).

Eksempel:

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

Bemærk: save-funktionen i block.json er typisk defineret i JavaScript. Hvis du bruger et eksternt script, skal du enqueue det og henvise til funktionsnavnet. Alternativt kan du inline funktionen som en streng (selvom dette ikke anbefales til komplekse blokke).

Trin 3: Kortlæg attributter

Ofte ændrer du ikke kun markup, men også attributnavne eller kilder. For eksempel kan du skifte fra at gemme forfatteren som en almindelig streng til et rigt tekstfelt. I sådanne tilfælde skal du bruge egenskaben migrate til at transformere gamle attributter til nye.

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

Hvis du ikke angiver en migrate-funktion, vil editoren blot sende de gamle attributter direkte til den nye blok. Det kan forårsage fejl, hvis attributnavne er ændret.

Trin 4: Test med rigtigt indhold

Efter at have defineret den udfasede version, skal du teste grundigt. Opret et nyt indlæg, indsæt den gamle blok (du kan simulere ved at indsætte den serialiserede blokkode fra et eksisterende indlæg), og bekræft, at den konverteres til den nye version uden valideringsfejl. Test også redigering og gemning af den konverterede blok. Gentag for flere udfasede versioner, hvis du har dem.

For dynamiske blokke er processen ens, men med en drejning: save-funktionen for en dynamisk blok returnerer typisk null (blokken gengives via PHP). I den udfasede post kan du enten sætte save til det tidligere statiske markup, der blev brugt, før du skiftede til dynamisk gengivelse, eller bruge en render_callback i PHP, der håndterer både gamle og nye attributstrukturer. Dette er mere komplekst, men muligt.

Forbehold og afvejninger

Udfasning er kraftfuldt, men det har ulemper. Hver udfaset version tilføjer kode til dit plugin. Over tid kan du ende med en kæde på fem eller seks ældre versioner, der sjældent bruges, men som skal vedligeholdes. WordPress-kerneholdet anbefaler at beholde mindst to versioner tilbage, men ud over det kan du overveje et rent brud, hvis antallet af berørte indlæg er lille.

En anden nuance: rækkefølgen af udfasede poster har betydning. Editoren itererer gennem arrayet fra indeks 0 og opefter og bruger den første match. Hvis to udfasede versioner ligner hinanden, kan den forkerte blive anvendt. Angiv altid den seneste udfasede version først (den, der umiddelbart går forud for den aktuelle version).

Endelig håndterer udfasning ikke indhold, der er redigeret ved hjælp af en sidebredde stilændring (f.eks. via theme.json). Hvis din bloks udseende var afhængig af globale stilarter, der siden er ændret, vil udfasningen ikke justere for det. Du skal muligvis tilføje et migrationsscript, der kører ved gemning eller via et plugin-opdateringshook.

Hvornår udfasning ikke er svaret

De fleste tutorials præsenterer udfasning som obligatorisk. I virkeligheden er der situationer, hvor et rent brud er bedre. Hvis din blok er ny og kun bruges i en håndfuld indlæg, kan manuel opdatering af disse få eksempler være hurtigere end at skrive og teste udfasningskode. Tilsvarende, hvis blokkens underliggende datamodel er fundamentalt anderledes (f.eks. hvis du fusionerer to blokke til én), er udfasning måske ikke fleksibel nok. I så fald skal du skrive et engangsmigrationsscript, der kører, når plugin'et opdateres, og konverterer gamle blokke til det nye format.

Et andet kontrapunkt: udfasning bør ikke bruges som erstatning for godt design. Hvis du forventer hyppige ændringer, skal du designe din blok med versionsstyring i tankerne fra starten – f.eks. ved at gemme en version-attribut og bruge betinget gengivelse. Denne tilgang, som diskuteres i Beyond Basic Blocks, er lettere end udfasning, men kræver forudseenhed.

Konklusion

Blokudfasning er et essentielt værktøj for enhver seriøs Gutenberg-udvikler. Det giver dig mulighed for at udvikle dine blokke uden at ødelægge brugernes indhold. De vigtigste trin er: fang den aktuelle tilstand, definer den udfasede version i block.json, kortlæg attributter om nødvendigt, og test med rigtigt indhold. Men husk, at udfasning medfører vedligeholdelsesomkostninger. Nogle gange er et rent brud eller et versioneret blokdesign mere pragmatisk. Brug udfasning strategisk, ikke automatisk, og dine blokke forbliver robuste gennem mange opdateringer.

For et bredere perspektiv på at bygge vedligeholdelsesvenlige plugins, se Building Robust WordPress Plugins. Og hvis du er ny inden for blokudvikling, vil Beyond Basic Blocks hjælpe dig i gang.