Gutenbergi plokkide aegumine: uuenda ilma sisu purustamata

Kokkuvõte

Gutenbergi ploki uuendamine purustab sageli olemasolevaid postitusi, mis kasutavad vana versiooni. See artikkel näitab, kuidas kasutada deprecated omadust block.json failis, et säilitada tagasiühilduvus. Õpid täpsed sammud praeguse ploki märgendi jäädvustamiseks, ühe või mitme aegunud versiooni määratlemiseks ja atribuutide õigeks kaardistamiseks. Käsitleme nii staatilisi kui ka dünaamilisi plokke koos praktiliste näidetega. Artikkel seab ka kahtluse alla eelduse, et aegumine on alati parim lähenemine, arutledes, millal võiks olla parem teha puhas eraldus. Lõpuks oskad oma plokke enesekindlalt uuendada ilma kasutajate sisu purustamata.

Muutuse stsenaarium

Käivitasite kuus kuud tagasi kohandatud iseloomustusploki. See väljastab lihtsa <div> elemendi koos tsitaadi ja autori nimega. Nüüd soovib teie klient uut kujundust: autor peaks olema tsitaadi kohal, erineva CSS-klassiga. Uuendate ploki save funktsiooni ja render_callback funktsiooni. Testite uut postitust – see näeb suurepärane välja. Seejärel lähete vana postituse juurde, mis kasutab seda plokki. Katastroof: tsitaadi tekst on kadunud, autor on vales kohas ja stiil on paigast ära. Olete just purustanud iga lehe, mis seda plokki kasutab.

See on klassikaline "muutuse" probleem Gutenbergi ploki arenduses. Plokid on sisuliselt andmestruktuurid koos märgendiga. Kui muudate märgendit, ei saa redaktor automaatselt vana sisu uuele struktuurile vastendada. Tulemuseks on kas valideerimisviga (plokk muutub kehtetuks) või – hullem – vaikne korruptsioon, kus plokk renderdub valesti.

Mis on ploki aegumine?

Ploki aegumine on Gutenbergi sisseehitatud mehhanism versioonimuudatuste käsitlemiseks. Määratledes oma ploki block.json failis deprecated massiivi, ütlete redaktorile: "Kui kohtad plokki, mis vastab ühele neist vanematest versioonidest, teisenda see praegusesse versiooni." Iga aegunud kirje määrab eelmised attributes, supports ja save funktsiooni (või render_callback). Kui redaktor laeb vana ploki, käib ta aegunud massiivi läbi järjekorras ja rakendab esimese sobiva teisenduse.

Seda funktsiooni kasutatakse sageli vähe, kuna arendajad eeldavad, et nad ei pea kunagi ploki märgendit muutma. Kuid reaalsetes projektides nõuded arenevad. Kui jätate aegumise vahele, sunnite kasutajaid plokke kustutama ja uuesti lisama (halb kasutajakogemus) või hoiate kahte eraldi plokiversiooni (segadus). Ametlik WordPressi arendaja käsiraamat käsitleb seda Block Editor Handbook lehel, kuid praktilised juhendid puuduvad.

1. samm: jäädvusta praegune olek

Enne muudatuste tegemist salvestage täpne save väljund (või render_callback dünaamiliste plokkide puhul) ja attributes, mida teie plokk praegu kasutab. Mõelge sellest kui hetktõmmise tegemisest. Staatiliste plokkide puhul salvestage JSX, mille save funktsioon tagastab. Dünaamiliste plokkide puhul salvestage PHP märgend, mille render_callback genereerib.

Looge oma pluginasse uus fail nimega deprecated.js (või sarnane) ja salvestage sinna vana save funktsioon. Või hoidke aegunud versioonid otse ploki peamises JavaScript-failis. Oluline on säilitada see kood täpselt nii, nagu see oli ploki esmakordsel kasutuselevõtul.

2. samm: määratle oma aegunud versioonid

Lisage oma block.json faili deprecated massiiv. Iga kirje on objekt, mis võib sisaldada:

• attributes (objekt): eelmised atribuudi definitsioonid.
• supports (objekt): kõik eelmised tugiseaded, mis muutusid.
• save (funktsioon või string): eelmine salvestusfunktsioon. JavaScripti-põhiste plokkide puhul impordite vana funktsiooni. PHP-s renderdatud dünaamiliste plokkide puhul võite kasutada migrate ja render_callback asemel.
• migrate (funktsioon): funktsioon, mis kaardistab vanad atribuudid uutele (valikuline).

Näide:

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

Märkus: save funktsioon block.json failis on tavaliselt määratletud JavaScriptis. Kui kasutate välist skripti, peate selle lisama ja funktsiooni nimele viitama. Või saate funktsiooni stringina sisse kirjutada (kuigi see pole keerukate plokkide puhul soovitatav).

3. samm: kaardista atribuudid

Sageli muudate mitte ainult märgendit, vaid ka atribuudi nimesid või allikaid. Näiteks võite minna üle autori salvestamiselt lihttekstina rikkalikuks tekstiväljaks. Sellistel juhtudel kasutage migrate omadust, et teisendada vanad atribuudid uuteks.

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

Kui te ei anna migrate funktsiooni, edastab redaktor lihtsalt vanad atribuudid otse uude plokki. See võib põhjustada vigu, kui atribuutide nimed on muutunud.

4. samm: testi reaalse sisuga

Pärast aegunud versiooni määratlemist testige põhjalikult. Looge uus postitus, sisestage vana plokk (saate simuleerida, kleepides serialiseeritud ploki koodi olemasolevast postitusest) ja kontrollige, et see teisendub uude versiooni ilma valideerimisvigadeta. Testige ka teisendatud ploki redigeerimist ja salvestamist. Korrake seda mitme aegunud versiooni puhul, kui neid on.

Dünaamiliste plokkide puhul on protsess sarnane, kuid keerdkäiguga: dünaamilise ploki save funktsioon tagastab tavaliselt null (plokk renderdub PHP kaudu). Aegunud kirjes saate kas määrata save väärtuseks eelmise staatilise märgendi, mida kasutati enne dünaamilisele renderdamisele üleminekut, või kasutada PHP-s render_callback funktsiooni, mis käsitleb nii vanu kui uusi atribuudi struktuure. See on keerulisem, kuid teostatav.

Hoiatused ja kompromissid

Aegumine on võimas, kuid sellel on varjuküljed. Iga aegunud versioon lisab teie pluginasse koodi. Aja jooksul võib tekkida kett viie-kuue pärandversiooniga, mida harva kasutatakse, kuid mida tuleb hooldada. WordPressi tuummeeskond soovitab hoida vähemalt kaks versiooni tagasi, kuid kaugemale minnes võiksite kaaluda puhast eraldust, kui mõjutatud postitusi on vähe.

Teine nüanss: aegunud kirjete järjekord on oluline. Redaktor käib massiivi läbi indeksist 0 alates ja kasutab esimest sobivat. Kui kaks aegunud versiooni on sarnased, võidakse rakendada vale. Loetlege alati kõige uuem aegunud versioon esimesena (see, mis vahetult eelneb praegusele versioonile).

Lõpuks ei käsitle aegumine sisu, mida on redigeeritud saidiülese stiilimuutusega (nt theme.json kaudu). Kui teie ploki välimus tugines globaalsetele stiilidele, mis on sellest ajast muutunud, ei kohanda aegumine seda. Võimalik, et peate lisama migratsiooniskripti, mis käivitatakse salvestamisel või plugina uuendamise käivitamisel.

Millal aegumine pole vastus

Enamik õpetusi käsitleb aegumist kohustuslikuna. Tegelikkuses on olukordi, kus puhas eraldus on parem. Kui teie plokk on uus ja seda kasutatakse vaid mõnes postituses, võib nende üksikute juhtumite käsitsi uuendamine olla kiirem kui aegumiskoodi kirjutamine ja testimine. Samuti, kui ploki aluseks olev andmemudel on põhimõtteliselt erinev (nt liidate kaks plokki üheks), ei pruugi aegumine olla piisavalt paindlik. Sellisel juhul kirjutage ühekordne migratsiooniskript, mis käivitub plugina uuendamisel, teisendades vanad plokid uude vormingusse.

Teine vastuoluline punkt: aegumist ei tohiks kasutada hea disaini asendajana. Kui ootate sagedasi muudatusi, kujundage plokk algusest peale versioonihaldusega – nt salvestades version atribuuti ja kasutades tingimuslikku renderdamist. Seda lähenemist, mida käsitletakse artiklis Beyond Basic Blocks, on kergem kui aegumine, kuid see nõuab ettenägelikkust.

Kokkuvõte

Ploki aegumine on oluline tööriist igale tõsisele Gutenbergi arendajale. See võimaldab teil oma plokke arendada ilma kasutajate sisu purustamata. Peamised sammud on: jäädvusta praegune olek, määratle aegunud versioon block.json failis, kaardista atribuudid vajadusel ja testi reaalse sisuga. Kuid pidage meeles, et aegumine toob kaasa hoolduskulusid. Mõnikord on pragmaatilisem teha puhas eraldus või kasutada versioonitud ploki disaini. Kasutage aegumist strateegiliselt, mitte automaatselt, ja teie plokid püsivad tugevatena läbi paljude uuenduste.

Laiema vaatenurga saamiseks hooldatavate pluginate ehitamise kohta vaadake Building Robust WordPress Plugins. Ja kui olete plokiarenduses uus, aitab Beyond Basic Blocks teil alustada.