Gutenberg-blokk-avskrivning: Oppdater uten å bryte innhold

Sammendrag

Å oppdatere en Gutenberg-blokk ødelegger ofte eksisterende innlegg som bruker den gamle versjonen. Denne artikkelen viser deg hvordan du bruker deprecated-egenskapen i block.json for å opprettholde bakoverkompatibilitet. Du lærer de nøyaktige trinnene for å fange gjeldende blokkmarkering, definere én eller flere avskrevne versjoner og kartlegge attributter riktig. Vi dekker både statiske og dynamiske blokker, med praktiske eksempler. Artikkelen tar også et oppgjør med antagelsen om at avskrivning alltid er den beste tilnærmingen, og diskuterer når et rent brudd kan være bedre. Mot slutten vil du kunne oppdatere blokkene dine trygt uten å ødelegge brukernes innhold.

Endringsscenarioet som ødelegger

Du lanserte en tilpasset testimonial-blokk for seks måneder siden. Den sender ut en enkel <div> med et sitat og et forfatternavn. Nå ønsker kunden din en ny utforming: forfatteren skal vises over sitatet, med en annen CSS-klasse. Du oppdaterer blokkens save-funksjon og render_callback. Du tester på et nytt innlegg – det ser flott ut. Så navigerer du til et gammelt innlegg som bruker blokken. Katastrofe: sitatteksten er borte, forfatteren er på feil sted, og stilen er feil. Du har nettopp ødelagt hver side som bruker blokken.

Dette er det klassiske «endringsscenarioet som ødelegger» i Gutenberg-blokkutvikling. Blokker er i bunn og grunn datastrukturer kombinert med markering. Når du endrer markeringen, kan ikke redigeringsprogrammet automatisk kartlegge gammelt innhold til den nye strukturen. Resultatet er enten en valideringsfeil (blokken blir ugyldig) eller – enda verre – stille korrupsjon der blokken vises feil.

Hva er blokkavskrivning?

Blokkavskrivning er Gutenbergs innebygde mekanisme for å håndtere versjonsendringer. Ved å definere en deprecated-matrise i blokkens block.json forteller du redigeringsprogrammet: «Hvis du støter på en blokk som samsvarer med én av disse eldre versjonene, transformer den til gjeldende versjon.» Hver avskrevne oppføring spesifiserer de tidligere attributes, supports og save-funksjonen (eller render_callback). Når redigeringsprogrammet laster en gammel blokk, går det gjennom avskrivningsmatrisen i rekkefølge og bruker den første samsvarende transformasjonen.

Denne funksjonen er ofte lite brukt fordi utviklere antar at de aldri vil trenge å endre en blokks markering. Men i virkelige prosjekter utvikler kravene seg. Hvis du hopper over avskrivning, tvinger du enten brukere til å slette og sette inn blokker på nytt (dårlig opplevelse) eller vedlikeholde to separate versjoner av blokken (rotete). Den offisielle WordPress-utviklerhåndboken dekker dette i Block Editor Handbook, men praktiske gjennomganger mangler.

Trinn 1: Fang gjeldende tilstand

Før du gjør endringer, noter nøyaktig save-utdata (eller render_callback for dynamiske blokker) og attributes blokken din bruker for øyeblikket. Tenk på det som å ta et øyeblikksbilde. For statiske blokker, lagre JSX-en som returneres av save-funksjonen. For dynamiske blokker, lagre PHP-markeringen generert av render_callback.

Opprett en ny fil i programtillegget ditt kalt deprecated.js (eller lignende) og lagre den gamle save-funksjonen der. Alternativt kan du beholde de avskrevne versjonene direkte i blokkens hoved-JavaScript-fil. Nøkkelen er å bevare denne koden nøyaktig slik den var da blokken først ble distribuert.

Trinn 2: Definer dine avskrevne versjoner

I block.json legger du til en deprecated-matrise. Hver oppføring er et objekt som kan inneholde:

• attributes (objekt): De tidligere attributtdefinisjonene.
• supports (objekt): Eventuelle tidligere støtteinnstillinger som ble endret.
• save (funksjon eller streng): Den tidligere save-funksjonen. For JavaScript-bare blokker importerer du den gamle funksjonen. For PHP-rendrede dynamiske blokker kan du bruke migrate og render_callback i stedet.
• migrate (funksjon): En funksjon som kartlegger gamle attributter til nye (valgfritt).

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

Merk: save-funksjonen i block.json er typisk definert i JavaScript. Hvis du bruker et eksternt skript, må du køe det og referere til funksjonsnavnet. Alternativt kan du inline funksjonen som en streng (selv om dette ikke anbefales for komplekse blokker).

Trinn 3: Kartlegg attributter

Ofte endrer du ikke bare markeringen, men også attributtnavn eller kilder. For eksempel kan du bytte fra å lagre forfatteren som en ren streng til et riktekstfelt. I slike tilfeller bruker du migrate-egenskapen for å transformere gamle attributter til nye.

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

Hvis du ikke oppgir en migrate-funksjon, vil redigeringsprogrammet bare sende de gamle attributtene direkte til den nye blokken. Det kan forårsake feil hvis attributtnavn er endret.

Trinn 4: Test med ekte innhold

Etter å ha definert den avskrevne versjonen, test grundig. Opprett et nytt innlegg, sett inn den gamle blokken (du kan simulere ved å lime inn serialisert blokkode fra et eksisterende innlegg), og bekreft at den konverteres til den nye versjonen uten valideringsfeil. Test også redigering og lagring av den konverterte blokken. Gjenta for flere avskrevne versjoner hvis du har dem.

For dynamiske blokker er prosessen lik, men med en vri: save-funksjonen for en dynamisk blokk returnerer typisk null (blokken gjengis via PHP). I den avskrevne oppføringen kan du enten sette save til den tidligere statiske markeringen som ble brukt før du byttet til dynamisk gjengivelse, eller bruke en render_callback i PHP som håndterer både gamle og nye attributtstrukturer. Dette er mer komplekst, men mulig.

Forbehold og avveininger

Avskrivning er kraftig, men har ulemper. Hver avskrevne versjon legger til kode i programtillegget ditt. Over tid kan du ende opp med en kjede på fem eller seks eldre versjoner som sjelden brukes, men som må vedlikeholdes. WordPress-kjerneteamet anbefaler å beholde minst to versjoner tilbake, men utover det kan du vurdere et rent brudd hvis antallet berørte innlegg er lite.

En annen nyanse: rekkefølgen på avskrevne oppføringer er viktig. Redigeringsprogrammet itererer gjennom matrisen fra indeks 0 og oppover og bruker det første treffet. Hvis to avskrevne versjoner er like, kan feil versjon bli brukt. List alltid den nyeste avskrevne versjonen først (den som umiddelbart går foran gjeldende versjon).

Til slutt håndterer ikke avskrivning innhold som ble redigert med en nettsteddekkende stilendring (f.eks. via theme.json). Hvis blokkens utseende stolte på globale stiler som siden har endret seg, vil ikke avskrivningen justere for det. Du må kanskje legge til et migreringsskript som kjører ved lagring eller via en programtilleggsoppdateringskrok.

Når avskrivning ikke er svaret

De fleste veiledninger fremstiller avskrivning som obligatorisk. I virkeligheten er det situasjoner der et rent brudd er bedre. Hvis blokken din er ny og brukes i bare en håndfull innlegg, kan det være raskere å manuelt oppdatere disse få tilfellene enn å skrive og teste avskrivningskode. På samme måte, hvis blokkens underliggende datamodell er fundamentalt annerledes (f.eks. slår du sammen to blokker til én), kan avskrivning være for lite fleksibelt. I så fall, skriv et engangsmigreringsskript som kjører når programtillegget oppdateres, og konverterer gamle blokker til det nye formatet.

Et annet kontroversielt poeng: avskrivning skal ikke brukes som en erstatning for god design. Hvis du forventer hyppige endringer, design blokken din med versjonering i tankene fra starten – for eksempel ved å lagre en version-attributt og bruke betinget gjengivelse. Denne tilnærmingen, diskutert i Beyond Basic Blocks, er lettere enn avskrivning, men krever framsyn.

Konklusjon

Blokkavskrivning er et viktig verktøy for enhver seriøs Gutenberg-utvikler. Det lar deg utvikle blokkene dine uten å ødelegge brukernes innhold. Nøkkeltrinnene er: fang gjeldende tilstand, definer den avskrevne versjonen i block.json, kartlegg attributter om nødvendig, og test med ekte innhold. Men husk at avskrivning medfører vedlikeholdskostnader. Noen ganger er et rent brudd eller en versjonert blokkdesign mer pragmatisk. Bruk avskrivning strategisk, ikke automatisk, og blokkene dine vil forbli robuste gjennom mange oppdateringer.

For et bredere perspektiv på å bygge vedlikeholdbare programtillegg, se Building Robust WordPress Plugins. Og hvis du er ny innen blokkutvikling, vil Beyond Basic Blocks hjelpe deg i gang.