Skapa anpassat Gutenberg-block – Del 3: Rekvisita och WordPress-komponenter

Det föregående steget i denna handledningsserie gick igenom hur man registrerar ett anpassat block, både i Javascript och i PHP. I det här steget kommer vi att lära oss hur man använder WordPress komponenter för att lägga till olika typer av fält och inställningar.

För att kunna använda WordPress komponenter i vårt block behöver vi först veta om rekvisita.

Rekvisita

Props är en viktig funktion i React och är i grunden ett sätt att överföra variabler eller funktioner till andra komponenter. Om du inte är bekant med React-rekvisita kan du läsa Reacts officiella handledning om detta.

WordPress tillhandahåller några rekvisita för editoch savefunktioner i registerBlockType(). Inuti dessa rekvisita får vi tillgång till kritiska saker, såsom attribut och en metod för att uppdatera våra attribut. Vi kommer att gå igenom attribut i detalj i nästa steg!

Hittills i vårt block har vi skrivit funktionen för editoch saveså här:

Du bör vänja dig vid att lägga till parametern propstill både editoch save, som så:

Nu har du full tillgång till variabeln propsoch allt den innehåller inifrån editoch save. Om du är nyfiken kan du lägga till ett console.log(props);i editfunktionen före returnpåståendet. Du bör se vilka rekvisita som finns tillgängliga i konsolfelsökaren.

Använder WordPress-komponenter

Som tidigare nämnts har vi tillgång till ett enormt bibliotek av komponenter och användbara funktioner i det globala paketet wp. Du hittar färdiga komponenter för alla typer av ingångsrelaterade komponenter du kan tänka dig. Exempel inkluderar textinmatning, rik textinmatning, rullgardinsmenyer, växlar, kryssrutor, knappar i olika stilar, mediauppladdningsverktyg och färgväljare. Det finns även funktioner och komponenter för mer avancerad funktionalitet. Som att fråga WordPress efter innehåll (inlägg, kategorier, etc) med antingen inbyggda funktioner eller hämtning med REST API.

Det är både enklare och rekommenderat att använda WordPress UI-komponenter. Detta för att se till att designen och funktionaliteten är så strömlinjeformad som möjligt för att inte förvirra eller irritera användarna.

Men i skrivande stund är dokumentationen för Gutenberg tyvärr väldigt knapp. Jag har hittat det bästa sättet att lära mig om vad som finns i wppaketet och hur komponenterna faktiskt fungerar genom att titta i deras officiella Gutenberg Github-repo. Vissa av paketen (mapparna) har en readme-text som erbjuder lite dokumentation. Ta en titt på readme för en knapp eller växeln till exempel.

Github-repo ska motsvara vad som finns inuti wppaketet (beroende på vilken version du har och vilken gren du tittar på i Github). Detta innebär att varje mapp du ser i rotkatalogen packagesi Github finns i det globala wppaketet. Som ett exempel kom ihåg att funktionen vi använde i föregående steg, registerBlockType(), var inuti wp.blocks, vilket betyder att du hittar källkoden för denna funktion exporterad inom packages/blocks/.

Eftersom jag har utvecklat ett antal anpassade Gutenberg-block och grävt en hel del i Github-repo, har jag upptäckt att det finns några paket som innehåller den vanligaste funktionaliteten som används för att skapa anpassade block. Jag tar med dem nedan.

För en mer komplett översikt över tillgängliga komponenter rekommenderar jag att du laddar ner min gratis e-bok som täcker tillgängliga komponenter i Gutenberg! Den innehåller de vanligaste och mest användbara komponenterna med dokumentation om rekvisita och kodexempel:

En snabb översikt över de vanligaste paketen du kommer att använda för block

Uppenbarligen finns det mycket mer tillgängligt, men nedan är det som är vanligast för blockutveckling. Vi kommer att använda de flesta om inte alla av dessa i denna handledningsserie. När du vill använda en komponent måste du veta i vilket paket den finns.

wp.components

Du hittar de flesta UI-ingångskomponenter inuti wp.components. Exempel är olika textinmatning, markering, kryssrutor, radioknappar, dragbara komponenter, knappar, färgväljare, datumväljare och så vidare. Du hittar också UI-komponenter som du kan använda för blockverktygsfältet och innehållet i sidofältet för inställningar (kallas InspectorControls) i editorn.

Kolla in mapparna i Github-repo.

wp.blockEditor och wp.editor

I dessa två paket hittar du användbara komponenter för rik text, hantering av bilder/mediauppladdning och komponenter för att faktiskt lägga till verktygsfält eller anpassade Inspector-paneler (sidofält).

I slutet av den här serien kommer vi att titta på att bygga dynamiska block där vi kommer att använda PHP för att rendera blockutdata, och för det kommer vi att använda en komponent från wp.editor.

Som jag förstår det började de flesta komponenter i wp.editortidiga Gutenberg-dagar, men särskilt efter WordPress 5.3 flyttades många av dem till wp.blockEditor. Om du använder en komponent wp.editorsom WordPress planerar att flytta in i wp.blockEditorkommer den inte att misslyckas från och med nu, men i konsolfelsökning kommer du att få varningar om att den har blivit utfasad och att du bör byta till wp.blockEditornär du kan. Och reversibelt om du följer den här serien med en äldre WordPress-version av någon anledning kan du stöta på fel när du anropar komponenter som inte har flyttats till wp.blockEditorännu.

wp.element

Inuti wp.elementhittar du komponenter som motsvarar React-komponenter. Till exempel Component(som motsvarar React.Component) och Fragment( React.Fragment). Vi kommer att använda dessa när vi börjar dela upp vår kod i separata komponenter.

wp.i18n

Som namnet anger wp.i18ninnehåller paketet funktioner för hantering av översättning. Den innehåller samma översättningsfunktioner som vi känner till dem i PHP; till exempel __()och _e(). Vi kommer att titta på detta i detalj i <<<>>>> när vi lär oss hur man översätter vårt block.

wp.data

Paketet wp.dataär till för att fråga WordPress efter data utanför editorn. Det finns komponenter för att skicka meddelanden, withSelectoch selectsom vi kommer att använda senare i den här serien för att söka efter inlägg i vårt block.

wp.compose

Det tidigare paketet och wp.composeär för mer avancerad blockbyggnad. Inuti detta paket hittar vi komponenter och funktioner för att skapa så kallade komponenter av högre ordning. Komponenter av högre ordning är en mönsterteknik i React för att återanvända komponenter och logik, och vi kommer att använda detta i kombination med wp.dataför att fråga inlägg.

Nog prat – hur använder du några av dessa komponenter i praktiken?

Som nämnts tidigare; för att kunna använda WordPress komponenter måste du veta var de finns. Förhoppningsvis kommer min översikt ovan i kombination med Github-repo att ge dig en uppfattning om var du kan få tag i dem.

Glöm inte att du alltid kan lägga till alla vanliga HTML-taggar, som div, span, rubriker och så vidare. Kom bara ihåg att följa Reacts riktlinjer i attribut. Till exempel classär ett reserverat nyckelord i React (för att skapa klassbaserade komponenter), så om du vill lägga till en klass till ett HTML-element måste du använda className.

Obs: Glöm inte npm run startatt kompilera din kod under utvecklingen.

Som ett enkelt exempel, låt oss prova några komponenter för att se hur de ser ut. Vi destrukturerar dem från deras motsvarande paket och använder dem i vår editfunktion.

Detta kommer till exempel att resultera i att vårt block ser ut så här i editorn.

Du kommer att märka att du kommer att få felmeddelanden i konsolen när du skriver i dem, och att det inte kommer att spara det du skriver in när du uppdaterar inlägget (och uppdaterar). Detta beror på att vi saknar rekvisita på komponenterna som är kopplingen till attribut, där all vår blockdata lagras. Rekvisitan ansvarar för att skicka de sparade värdena och funktioner som ansvarar för att uppdatera våra attribut när något ändras i våra ingångar. Detta är vad vi kommer att göra i nästa steg, där vi äntligen ska börja skriva lite kod på riktigt.