Gutenberg bloko nusidėvėjimas: atnaujinkite nepažeisdami turinio

Santrauka\n\nAtnaujinant Gutenberg bloką dažnai sugadinami esami įrašai, kuriuose naudojama sena versija. Šis straipsnis parodo, kaip naudoti deprecated savybę block.json išlaikant atgalinį suderinamumą. Sužinosite tikslius žingsnius, kaip užfiksuoti dabartinę bloko struktūrą, apibrėžti vieną ar daugiau nusidėvėjusių versijų ir teisingai priskirti atributus. Apžvelgsime tiek statinius, tiek dinaminius blokus su praktiniais pavyzdžiais. Straipsnis taip pat kritiškai vertina prielaidą, kad nusidėvėjimas visada yra geriausias sprendimas, aptariant, kada gali būti geriau atlikti švarų lūžį. Galiausiai galėsite atnaujinti savo blokus drąsiai nesugadindami vartotojų turinio.\n\n## Lūžio scenarijus\n\nPrieš šešis mėnesius paleidote pritaikytą rekomendacijos bloką. Jis išveda paprastą <div> su citata ir autoriaus vardu. Dabar jūsų klientas nori naujo dizaino: autorius turi būti virš citatos, su kita CSS klase. Atnaujinate bloko save funkciją ir render_callback. Išbandote naujame įraše – atrodo puikiai. Tada pereinate prie seno įrašo, kuriame naudojamas blokas. Katastrofa: citatos tekstas dingęs, autorius netinkamoje vietoje, o stilius sugadintas. Ką tik sugadinote kiekvieną puslapį, kuriame naudojamas blokas.\n\nTai yra klasikinė "lūžio pokyčio" problema kuriant Gutenberg blokus. Blokai iš esmės yra duomenų struktūros, sujungtos su žymėjimu. Kai pakeičiate žymėjimą, redaktorius negali automatiškai susieti seno turinio su nauja struktūra. Rezultatas yra arba patvirtinimo klaida (blokas tampa negaliojančiu), arba – dar blogiau – tylus sugadinimas, kai blokas atvaizduojamas neteisingai.\n\n## Kas yra bloko nusidėvėjimas?\n\nBloko nusidėvėjimas yra įmontuotas Gutenberg mechanizmas, skirtas tvarkyti versijų pakeitimus. Apibrėždami deprecated masyvą savo bloko block.json, pasakote redaktoriui: "Jei susidursite su bloku, atitinkančiu vieną iš šių senesnių versijų, paverskite jį į dabartinę versiją." Kiekvienas nusidėvėjęs įrašas nurodo ankstesnius attributes, supports ir save funkciją (arba render_callback). Kai redaktorius įkelia seną bloką, jis pereina per nusidėvėjusių masyvą eilės tvarka ir pritaiko pirmą atitinkantį transformavimą.\n\nŠi funkcija dažnai nepakankamai naudojama, nes kūrėjai mano, kad jiems niekada nereikės keisti bloko žymėjimo. Tačiau realiuose projektuose reikalavimai keičiasi. Jei praleisite nusidėvėjimą, arba priversite naudotojus ištrinti ir iš naujo įterpti blokus (prasta patirtis), arba palaikysite dvi atskiras bloko versijas (netvarkinga). Oficialiame WordPress kūrėjo žinyne tai aprašyta Blokų redaktoriaus žinyne, tačiau trūksta praktinių pavyzdžių.\n\n## 1 žingsnis: Užfiksuokite dabartinę būseną\n\nPrieš atlikdami bet kokius pakeitimus, užrašykite tikslią save išvestį (arba render_callback dinaminiams blokams) ir attributes, kuriuos jūsų blokas šiuo metu naudoja. Įsivaizduokite tai kaip momentinį vaizdą. Statiškiems blokams išsaugokite JSX, kurį grąžina save funkcija. Dinaminiams blokams išsaugokite PHP žymėjimą, sugeneruotą render_callback.\n\nSukurkite naują failą savo papildinyje pavadinimu deprecated.js (ar panašiai) ir ten saugokite seną save funkciją. Arba laikykite nusidėvėjusias versijas tiesiogiai pagrindiniame bloko JavaScript faile. Svarbiausia išsaugoti šį kodą tiksliai tokį, koks jis buvo, kai blokas pirmą kartą buvo pristatytas.\n\n## 2 žingsnis: Apibrėžkite nusidėvėjusias versijas\n\nSavo block.json pridėkite deprecated masyvą. Kiekvienas įrašas yra objektas, kuris gali apimti:\n\n- attributes (objektas): Ankstesni atributų apibrėžimai.\n- supports (objektas): Bet kokie ankstesni palaikymo nustatymai, kurie pasikeitė.\n- save (funkcija arba eilutė): Ankstesnė saugojimo funkcija. Tik JavaScript blokams importuosite seną funkciją. PHP atvaizduojamiems dinaminiams blokams galite naudoti migrate ir render_callback.\n- migrate (funkcija): Funkcija, kuri susieja senus atributus su naujais (neprivaloma).\n\nPavyzdys:\n\njson\n\"deprecated\": [\n {\n \"attributes\": {\n \"quote\": { \"type\": \"string\", \"source\": \"html\", \"selector\": \".quote\" },\n \"author\": { \"type\": \"string\", \"source\": \"html\", \"selector\": \".author\" }\n },\n \"supports\": {},\n \"save\": \"() => <div className=\\\"testimonial-legacy\\\"><p className=\\\"quote\\\">{attributes.quote}</p><p className=\\\"author\\\">{attributes.author}</p></div>\"\n }\n]\n\n\nPastaba: save funkcija block.json paprastai apibrėžiama JavaScript. Jei naudojate išorinį scenarijų, turėsite jį įtraukti ir nurodyti funkcijos pavadinimą. Arba galite funkciją įterpti kaip eilutę (nors tai nerekomenduojama sudėtingiems blokams).\n\n## 3 žingsnis: Atributų susiejimas\n\nDažnai keičiate ne tik žymėjimą, bet ir atributų pavadinimus ar šaltinius. Pavyzdžiui, galite pereiti nuo autoriaus saugojimo kaip paprastos teksto eilutės prie turtingo teksto lauko. Tokiais atvejais naudokite migrate savybę, kad paverstumėte senus atributus į naujus.\n\njavascript\nmigrate: (attributes) => {\n return {\n quote: attributes.quote,\n author: { content: attributes.author, level: 2 }\n };\n}\n\n\nJei nepateiksite migrate funkcijos, redaktorius tiesiog perduos senus atributus naujam blokui. Tai gali sukelti klaidų, jei atributų pavadinimai pasikeitė.\n\n## 4 žingsnis: Išbandykite su tikru turiniu\n\nApibrėžę nusidėvėjusią versiją, atlikite kruopščius bandymus. Sukurkite naują įrašą, įterpkite seną bloką (galite imituoti įklijuodami serializuotą bloko kodą iš esamo įrašo) ir patikrinkite, ar jis konvertuojamas į naują versiją be patvirtinimo klaidų. Taip pat išbandykite konvertuoto bloko redagavimą ir išsaugojimą. Pakartokite su keliomis nusidėvėjusiomis versijomis, jei jų turite.\n\nKalbant dinaminiams blokams, procesas yra panašus, bet su vingiu: dinaminio bloko save funkcija paprastai grąžina null (blokas atvaizduojamas per PHP). Nusidėvėjusiame įraše galite nustatyti save į ankstesnį statinį žymėjimą, kuris buvo naudojamas prieš pereinant prie dinaminio atvaizdavimo, arba naudoti render_callback PHP, kuris tvarko tiek senas, tiek naujas atributų struktūras. Tai sudėtingiau, bet įmanoma.\n\n## Įspėjimai ir kompromisai\n\nNusidėvėjimas yra galingas, tačiau turi trūkumų. Kiekviena nusidėvėjusi versija prideda kodo jūsų papildinyje. Laikui bėgant galite turėti penkių ar šešių paveldėtų versijų grandinę, kurios retai naudojamos, tačiau turi būti palaikomos. WordPress pagrindinė komanda rekomenduoja išlaikyti bent dvi versijas atgal, tačiau viršijus tai galite apsvarstyti švarų lūžį, jei paveiktų įrašų skaičius yra mažas.\n\nKitas niuansas: nusidėvėjusių įrašų eiliškumas yra svarbus. Redaktorius pereina per masyvą nuo 0 indekso aukštyn ir naudoja pirmą atitikmenį. Jei dvi nusidėvėjusios versijos yra panašios, gali būti pritaikyta neteisinga. Visada pirmiausiai išvardykite naujausią nusidėvėjusią versiją (tą, kuri tiesiogiai prieš dabartinę versiją).\n\nGaliausiai, nusidėvėjimas netvarko turinio, kuris buvo redaguotas naudojant viso tinklo stiliaus pakeitimą (pvz., per theme.json). Jei jūsų bloko išvaizda priklausė nuo pasaulinių stilių, kurie nuo to laiko pasikeitė, nusidėvėjimas to nepriderins. Gali tekti pridėti migracijos scenarijų, kuris vykdomas išsaugojimo metu arba per papildinio naujinimo kablį.\n\n## Kai nusidėvėjimas nėra atsakymas\n\nDauguma pamokų nusidėvėjimą pateikia kaip privalomą. Iš tiesų yra situacijų, kai švarus lūžis yra geresnis. Jei jūsų blokas yra naujas ir naudojamas tik keliuose įrašuose, rankinis tų kelių atvejų atnaujinimas gali būti greitesnis nei nusidėvėjimo kodo rašymas ir testavimas. Panašiai, jei bloko pagrindinis duomenų modelis iš esmės skiriasi (pvz., sujungiate du blokus į vieną), nusidėvėjimas gali būti nepakankamai lankstus. Tokiu atveju parašykite vienkartinį migracijos scenarijų, kuris vykdomas atnaujinus papildinį, konvertuodamas senus blokus į naują formatą.\n\nKitas prieštaringas punktas: nusidėvėjimas neturėtų būti naudojamas kaip gero dizaino pakaitalas. Jei numatote dažnus pakeitimus, kurkite bloką turėdami omenyje versijavimą nuo pradžių – pvz., saugodami version atributą ir naudodami sąlyginį atvaizdavimą. Šis metodas, aptartas Už pagrindinių blokų ribų, yra lengvesnis už nusidėvėjimą, tačiau reikalauja įžvalgos.\n\n## Išvada\n\nBloko nusidėvėjimas yra esminis įrankis kiekvienam rimtam Gutenberg kūrėjui. Tai leidžia jums tobulinti savo blokus nesugadinant vartotojų turinio. Pagrindiniai žingsniai yra: užfiksuokite dabartinę būseną, apibrėžkite nusidėvėjusią versiją block.json, susiekite atributus, jei reikia, ir išbandykite su tikru turiniu. Tačiau atminkite, kad nusidėvėjimas susijęs su priežiūros išlaidomis. Kartais švarus lūžis arba versijuotas bloko dizainas yra pragmatiškesni. Naudokite nusidėvėjimą strategiškai, ne automatiškai, ir jūsų blokai išliks tvirti per daugelį atnaujinimų.\n\nNorėdami gauti platesnę perspektyvą, kaip kurti lengvai prižiūrimus papildinius, žiūrėkite Tvirtų WordPress papildinių kūrimas. Ir jei esate naujokas blokų kūrime, Už pagrindinių blokų ribų padės jums pradėti.