Hur man lägger till färginställningar i ditt anpassade Gutenberg-block
Det här inlägget kommer att gå in på djupet i hur du lägger till färginställningar i ditt anpassade WordPress Gutenberg-block. Vi kommer att lära oss hur man lägger till samma färginställningskomponent, som har att välja mellan palettfärger och anpassade färger, som många av WordPresss standardblock använder.
Det här är vad vi kommer att lägga till i vårt anpassade block:
Genom att använda Gutenbergs komponenter kan vi mycket enkelt implementera denna palett/färgsektion till vårt eget anpassade block. Du kan definiera färginställningarna för att påverka vilken färg du vill; bakgrund, textfärg, kantfärg eller vad som helst. Du kan också lägga till så många färginställningar du vill inuti den här panelen.
Innan vi dyker in i koden finns det några saker du måste vara medveten om. Hoppa inte vidare till koden eftersom nästa avsnitt kommer att förklara mycket varför koden behöver göra det som det gör.
Vad du behöver veta först
Komponenterna för att implementera palett/färginställningar är PanelColorSettings
och withColors
från wp.blockEditor
paketet. Komponenten withColors
är en så kallad högre ordningskomponent och behöver implementeras lite annorlunda än att bara mata ut en normal komponent. Jag ska gå in på lite mer i detalj senare. Men först måste vi vara medvetna om grunderna i hur Gutenberg hanterar blockfärginställningar.
Hur Gutenberg-block hanterar färginställningar
Det finns vissa regler för hur Gutenberg hanterar färginställningar i block. Om du någonsin har formaterat ett Gutenberg-stödt tema innan är du förmodligen redan bekant med dessa regler. Vi går snabbt igenom dem ändå eftersom vi måste hantera detta i vår blockkod.
- När en palettfärg väljs kommer nodblockelementet att få en klass av ett visst mönster. Klassen börjar med ”
has-
", och sedan kommer palettens snigel efter. Slutet beror på vilket element färgen ska påverka. För textfärg slutar den med "-color
". För bakgrundsfärg slutar den med "-background-color
". Som ett exempel, ett block med en palettfärg "röd" vald som bakgrundsfärg kommer att få klassen "has-red-background-color
". - När en anpassad färg väljs (från färgväljaren), kommer nodblockelementet att få inline-stil med hex-koden. Till exempel kommer en anpassad färg #DD0000 vald för bakgrundsfärg att få attributet "
style="background-color: #DD0000;
".
När vi implementerar färginställningar för vårt block måste vi implementera rätt klass och inline-stil. Vi kommer att göra det i slutet av denna handledning.
Hur man arbetar medwithColors
Som nämnts tidigare withColors
är en högre ordningskomponent. Vad det i princip betyder att det är en komponent som tar en komponent och returnerar en ny komponent. I den returnerade komponenten får vi användbara rekvisita från den högre ordningens komponenten. För att uttrycka det enkelt kommer vi att använda withColors
för att returnera vår egen komponent för vårt anpassade block. Vår blockkomponent får nödvändig rekvisita för att arbeta med färger från withColors
.
Komponenten withColors
hanterar tillstånd och mycket funktionalitet för att arbeta med färger. Och vi får mycket automatisering i den här processen. Detta är väldigt praktiskt för att ta reda på om den valda färgen är en palettfärg (vi måste lägga till en klass) eller en anpassad färg (vi måste lägga till inline-stil). withColors
förenkla mycket av processen att lagra den valda färgen, vad den än är, i vårt blocks attribut. På tal om attribut..
Attribut ochwithColors
Uppenbarligen behöver ditt block attribut för att lagra den valda färgen. För att dra nytta av withColors automatisering för att lagra rätt färg måste du faktiskt definiera två attribut för varje färginställning. En för att lagra palettfärgens slug, och en annan för att lagra hex-koden. Det finns dock vissa regler.
Säg att du vill lägga till en färginställning för blockets textfärg – så du bestämmer dig för att definiera ett attribut med passande namn " textColor
". Du måste sedan definiera ett annat attribut i mönstret " customYourOriginalAttribute
". I det här exemplet måste det andra attributet heta " customTextColor
". Tänk på camelCase (stora bokstäver) här. Att följa det här mönstret withColors
kommer automatiskt:
- Om en palettfärg har valts kommer attributet "
textColor
" att innehålla palettens slug. - Om en anpassad färg har valts kommer "
customTextColor
" att fyllas i med hex-koden.
Dessa två fungerar tillsammans. Om en anpassad färg väljs textColor
blir det automatiskt undefined
och vice versa.
Och till sist, en sista sak att komma ihåg: du behöver inte använda setAttributes()
för att uppdatera dina färgattribut! De medföljande rekvisitana från withColors
inkluderar en funktion som automatiskt uppdaterar dina attribut åt dig. Allt du behöver göra är att skicka denna funktion till onChange
händelsen till PanelColorSettings
komponenten, så kommer dina attribut att uppdateras automatiskt.
Ok, det är dags att se allt detta i praktiken!
Implementera färginställningar i ett anpassat block
Till att börja med har jag ett ganska värdelöst anpassat block som inte gör något annat än att visa en hårdkodad text. Detta gör det bara enkelt att skilja ut vad vi behöver koda för att lägga till färginställningar. Jag har en handledningsserie om hur du skapar dina egna anpassade block om du är intresserad av att lära dig mer.
Obs: Jag skriver all kod i ES6/ESNext. Detta inkluderar pilfunktioner som kräver särskild omsorg i din Babel/webpack-konfiguration. Om du får fel på en del av koden nedan, följ min guide i hur du ställer in Webpack och Babel för ES6/ESNext eller justerar koden så att den inte använder "experimentella syntaxer".
Det här är mitt grundläggande anpassade block innan jag gör något med färginställningar:
Det är ganska grundläggande. Observera att edit
funktionen helt enkelt hänvisar till en separat komponent BlockWithColorSettings
, istället för att skriva den inline. Detta gör det lättare att implementera withColors
senare.
Okej, dags att implementera färginställningar i vårt block! Som ett exempel vill jag ställa in textfärg.
Lägga till attribut
Som nämnts tidigare måste vi definiera två attribut för varje färginställning. Och vi måste vara extra försiktiga i deras namngivning. Jag vill lägga till ett textfärgattribut, så jag döper attributet textColor
. Vilket betyder att jag också kommer att lägga till ett attribut customTextColor
. Båda ska vara av typen string.
Våra attribut är redo för lagring av blockets textfärginställning. Nu är det dags att implementera withColors
och PanelColorSettings
.
GenomförandewithColors
Som nämnts tidigare withColors
är en högre ordningskomponent som borde ta en komponent för att returnera. Vi vill uppenbarligen att den ska returnera vår redigeringskomponent, BlockWithColorSettings
. Men som parameter withColors
tillhandahåller vi ett objekt.
I objektet som skickas till withColors
måste vi berätta withColors
vilket attribut vi vill använda för att lagra färgen och vilken typ av element det kommer att färga (i vårt fall textfärg, vilket betyder CSS-regeln "färg"). Att informera om CSS-regeln säkerställer att klassnamnen som returneras är korrekta. Eftersom detta är textfärg vill vi ha klassnamn som "har-färg".
Först lite destrukturering på toppen. withColors
finns i wp.blockEditor
paketet.
const { withColors } = wp.blockEditor;
Vi ändrar edit
funktionen till:
Med den här koden kommer vår komponent BlockWithColorSettings
att få ytterligare rekvisita:
props.textColor
: Är ett objekt som består av all information om den valda färgen. Om en palettfärg valdes kommer den att lagra egenskaper för hex-kod, palettsnigel, klassnamn och mer. Om en anpassad färg har valts kommer objektet att innehålla hex-koden. Hexkoden finns alltid i egenskapencolor
. Och klassnamnet (endast om en palettfärg har valts) kommer att ställas in i egenskapenclass
.props.setTextColor
: En funktion som uppdaterar våra attribut åt oss. Vi tillhandahåller detta för färginställningarnasonChange
händelse som vi kommer att se senare. Funktionen kommer att uppdatera bådetextColor
ochcustomTextColor
attribut. Eftersom vi följde namnreglerna kommer det att uppdateras automatisktcustomTextColor
även om vi aldrig angav detta attributnamn.
Observera att "set"-funktionen som tillhandahålls som prop kommer att följa regeln: " setYourAttributeName
". Eftersom vi tillhandahållit textColor
, heter funktionen setTextColor
. Om vi istället döpte vårt attribut awesomeColor
och angav detta i withColors
objektet, skulle set-funktionen få namnet setAwesomeColor()
.
GenomförandePanelColorSettings
Nästa steg är att implementera själva inspektörsektionen. För att göra detta lägger vi till PanelColorSettings
inuti en InspectorControls
komponent. Eftersom React kräver att allt ska vara inuti en rotnod använder vi också Fragment
(från wp.elements
) för att linda in allt.
Först lite destrukturering överst i filen:
const { Fragment } = wp.element;
const { InspectorControls, PanelColorSettings, withColors } = wp.blockEditor;
Och vi uppdaterar vår BlockWithColorSettings
komponent till något sånt här:
Som du kan se i rad #2
destrukturerar vi rekvisita som vi fått från withColors
, textColor
och setTextColor
. Tänk på att det props.textColor
är objektet som tas emot från withColors
och props.attributes.textColor
är attributet. Vi behöver dock inte hänvisa till attributet.
Som rekvisita till komponenten PanelColorSettings
kan vi tillhandahålla en titel för avsnittet (titel i den hopfällbara rutan i Inspector). Det viktiga här är rekvisitan colorSettings
där vi behöver tillhandahålla en mängd färginställningsobjekt. För varje färginställning (vi har för närvarande bara en) måste vi tillhandahålla några egenskaper. Egenskapen value
förväntar sig den för närvarande valda hex-koden (även om en palettfärg har valts). Detta tillhandahålls för oss i textColor
rekvisitan, inne i fastigheten color
. För onChange
fastigheten tillhandahåller vi helt enkelt "set"-funktionen som tillhandahålls av withColors
, setTextColor
. Och slutligen bör vi ge ett label
så att användaren vet vilket element denna färg kommer att påverka. Det kommer att visas precis ovanför området för att välja en färg.
Så här ser vår komponent ut i Gutenberg-redigeraren just nu:
Det håller nu på att uppdatera våra attribut när vi väljer färger. Du kan se att den kommer ihåg ditt färgval när du sparar inlägget.
Dock händer ingenting visuellt när du byter färg. Färgvalet lagras i attributen, men ingen färgändring sker i editorn och inte heller vid förhandsgranskning av inlägget. Detta beror på att vi behöver lägga till kod för blockets klasser och stilar. Vi måste göra detta för både edit
funktion (som är för redaktören) och save
funktion (frontend). Det är nästa steg.
Hantera klass och inline-stilar iedit
Vi behöver bygga blockets nodklass och stilattribut enligt den valda färginställningen. Som tur withColors
är får vi lite automatisering i detta. Kom ihåg att det props.textColor
är ett objekt som innehåller all information vi behöver, inklusive klassnamnet.
Vi skulle kunna göra något så här:
På line #20
tillämpar vi den kritiska klassen och inline-stilen på rotnoden i vårt block. Innan dess bygger vi attributet class och inline style genom att kontrollera props.textColor
objektet.
Efter denna ändring bör ditt anpassade block nu vara fullt fungerande i editorn. När du byter färg kommer blocket att ändra textfärgen. Grymt bra! Det sista steget är att göra detta för save
funktionen också, så att vi får dessa klasser och stilar i frontend också.
Hantera klass och inline-stilar isave
Konceptet med att bygga klass- och inline-stilar och tillämpa dem på rotnoden är samma i save
som i edit
. Men det finns en avgörande skillnad. Vi save
har inte rekvisita som tillhandahålls av withColors
. Och vi kan inte lägga till komponenter av högre ordning till save
funktionen. Så i save
funktionen är all information vi har attributen.
Det är en bra tumregel att undvika hårdkodning av "har-" klassnamn. Vad händer om WordPress bestämmer sig för att ändra denna regel i framtiden? Som tur är har vi en funktion som kan hjälpa oss att skapa rätt klassnamn för oss: getColorClassName()
.
Innan vi glömmer, låt oss destrukturera det. Det finns också i wp.blockEditor
paketet.
const { InspectorControls, PanelColorSettings, withColors, getColorClassName } = wp.blockEditor;
Användning av getColorClassName()
funktionen kräver två parametrar. Först en sträng för CSS-regeln. Eftersom vår färginställning är för textfärg tillhandahåller vi ‘ color
‘. Detta talar om för funktionen att den ska returnera ett klassnamn av "har-något-färg" och inte "har-något-bakgrundsfärg" till exempel. Som andra parameter måste vi ange värdet på attributet.
Style-attributet byggs helt enkelt genom att ställa in "color" till värdet för attributet customTextColor
, om det är definierat.
Och naturligtvis, glöm inte att tillämpa klassen och stilen på rotnoden i ditt block; som i rad #12
.
PS: Om du testar ditt block i editorn medan du skriver den här koden får du nu ett blockeringsfel. Detta beror på att vi nu har ändrat utdata för save
funktionen och det du har sparat tidigare är i konflikt. Du måste ta bort blocket och lägga till det igen.
Efter denna ändring bör ditt block nu även tillämpa den valda textfärgen i frontend.
Och det är allt! Du har nu framgångsrikt implementerat färginställningar i ditt block. Om du är intresserad av att lägga till flera färginställningar (inte bara textfärg), läs vidare.
En anteckning om flera färginställningar
Vid det här laget bör du kunna implementera flera färginställningar. Du kanske vill lägga till inställningar för bakgrundsfärg, textfärg, kantfärg eller vad som helst annat för ditt block. I det här avsnittet ska jag göra en snabb översikt över vad vi behöver göra för att implementera flera färginställningar.
Låt oss anta att jag vill lägga till bakgrundsfärg till mitt block också.
Först måste jag definiera ett nytt attribut med ett kreativt namn backgroundColor
. Jag definierar ett annat attribut customBackgroundColor
också.
I edit
funktionen ändrar jag det angivna objektet till withColors
:
withColors({textColor: 'color', backgroundColor: 'background-color'})
Detta säger withColors
att mitt textColor
attribut är för CSS-regeln " color
" (för textfärg), och attributet backgroundColor
är för CSS-regeln " background-color
". withColors
kommer automatiskt att känna igen och uppdatera attributen customTextColor
och customBackgroundColor
också.
I PanelColorSettings
komponenten tillhandahåller jag ett annat objekt till arrayen till prop colorSettings
. Såhär:
Med detta bör du få två separata färginställningar inuti Inspector-rutan för färginställningar.
Det sista steget är att bygga lämpliga klassnamn och stilar i både edit
och save
. Detta är ett ganska enkelt steg eftersom det bara är att bygga en sträng eller ett stilobjekt korrekt. Kom ihåg att ditt klassnamn måste stödja flera färgklasser (t.ex. om både textfärg och bakgrundsfärg har valts). Lägg bara till ett mellanslag mellan varje klassnamn.
PS: Om du behöver hantera många klassnamn för ditt block kan du ha nytta av att installera classnames
paketet. I stort sett alla komponenter i Gutenberg använder det här biblioteket för att enklare kombinera klassnamn.
Slutsats och fullständig kod
Du borde nu ha lärt dig hur du implementerar färginställningar i ditt anpassade block. Jag hoppas att detta var till någon nytta för dig! Jag var tvungen att lägga till den här funktionen i mitt projekt, och jag kunde verkligen inte hitta någon information eller bra dokumentation. Så det här är resultatet av att konsolidera allt jag lärt mig om detta ämne, efter mycket försök och misstag.
Här är den slutliga koden, helt och hållet, för det anpassade blocket med textfärginställning: