W tej części napiszemy Javascript, aby zarejestrować i skonfigurować nasz niestandardowy blok. Na koniec zarejestrujemy skrypt w PHP i wykonamy niezbędny kod PHP, aby WordPress rozpoznał go jako nowy blok.
Najpierw krótka informacja o tym, jak uzyskać dostęp do funkcji i komponentów WordPress Gutenberg.
Pakiet globalny wpi destrukturyzacja
Kiedy jesteśmy w pliku JavaScript umieszczonym w kolejce w edytorze Gutenberg, mamy dostęp do globalnego obiektu/pakietu: wp. Jest to bardzo, bardzo duży obiekt JavaScript i zawiera całą masę przydatnych komponentów i funkcji, których użyjemy do tworzenia bloków. Pisząc JavaScript dla bloków niestandardowych, będziesz odwoływać się do wpwielu.
Dlatego powszechne jest, zarówno we współczesnym JavaScript, jak i w React, destrukturyzację tego, czego chcemy z niego użyć. Zasadniczo oznacza to po prostu, że definiujemy zmienne lokalne z części większej struktury. Na przykład pierwsza funkcja, której użyjemy, to registerBlockType()ta, która istnieje w wp.blocks. Możemy wywołać funkcję tak:
wp.blocks.registerBlockType();Ale łatwiej to zdekonstruować tak:
const { registerBlockType } = wp.blocks;
registerBlockType();Teraz możesz odwoływać się do funkcji bezpośrednio, bez poprzedzania jej strukturą. O wiele bardziej przydaje się, gdy odwołujemy się do funkcji lub komponentów, które będziemy często powtarzać.
W tej serii przeprowadzimy restrukturyzację, a w miarę postępów w samouczku zobaczymy, o ile bardziej czytelny i krótszy będzie nasz kod.
Rejestracja nowego bloku
W pakiecie registerBlockType()dostępna jest funkcja rejestracji nowego bloku niestandardowego. wp.blocksPrzyjmuje dwa parametry; po pierwsze ciąg z przestrzenią nazw i nazwą bloku, a po drugie obiekt z pełną konfiguracją bloku.
Gutenberg oczekuje, że wszystkie bloki będą miały przestrzeń nazw i nazwę zdefiniowaną z ukośnikiem pomiędzy nimi. Przestrzeń nazw ma zapewnić, że nazwa bloku nie będzie kolidować z innymi blokami, które mogą używać tej samej nazwy. Wszystkie bloki w WordPressie używają przestrzeni nazw core. Na przykład standardowy blok akapitu w WordPressie ma nazwę core/paragraph. Jeśli wybierzesz inną przestrzeń nazw, możesz również utworzyć blok o nazwie akapit bez powodowania żadnych problemów.
Wybierz unikalną dla siebie przestrzeń nazw wersji slugu. W tej serii użyję przestrzeni nazw awp(krótkiej wersji A White Pixel).
Otwórz plik źródłowy, który stworzyliśmy w ostatnim kroku; src/block-awhitepixel-myfirstblock.js, w edytorze. Najpierw zadzwonimy registerBlockTypez destructured wp.blocks, o nazwie awp/firstblock. Dostosuj swoją nazwę i przestrzeń nazw na bieżąco.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});W drugim parametrze, obiekcie konfiguracji bloku, musimy zdefiniować kilka właściwości, aby został pomyślnie zarejestrowany. Pamiętaj, że konfiguracja bloku jest obiektem, co oznacza, że musisz zapisać wszystko jako pary klucz + wartość, oddzielone przecinkiem. Istnieje wiele możliwych właściwości konfiguracyjnych, więc przejrzyjmy je, a na końcu zobaczymy ostateczny kod.
Wymagane: tytuł
Pierwsza wymagana właściwość to title. To jest nazwa, która pojawi się po wybraniu między blokami. Ustaw tę właściwość jako dowolną nazwę, którą chcesz w ciągu.
Jako tytuł dodamy:
title: 'My first block',PS: Przyjrzymy się ponownie, jak piszemy wszystkie łańcuchy w naszym bloku, aby upewnić się, że można je przetłumaczyć w części 8. Ale na razie zachowamy prostotę i po prostu napiszemy łańcuchy.
Wymagane: kategoria
Właściwość categoryokreśla, w której kategorii bloków pojawi się Twój blok po wybraniu bloków do wstawienia w edytorze. Możliwe wartości to common, formatting, layout, widgets, embed.
Umieśćmy to w commonpierwszej kategorii bloków.
category: 'common',Opcjonalnie: ikona
Jeśli korzystałeś z Gutenberga, prawdopodobnie zauważyłeś, że wszystkie bloki mają ikony. Możesz dodać ikonę do swojego bloku z ciągiem, który odnosi się do dowolnego z dashikonów WordPressa, lub możesz dodać niestandardowy svgelement.
Wybiorę tylko jeden z dashikonów WordPressa, buźkę – ale możesz wybrać dowolny. Zauważ, że pomijasz dodawanie „dashicons-" do nazwy klasy ikony.
icon: 'smiley',Opcjonalnie: opis
Możesz podać opis, który będzie wyświetlany na pasku bocznym Ustawienia (po prawej stronie), gdy blok jest aktywny.
Jako przykład dodam tylko krótki tekst:
description: 'Learning in progress',Opcjonalnie: słowa kluczowe
Gutenberg obsługuje funkcję wyszukiwania przy wyborze typów bloków. We właściwości można podać tablicę możliwych dopasowań keywords. Bez keywordstego znalazłbyś swój blok, wyszukując jego nazwę.
Dodam examplei test, abyśmy mogli łatwo znaleźć nasz niestandardowy blok, gdy zaczniemy wpisywać jedno z tych słów kluczowych.
keywords: ['example', 'test'],Opcjonalnie: atrybuty
Właściwość attributesjest bardzo ważną właściwością, do której będziemy często wracać w tej serii samouczków. Tutaj przechowujesz swoje dane strukturalne i informacje wprowadzane przez użytkownika dla swojego bloku. Możesz to sobie wyobrazić jako zmienne. Na razie tego nie dodamy, ale na pewno niedługo do tego wrócimy.
(rodzaj) wymagane: edytuj i opcjonalnie: zapisz
W ramach właściwości editi savew rzeczywistości dodasz cały kod zarówno dla danych wyjściowych edytora, jak i dla renderowania frontendu. Obie te właściwości oczekują funkcji, która powinna zwrócić pewne dane wyjściowe.
Właściwość editopisuje strukturę Twojego bloku w edytorze. Właściwość savezasadniczo obsługuje dwie rzeczy; Twoje dane wyjściowe bloku w interfejsie użytkownika, ale także struktura tego, w jaki sposób Twój blok jest zapisywany w bazie danych. Będziesz pracować głównie w edittym miejscu, w którym dodajesz dane wejściowe do wprowadzania lub wybierania rzeczy oraz aktualizowania danych bloku. Funkcja savenie powinna w żaden sposób aktualizować ani edytować danych, powinna po prostu wyprowadzać.
Gutenberg musi być w stanie zrekonstruować twój blok ze wszystkimi jego ustawieniami w edytorze na podstawie tego, co jest wyjściowe w savefunkcji (i atrybutach). Jeśli Gutenberg kiedykolwiek otworzy post, w którym poprzednio zapisane dane wyjściowe bloku różnią się (nawet nieznacznie) od tego, co zdefiniowano w zapisie, twój blok stanie się nieważny.
Gwarantuję Ci, że będziesz się z tym często spotykać podczas tworzenia niestandardowych bloków. Kiedy tak się stanie, musisz usunąć blok (z kropek na pasku narzędzi) i dodać go ponownie. Polecam też zrobić odświeżanie przeglądarki (F5 lub CTRL+R).
WordPress ma dedykowaną stronę dokumentacji dla funkcji edycji i zapisywania bloku, jeśli chcesz dowiedzieć się więcej.
Jeśli chodzi o nasz pierwszy blok, wypiszmy coś podstawowego. Zwrócimy to samo dla obu editi save; „:)” zawinięty w <div>. Ikona bloku to w końcu buźka.
Inne właściwości
Istnieje więcej opcjonalnych właściwości dla registerBlockType; parent, supports, transforms, example, i styles. Na razie pominiemy je, ponieważ większość z nich dotyczy bardziej zaawansowanego lub niestandardowego budowania bloków. Jeśli chcesz dowiedzieć się więcej na ten temat, zapoznaj się z dokumentacją WordPressa.
Kod bloku końcowego rejestru
Nasz kod wygląda teraz mniej więcej tak.
Dzięki temu mamy wystarczająco dużo, aby nasz blok został pomyślnie zarejestrowany jako blok niestandardowy. Zobaczmy to w praktyce w edytorze Gutenberga.
Czy pamiętałeś o skompilowaniu kodu JavaScript? W poprzednim kroku dowiedzieliśmy się, że nie możemy załadować tego pliku JavaScript do Gutenberga; potrzebujemy skompilowanej wersji. Zwykle rozwijasz się npm run startdziałając w tle lub możesz po prostu uruchomić npm run buildraz teraz. Powinno to skompilować nasz źródłowy Javascript i umieścić go w dowolnym miejscu, w którym ma być umieszczony i nazwany w pliku webpack.config.js.
Część PHP rejestracji bloku
Dla każdego bloku musisz zarejestrować plik Javascript i jest to dokładnie to samo, co inne skrypty w WordPressie – używając [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Zauważ, że rejestrujemy skrypt, a nie umieszczamy go w kolejce. Dzieje się tak dlatego, że musimy również wywołać funkcję PHP, aby zarejestrować każdy niestandardowy blok, a ta funkcja jest odpowiedzialna za kolejkowanie skryptu, gdy jest to potrzebne.
Wolę trzymać kod związany z Gutenbergiem w osobnym pliku w moich motywach. Ale możesz, i będziemy w tym samouczku, po prostu napisać cały kod PHP bezpośrednio w motywie functions.phpdla uproszczenia.
Zalecam używanie inithaka do swojej funkcji, a nie enqueue_block_assets. Możemy połączyć zarówno rejestrację skryptu, jak i rejestrację bloku.
Funkcja PHP, której użyjemy do zarejestrowania nowego bloku to [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Podobnie jak Javascript registerBlockType()przyjmuje dwa parametry; przestrzeń nazw i nazwę bloku oraz tablicę z argumentami. Upewnij się, że podajesz dokładnie taką samą przestrzeń nazw i nazwę w PHP jak w JavaScript.
W drugim argumencie jest kilka możliwych argumentów (do niektórych wrócimy w dalszej części tej serii). Ale najważniejszą z nich jest editor_scriptmiejsce, w którym podajesz uchwyt (pierwszy parametr wp_register_script()) zarejestrowanego skryptu.
I to wszystko!
Nasz blok w edytorze Gutenberg
Teraz, gdy odświeżysz edytor w jakimś poście, powinieneś znaleźć nasz blok – albo otwierając kategorię Wspólne, albo wyszukując dowolne z podanych słów kluczowych lub nazwy.
Nasz blok renderuje proste „:)” zarówno w edytorze, jak i we frontendzie. Na razie nie możesz edytować niczego w bloku, ale tego nauczymy się w kolejnych krokach!