W tym poście dowiesz się, jak dodać ustawienia kolorów do niestandardowego bloku WordPress Gutenberg. Dowiemy się, jak dodać ten sam składnik ustawień kolorów, który umożliwia wybór kolorów z palety i kolorów niestandardowych, z których korzysta wiele domyślnych bloków WordPressa.
Oto, co dodamy do naszego niestandardowego bloku:
Korzystając z komponentów Gutenberga, możemy bardzo łatwo zaimplementować tę paletę/sekcję kolorów do naszego własnego niestandardowego bloku. Możesz zdefiniować ustawienia kolorów, aby wpłynąć na dowolny kolor; tło, kolor tekstu, kolor obramowania lub cokolwiek innego. Możesz także dodać tyle ustawień kolorów, ile chcesz, do tego panelu.
Zanim zagłębimy się w kod, musisz wiedzieć o kilku rzeczach. Nie przechodź dalej do kodu, ponieważ następna sekcja wyjaśni wiele, dlaczego kod musi robić to tak, jak robi.
Co musisz najpierw wiedzieć
Komponenty do implementacji ustawień palety/koloru to iz PanelColorSettingspakietu. Komponent jest tak zwanym komponentem wyższego rzędu i musi być zaimplementowany nieco inaczej niż zwykłe wyprowadzanie normalnego komponentu. Później omówię trochę więcej szczegółów. Ale najpierw musimy zdać sobie sprawę z podstaw, w jaki sposób Gutenberg obsługuje ustawienia kolorów bloków.withColors``wp.blockEditor``withColors
Jak klocki Gutenberga obsługują ustawienia kolorów
Istnieją pewne zasady dotyczące sposobu, w jaki Gutenberg obsługuje ustawienia kolorów w blokach. Jeśli kiedykolwiek stylowałeś motyw obsługiwany przez Gutenberga, prawdopodobnie znasz już te zasady. Mimo to szybko je przejrzymy, ponieważ musimy sobie z tym poradzić w naszym kodzie blokowym.
- Po wybraniu koloru z palety element bloku węzła otrzyma klasę określonego wzoru. Zajęcia rozpoczynają się od „
has-", a następnie pojawia się ślimak z palety. Zakończenie zależy od tego, na jaki element ma wpływać kolor. Dla koloru tekstu kończy się na „-color“. Dla koloru tła kończy się na „-background-color“. Jako przykład, blok z kolorem palety „red” wybranym jako kolor tła otrzyma klasę „has-red-background-color“. - Po wybraniu niestandardowego koloru (z selektora kolorów), element bloku węzła otrzyma styl wbudowany z kodem szesnastkowym. Na przykład niestandardowy kolor #DD0000 wybrany jako kolor tła otrzyma atrybut „
style="background-color: #DD0000;“.
Kiedy zaimplementujemy ustawienia kolorów dla naszego bloku, będziemy musieli zaimplementować poprawną klasę i styl inline. Zrobimy to na końcu tego samouczka.
Jak pracować zwithColors
Jak wspomniano wcześniej withColors, jest to składnik wyższego rzędu. Zasadniczo oznacza to, że jest to komponent, który pobiera komponent i zwraca nowy komponent. W zwróconym komponencie otrzymujemy przydatne rekwizyty z komponentu wyższego rzędu. Mówiąc prościej, użyjemy withColorsdo zwrócenia własnego komponentu dla naszego niestandardowego bloku. Nasz komponent blokowy otrzymuje niezbędne rekwizyty do pracy z kolorami z withColors.
Komponent withColorsobsługuje stan i wiele funkcji do pracy z kolorami. W tym procesie uzyskujemy dużą automatyzację. Jest to bardzo przydatne do ustalenia, czy wybrany kolor jest kolorem z palety (musimy dodać klasę) czy kolorem niestandardowym (musimy dodać styl liniowy). withColorsznacznie uprościć proces przechowywania wybranego koloru, niezależnie od tego, jaki jest, w atrybutach naszego bloku. A skoro mowa o atrybutach…
Atrybuty iwithColors
Oczywiście twój blok potrzebuje atrybutów do przechowywania wybranego koloru. Aby skorzystać z automatyzacji withColor do przechowywania prawidłowego koloru, musisz zdefiniować dwa atrybuty dla każdego ustawienia koloru. Jeden do przechowywania informacji o kolorze palety, a drugi do przechowywania kodu szesnastkowego. Są jednak pewne zasady.
Załóżmy, że chcesz dodać ustawienie koloru dla koloru tekstu bloku – więc decydujesz się zdefiniować atrybut o trafnej nazwie „ textColor“. Będziesz wtedy musiał zdefiniować kolejny atrybut we wzorcu „ customYourOriginalAttribute“. W tym przykładzie drugi atrybut będzie musiał mieć nazwę „ customTextColor“. Zwróć uwagę na camelCase (wielkość liter) tutaj. Podążanie za tym wzorem withColorsautomatycznie:
- Jeśli został wybrany kolor palety, atrybut „
textColor” będzie zawierał informacje o palecie. - Jeśli został wybrany kolor niestandardowy, „
customTextColor” zostanie uzupełniony kodem szesnastkowym.
Te dwie rzeczy działają w tandemie. W przypadku wybrania koloru niestandardowego textColorautomatycznie zostanie wyświetlony undefined, i na odwrót.
I na koniec, ostatnia rzecz do zapamiętania: nie musisz używać setAttributes()do aktualizowania atrybutów kolorów! Dostarczone rekwizyty z withColorszawierają funkcję, która automatycznie aktualizuje Twoje atrybuty. Wystarczy, że przekażesz tę funkcję do onChangezdarzenia do PanelColorSettingskomponentu, a Twoje atrybuty zostaną automatycznie zaktualizowane.
Ok, czas zobaczyć to wszystko w praktyce!
Wdrażanie ustawień kolorów w bloku niestandardowym
Na początek mam dość bezużyteczny niestandardowy blok, który nie robi nic innego niż wyświetlanie zakodowanego tekstu. To po prostu ułatwia oddzielenie tego, co potrzebujemy do kodu, aby dodać ustawienia kolorów. Mam serię samouczków na temat tworzenia własnych niestandardowych bloków, jeśli chcesz dowiedzieć się więcej.
Uwaga: piszę cały kod w ES6/ESNext. Obejmuje to funkcje strzałek, które wymagają szczególnej uwagi podczas konfiguracji Babel/webpack. Jeśli otrzymujesz błędy w którymś z poniższych kodów, postępuj zgodnie z moim przewodnikiem, jak skonfigurować Webpack i Babel dla ES6/ESNext lub dostosuj kod, aby nie używał „eksperymentalnych składni”.
To jest mój podstawowy niestandardowy blok przed zrobieniem czegokolwiek z ustawieniami kolorów:
To dość podstawowe. Zauważ, że editfunkcja po prostu odwołuje się do oddzielnego komponentu BlockWithColorSettings, zamiast pisać go w linii. Ułatwia to withColorspóźniejszą implementację.
Dobra, czas na wprowadzenie ustawień kolorystycznych do naszego bloku! Jako przykład chcę ustawić kolor tekstu.
Dodawanie atrybutów
Jak wspomniano wcześniej, musimy zdefiniować dwa atrybuty dla każdego ustawienia koloru. I musimy zachować szczególną ostrożność w ich nazewnictwie. Chcę dodać atrybut koloru tekstu, więc nazywam ten atrybut textColor. Co oznacza, że dodam również atrybut customTextColor. Oba powinny być typu string.
Nasze atrybuty są gotowe do przechowywania ustawień koloru tekstu bloku. Teraz nadszedł czas na wdrożenie withColorsi PanelColorSettings.
RealizowaniewithColors
Jak wspomniano wcześniej withColors, jest to składnik wyższego rzędu, który powinien zwrócić składnik. Oczywiście chcemy, aby zwracał nasz komponent edycji, BlockWithColorSettings. Ale jako parametr withColorspodajemy obiekt.
W przekazanym obiekcie withColorsmusimy powiedzieć, withColorsjakiego atrybutu chcemy użyć do przechowywania koloru i jakiego rodzaju elementu będzie on kolorował (w naszym przypadku text color, co oznacza regułę CSS „color”). Informowanie o regule CSS daje pewność, że zwracane nazwy klas są poprawne. Ponieważ jest to kolor tekstu, chcemy mieć nazwy klas, takie jak „ma kolor”.
Najpierw trochę destrukturyzacji na górze. withColorsznajduje się w wp.blockEditorpakiecie.
const { withColors } = wp.blockEditor;Zmienimy editfunkcję na:
Dzięki temu kodowi nasz komponent BlockWithColorSettingsotrzyma dodatkowe rekwizyty:
props.textColor: Jest obiektem, który zawiera wszystkie informacje o wybranym kolorze. Jeśli został wybrany kolor palety, będzie on przechowywać właściwości kodu szesnastkowego, informacji o pracy palety, nazwy klasy i nie tylko. Jeśli wybrano kolor niestandardowy, obiekt będzie zawierał kod szesnastkowy. Kod szesnastkowy zawsze znajduje się we właściwościcolor. A nazwa klasy (tylko jeśli został wybrany kolor palety) zostanie ustawiona we właściwościclass.props.setTextColor: Funkcja, która zaktualizuje dla nas nasze atrybuty. Zapewniamy to dlaonChangezdarzenia ustawień kolorów, jak zobaczymy później. Funkcja zaktualizuje zarówno atrybuty, jaktextColori.customTextColorPonieważ przestrzegaliśmy zasad nazewnictwa, zostanie on automatycznie zaktualizowanycustomTextColor, mimo że nigdy nie podaliśmy tej nazwy atrybutu.
Zauważ, że funkcja „set” dostarczona jako prop będzie zgodna z regułą: „ setYourAttributeName“. Ponieważ podaliśmy textColor, funkcja ma nazwę setTextColor. Gdybyśmy zamiast tego nazwali nasz atrybut awesomeColori dostarczyli to w withColorsobiekcie, funkcja set-była nazwana setAwesomeColor().
RealizowaniePanelColorSettings
Kolejnym krokiem jest wdrożenie właściwej sekcji Inspektora. W tym celu dodajemy PanelColorSettingswewnątrz InspectorControlskomponentu. Ponieważ React wymaga, aby wszystko znajdowało się w jednym węźle głównym, używamy również Fragment(from wp.elements) do owinięcia wszystkiego wewnątrz.
Najpierw trochę destrukturyzacji na górze pliku:
const { Fragment } = wp.element;
const { InspectorControls, PanelColorSettings, withColors } = wp.blockEditor;I aktualizujemy nasz BlockWithColorSettingskomponent do czegoś takiego:
Jak widać #2, destrukturyzujemy rekwizyty otrzymane z withColors, textColororaz setTextColor. Pamiętaj, że props.textColorjest to obiekt otrzymany z withColors, i props.attributes.textColorjest atrybutem. Nie musimy jednak odwoływać się do atrybutu.
Jako rekwizyty do komponentu PanelColorSettingsmożemy podać tytuł sekcji (tytuł w zwijanym polu w Inspektorze). Ważną rzeczą jest tutaj rekwizyt, w colorSettingsktórym musimy zapewnić szereg obiektów ustawiających kolory. Dla każdego ustawienia koloru (obecnie mamy tylko jedno) musimy podać pewne właściwości. Właściwość valueoczekuje aktualnie wybranego kodu szesnastkowego (mimo że wybrano kolor palety). Jest to dla nas przewidziane w textColorrekwizycie, we wnętrzu posesji color. Dla onChangewłaściwości podajemy po prostu funkcję „ustaw” dostarczoną przez withColors, setTextColor. I na koniec powinniśmy podać label, aby użytkownik wiedział, na jaki element wpłynie ten kolor. Pojawi się tuż nad obszarem wyboru koloru.
Oto jak nasz komponent pojawia się teraz w edytorze Gutenberg:
Teraz z powodzeniem aktualizuje nasze atrybuty przy wyborze kolorów. Widać, że zapamiętuje wybrany przez Ciebie kolor podczas zapisywania posta.
Jednak nic nie dzieje się wizualnie, gdy zmieniasz kolory. Wybór koloru jest przechowywany w atrybutach, ale zmiana koloru nie następuje w edytorze ani podczas podglądu posta. Dzieje się tak, ponieważ musimy dodać kod dla klas i stylów bloku. Musimy to zrobić zarówno dla editfunkcji (czyli dla edytora), jak i savefunkcji (frontend). To kolejny krok.
Obsługa stylów klasowych i wbudowanych wedit
Musimy zbudować klasę węzła i atrybuty stylu bloku zgodnie z wybranym ustawieniem koloru. Na szczęście withColorsotrzymujemy w tym pewną automatyzację. Pamiętaj, że props.textColorjest to obiekt, który zawiera wszystkie potrzebne nam informacje, w tym nazwę klasy.
Moglibyśmy zrobić coś takiego:
W linii #20stosujemy klasę krytyczną i styl inline do węzła głównego naszego bloku. Wcześniej budujemy atrybut class i inline style, sprawdzając props.textColorobiekt.
Po tej zmianie Twój niestandardowy blok powinien być teraz w pełni funkcjonalny w edytorze. Za każdym razem, gdy zmienisz kolor, blok zmieni kolor tekstu. Wspaniały! Ostatnim krokiem jest zrobienie tego również dla savefunkcji, tak aby te klasy i style również dostały się do interfejsu.
Obsługa stylów klasowych i wbudowanych wsave
Koncepcja budowania klas i stylów wbudowanych oraz stosowania ich do węzła głównego jest taka sama savejak w programie edit. Ale jest zasadnicza różnica. W savenie mamy rekwizytów dostarczonych przez withColors. I nie możemy dodać do savefunkcji komponentów wyższego rzędu. Tak więc w savefunkcji wszystkie informacje jakie posiadamy są atrybutami.
To dobra praktyczna zasada, aby uniknąć zakodowania „ma-” nazw klas. Co się stanie, jeśli WordPress zdecyduje się zmienić tę zasadę w przyszłości? Na szczęście mamy funkcję, która może nam pomóc wygenerować dla nas odpowiednie nazwy klas: getColorClassName().
Zanim zapomnimy, zniszczmy to. Jest również w wp.blockEditoropakowaniu.
const { InspectorControls, PanelColorSettings, withColors, getColorClassName } = wp.blockEditor;Użycie getColorClassName()funkcji wymaga dwóch parametrów. Najpierw ciąg dla reguły CSS. Ponieważ nasze ustawienie kolorów dotyczy koloru tekstu, zapewniamy „ color“. To mówi funkcji, że powinna zwrócić nazwę klasy „ma-coś-kolor”, a nie „ma-coś-kolor-tła”. Jako drugi parametr musimy podać wartość atrybutu.
Atrybut style jest po prostu budowany przez ustawienie „color” na wartość atrybutu customTextColor, jeśli jest zdefiniowany.
I oczywiście nie zapomnij zastosować klasy i stylu do węzła głównego swojego bloku; jak w kolejce #12.
PS: Jeśli testujesz swój blok w edytorze podczas pisania tego kodu, otrzymasz teraz błąd bloku. Dzieje się tak, ponieważ teraz zmieniliśmy dane wyjściowe savefunkcji i cokolwiek zapisałeś wcześniej, jest w konflikcie. Będziesz musiał usunąć blok i ponownie go dodać.
Po tej zmianie twój blok powinien teraz poprawnie zastosować wybrany kolor tekstu również w interfejsie.
I to wszystko! Pomyślnie zaimplementowałeś ustawienia kolorów do swojego bloku. Jeśli chcesz dodać wiele ustawień kolorów (nie tylko kolor tekstu), czytaj dalej.
Uwaga na temat wielu ustawień kolorów
Do tej pory powinieneś być w stanie zaimplementować wiele ustawień kolorów. Możesz dodać ustawienia koloru tła, koloru tekstu, koloru obramowania lub czegokolwiek innego do swojego bloku. W tej sekcji zrobię szybki przegląd tego, co musimy zrobić, aby zaimplementować wiele ustawień kolorów.
Załóżmy, że chcę dodać kolor tła do mojego bloku.
Najpierw muszę zdefiniować nowy atrybut o nazwie twórczo backgroundColor. Zdefiniuję też inny atrybut customBackgroundColor.
W editfunkcji zmieniam udostępniony obiekt na withColorstaki:
withColors({textColor: 'color', backgroundColor: 'background-color'})Oznacza to withColors, że mój textColoratrybut jest dla reguły CSS „ color” (dla koloru tekstu), a atrybut backgroundColorjest dla reguły CSS „ background-color“. withColorsautomatycznie rozpozna i zaktualizuje również atrybuty i customTextColor.customBackgroundColor
W PanelColorSettingskomponencie dostarczam kolejny obiekt do tablicy do prop colorSettings. Tak jak:
Dzięki temu powinieneś uzyskać dwa oddzielne ustawienia kolorów w polu Inspektora dla ustawień kolorów.
Ostatnim krokiem jest zbudowanie odpowiednich nazw klas i stylów w obu editi save. Jest to dość prosty krok, ponieważ jest to po prostu poprawne budowanie ciągu lub obiektu stylu. Pamiętaj, że nazwa Twojej klasy musi obsługiwać wiele klas kolorów (np. jeśli wybrano zarówno kolor tekstu, jak i kolor tła). Po prostu dodaj spację między każdą nazwą klasy.
PS: Jeśli potrzebujesz obsłużyć wiele nazw klas dla swojego bloku, możesz skorzystać z zainstalowania classnamespakietu. Prawie wszystkie komponenty w Gutenbergu używają tej biblioteki do łatwiejszego łączenia nazw klas.
Wniosek i pełny kod
Powinieneś się teraz nauczyć, jak zaimplementować ustawienia kolorów w swoim bloku niestandardowym. Mam nadzieję, że to ci się przyda! Musiałem dodać tę funkcję do mojego projektu i naprawdę nie mogłem znaleźć żadnych informacji ani dobrej dokumentacji. Jest to więc efekt utrwalenia wszystkiego, czego się dowiedziałem na ten temat, po wielu próbach i błędach.
Oto końcowy kod, łącznie, dla przykładowego bloku niestandardowego z ustawieniem koloru tekstu: