Gutenberg bloka deprecēšana: Atjaunināt, nesabojājot saturu

Kopsavilkums

Gutenberg bloka atjaunināšana bieži vien sabojā esošās ziņas, kurās izmantota vecā versija. Šis raksts parāda, kā izmantot deprecated rekvizītu block.json, lai saglabātu atpakaļsaderību. Jūs uzzināsit precīzus soļus, kā fiksēt pašreizējo bloka atzīmējumu, definēt vienu vai vairākas novecojušās versijas un pareizi kartēt atribūtus. Mēs apskatīsim gan statiskos, gan dinamiskos blokus ar praktiskiem piemēriem. Raksts arī apšauba pieņēmumu, ka deprecēšana vienmēr ir labākā pieeja, apspriežot, kad tīrs pārtraukums varētu būt labāks. Beigās jūs varēsiet pārliecinoši atjaunināt savus blokus, nesabojājot lietotāju saturu.

Izmaiņu scenārijs

Jūs pirms sešiem mēnešiem palaidāt pielāgotu testimoniju bloku. Tas izvada vienkāršu <div> ar citātu un autora vārdu. Tagad jūsu klients vēlas jaunu dizainu: autoram jāparādās virs citāta ar atšķirīgu CSS klasi. Jūs atjaunināt bloka save funkciju un render_callback. Jūs testējat jaunā ziņā — tas izskatās lieliski. Tad jūs atverat vecu ziņu, kurā izmantots bloks. Katastrofa: citāta teksts ir pazudis, autors ir nepareizā vietā, un stils ir izjaukts. Jūs tikko sabojājāt katru lapu, kurā ir šis bloks.

Tā ir klasiskā "nepārtrauktību izjaucošo izmaiņu" problēma Gutenberg bloku izstrādē. Bloki būtībā ir datu struktūras, kas apvienotas ar atzīmējumu. Kad jūs maināt atzīmējumu, redaktors nevar automātiski kartēt veco saturu uz jauno struktūru. Rezultātā rodas vai nu validācijas kļūda (bloks kļūst nederīgs), vai — vēl ļaunāk — klusa sabojāšana, kad bloks tiek attēlots nepareizi.

Kas ir bloka deprecēšana?

Bloka deprecēšana ir Gutenberg iebūvēts mehānisms versiju izmaiņu apstrādei. Definējot deprecated masīvu sava bloka block.json, jūs sakāt redaktoram: "Ja jūs sastopat bloku, kas atbilst kādai no šīm vecākajām versijām, pārveidojiet to pašreizējā versijā." Katrs deprecēts ieraksts norāda iepriekšējos attributes, supports un save funkciju (vai render_callback). Kad redaktors ielādē vecu bloku, tas iziet cauri deprecēto masīvam secībā un pielieto pirmo atbilstošo pārveidojumu.

Šī iespēja bieži tiek nepietiekami izmantota, jo izstrādātāji pieņem, ka viņiem nekad nebūs jāmaina bloka atzīmējums. Bet reālos projektos prasības mainās. Ja jūs izlaidīsiet deprecēšanu, jūs vai nu piespiedīsiet lietotājus dzēst un ievietot blokus no jauna (slikta pieredze), vai arī uzturēsit divas atsevišķas bloka versijas (nekārtīgi). Oficiālā WordPress izstrādātāja rokasgrāmata par to runā Bloku redaktora rokasgrāmatā, bet praktisku ceļvežu trūkst.

1. solis: Fiksējiet pašreizējo stāvokli

Pirms veicat izmaiņas, ierakstiet precīzu save izvadi (vai render_callback dinamiskajiem blokiem) un attributes, ko jūsu bloks pašlaik izmanto. Domājiet par to kā par momentuzņēmumu. Statiskajiem blokiem saglabājiet JSX, ko atgriež save funkcija. Dinamiskajiem blokiem saglabājiet PHP atzīmējumu, ko ģenerē render_callback.

Izveidojiet jaunu failu savā spraudnī ar nosaukumu deprecated.js (vai līdzīgu) un glabājiet tajā veco save funkciju. Vai arī glabājiet deprecētās versijas tieši bloka galvenajā JavaScript failā. Galvenais ir saglabāt šo kodu tieši tā, kā tas bija, kad bloks pirmo reizi tika izplatīts.

2. solis: Definējiet deprecētās versijas

Savā block.json pievienojiet deprecated masīvu. Katrs ieraksts ir objekts, kas var ietvert:

• attributes (objekts): Iepriekšējās atribūtu definīcijas.
• supports (objekts): Visi iepriekšējie atbalsta iestatījumi, kas mainījās.
• save (funkcija vai virkne): Iepriekšējā save funkcija. JavaScript tikai blokiem jūs importēsit veco funkciju. PHP renderētiem dinamiskajiem blokiem varat izmantot migrate un render_callback.
• migrate (funkcija): Funkcija, kas kartē vecos atribūtus uz jauniem (pēc izvēles).

Piemērs:

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

Piezīme: save funkcija block.json parasti tiek definēta JavaScript. Ja izmantojat ārēju skriptu, jums tas būs jāpievieno un jāatsaucas uz funkcijas nosaukumu. Vai arī varat iekļaut funkciju kā virkni (lai gan tas nav ieteicams sarežģītiem blokiem).

3. solis: Kartējiet atribūtus

Bieži vien jūs maināt ne tikai atzīmējumu, bet arī atribūtu nosaukumus vai avotus. Piemēram, jūs varat pāriet no autora glabāšanas kā vienkāršas virknes uz bagātināta teksta lauku. Šādos gadījumos izmantojiet migrate rekvizītu, lai pārveidotu vecos atribūtus jaunajos.

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

Ja nenorādāt migrate funkciju, redaktors vienkārši nodos vecos atribūtus tieši jaunajam blokam. Tas var izraisīt kļūdas, ja atribūtu nosaukumi ir mainījušies.

4. solis: Testējiet ar reālu saturu

Pēc deprecētās versijas definēšanas testējiet rūpīgi. Izveidojiet jaunu ziņu, ievietojiet veco bloku (varat simulēt, ielīmējot sērijveidotu bloka kodu no esošas ziņas) un pārbaudiet, vai tas pārveidojas par jauno versiju bez validācijas kļūdām. Testējiet arī pārveidotā bloka rediģēšanu un saglabāšanu. Atkārtojiet vairākām deprecētām versijām, ja tādas ir.

Dinamiskajiem blokiem process ir līdzīgs, bet ar niansi: save funkcija dinamiskajam blokam parasti atgriež null (bloks tiek renderēts ar PHP). Deprecētajā ierakstā varat iestatīt save uz iepriekšējo statisko atzīmējumu, kas tika izmantots pirms pārejas uz dinamisku renderēšanu, vai arī izmantot render_callback PHP, kas apstrādā gan vecās, gan jaunās atribūtu struktūras. Tas ir sarežģītāk, bet izpildāms.

Ierobežojumi un kompromisi

Deprecēšana ir jaudīga, bet tai ir trūkumi. Katra deprecēta versija pievieno kodu jūsu spraudnim. Laika gaitā jūs varat iegūt ķēdi no piecām vai sešām mantotām versijām, kuras tiek reti izmantotas, bet jāuztur. WordPress kodola komanda iesaka saglabāt vismaz divas versijas atpakaļ, bet pēc tam jūs varat apsvērt tīru pārtraukumu, ja skarto ziņu skaits ir neliels.

Vēl viena nianse: deprecēto ierakstu secībai ir nozīme. Redaktors iet cauri masīvam no indeksa 0 uz augšu un izmanto pirmo atbilstību. Ja divas deprecētas versijas ir līdzīgas, var tikt piemērota nepareizā. Vienmēr vispirms iekļaujiet jaunāko deprecēto versiju (to, kas tieši ir pirms pašreizējās versijas).

Visbeidzot, deprecēšana neapstrādā saturu, kas tika rediģēts, izmantojot vietas mēroga stila izmaiņas (piem., caur theme.json). Ja jūsu bloka izskats bija atkarīgs no globāliem stiliem, kas kopš tā laika ir mainījušies, deprecēšana to nekompensēs. Jums var būt nepieciešams pievienot migrācijas skriptu, kas darbojas saglabāšanas laikā vai izmantojot spraudņa atjaunināšanas āķi.

Kad deprecēšana nav atbilde

Lielākā daļa pamācību deprecēšanu pasniedz kā obligātu. Patiesībā ir situācijas, kad tīrs pārtraukums ir labāks. Ja jūsu bloks ir jauns un tiek izmantots tikai dažās ziņās, manuāla šo dažu gadījumu atjaunināšana var būt ātrāka nekā deprecēšanas koda rakstīšana un testēšana. Tāpat, ja bloka pamatā esošais datu modelis ir būtiski atšķirīgs (piem., jūs apvienojat divus blokus vienā), deprecēšana var nebūt pietiekami elastīga. Šajā gadījumā uzrakstiet vienreizēju migrācijas skriptu, kas darbojas, kad spraudnis tiek atjaunināts, pārveidojot vecos blokus jaunajā formātā.

Vēl viens pretējs viedoklis: deprecēšana nav jāizmanto kā aizstājējs labam dizainam. Ja jūs paredzat biežas izmaiņas, no sākuma veidojiet savu bloku, ņemot vērā versiju pārvaldību — piem., glabājot version atribūtu un izmantojot nosacītu renderēšanu. Šī pieeja, kas apskatīta Ārpus pamata blokiem, ir vieglāka nekā deprecēšana, bet prasa tālredzību.

Secinājums

Bloka deprecēšana ir būtisks rīks jebkuram nopietnam Gutenberg izstrādātājam. Tas ļauj jums attīstīt savus blokus, nesabojājot lietotāju saturu. Galvenie soļi ir: fiksēt pašreizējo stāvokli, definēt deprecēto versiju block.json, kartēt atribūtus, ja nepieciešams, un testēt ar reālu saturu. Bet atcerieties, ka deprecēšana ir saistīta ar uzturēšanas izmaksām. Dažreiz tīrs pārtraukums vai versiju bloka dizains ir praktiskāks. Izmantojiet deprecēšanu stratēģiski, nevis automātiski, un jūsu bloki paliks stabili daudzu atjauninājumu laikā.

Lai iegūtu plašāku skatījumu par uzturējamu spraudņu veidošanu, skatiet Stabilu WordPress spraudņu veidošana. Un, ja esat iesācējs bloku izstrādē, Ārpus pamata blokiem palīdzēs jums sākt.