Budowanie niestandardowych bloków Gutenberga: ostateczny samouczek dotyczący tworzenia bloków

Wiele osób narzeka na przeszkody w rozpoczęciu budowania bloków i aplikacji Gutenberga. Krzywa uczenia się jest stroma, głównie z powodu trudności w instalacji i konfiguracji środowiska programistycznego. Ponadto solidna znajomość JavaScript, Node.js, React i Redux to niezbędne składniki tego dość złożonego przepisu.

Oficjalny podręcznik edytora bloków WordPress zapewnia programistom ogromną ilość informacji, ale możesz zagubić się w tym morzu szczegółów.

A warto wspomnieć o tym, co Matias Ventura, główny architekt projektu Gutenberg, relacjonował w rozmowie z WP Tavern:

Chociaż są ludzie, którzy mogą się tego szybko nauczyć, nadal stanowi to dużą barierę dla ludzi. Myślę, że jest na to kilka warstw; dokumentacja może być o rząd wielkości lepsza zarówno pod względem organizacji, jak i prezentacji. Mam nadzieję, że możemy tam zrobić o wiele więcej.

Mając to na uwadze, postanowiliśmy udostępnić samouczek krok po kroku, który ma pomóc naszym czytelnikom w rozpoczęciu pracy z blokiem Gutenberga.

Brzmi interesująco? Zanurzmy się!

Wymagania wstępne dotyczące rozwoju bloku Gutenberg

W tym samouczku jedyne wymagane umiejętności to dobra znajomość tworzenia wtyczek WordPress i przynajmniej podstawowa znajomość HTML, CSS, JavaScript i React.

Czy to będzie ambitny projekt? Założysz się, że tak będzie!

Nie było łatwo znaleźć właściwy kompromis między kompletnością a prostotą ani zdecydować, które tematy włączyć, a które pominąć.

Miejmy nadzieję, że średniozaawansowani i zaawansowani czytelnicy wybaczą nam, że nie zagłębiamy się w pewne koncepcje, takie jak stan reakcji, sklep Redux, komponenty wysokiego zamówienia i tak dalej. Te tematy wymagają dodatkowej przestrzeni i uwagi i są prawdopodobnie zbyt zaawansowane, aby rozpocząć tworzenie bloków (chyba że jesteś programistą React).

Z tego samego powodu nie będziemy omawiać niektórych bardziej zaawansowanych tematów związanych z rozwojem bloków Gutenberga, takich jak dynamiczne bloki i metaboxy.

Dzięki wiedzy, którą zdobędziesz pod koniec tego artykułu, będziesz mógł od razu zacząć się bawić i być produktywnym.

Gdy zaczniesz budować bloki, będziesz mógł dalej doskonalić swoje umiejętności i samodzielnie budować jeszcze bardziej zaawansowane bloki Gutenberga.

Co to jest blok Gutenberga?

Od czasu premiery w grudniu 2018 r. edytor bloków został znacznie ulepszony we wszystkich aspektach: wydajniejsze interfejsy API, bardziej zaawansowany interfejs użytkownika, ulepszona użyteczność, mnóstwo nowych bloków, pierwsze implementacje pełnej edycji witryny i wiele więcej .

Krótko mówiąc, nawet jeśli Gutenberg jest wciąż w fazie intensywnego rozwoju, przebył długą drogę — a dziś edytor bloków jest pełnoprawnym kandydatem jako niezawodny, funkcjonalny kreator stron i witryn.

Z punktu widzenia programisty, Gutenberg jest jednostronicową aplikacją opartą na React (SPA), która umożliwia użytkownikom WordPressa tworzenie, edytowanie i usuwanie treści w WordPressie. Nie powinno to jednak skłaniać do myślenia o ulepszonej wersji tradycyjnego edytora treści.

Chcemy to wyjaśnić:

W Gutenberg treść jest podzielona na bloki, które są „cegłami”, których użytkownicy mogą używać do tworzenia postów i stron lub całych witryn internetowych.

Ale czym technicznie jest blok?

Podoba nam się definicja WordPressa:

„Blok” to abstrakcyjny termin używany do opisania jednostek znaczników, które, skomponowane razem, tworzą treść lub układ strony internetowej. Pomysł łączy koncepcje tego, co dziś w WordPress osiągamy za pomocą skrótów, niestandardowego HTML i embed Discovery w jednym spójnym interfejsie API i doświadczeniu użytkownika.

Tytuły, akapity, kolumny, obrazy, galerie i wszystkie elementy, które składają się na interfejs edytora, od paneli paska bocznego po blokowe kontrolki paska narzędzi, są komponentami React.

Czym więc są komponenty Reacta? W3Schools podaje następującą definicję:

Komponenty to niezależne i wielokrotnego użytku bity kodu. Służą temu samemu celowi co funkcje JavaScript, ale działają w izolacji i zwracają kod HTML za pomocą funkcji render() .

Podczas gdy doświadczenie edycji dostarczane przez Gutenberga jest nowe w porównaniu z klasycznym edytorem WordPress, sposób, w jaki WordPress przechowuje twoje treści w bazie danych, wcale się nie zmienia. Dzieje się tak, ponieważ Gutenberg to aplikacja, która działa w ramach WordPressa, ale nie zmienia sposobu, w jaki działa CMS.

Posty (w tym posty, strony i niestandardowe typy postów) utworzone za pomocą Gutenberga są nadal przechowywane w tabeli wp_posts , dokładnie tak jak w klasycznym edytorze.

Ale w poście utworzonym za pomocą Gutenberga znajdziesz dodatkowe informacje w tabeli, które reprezentują fundamentalną różnicę między postami utworzonymi za pomocą Edytora klasycznego i Gutenberga.

Te informacje wyglądają jak komentarze HTML i mają określoną funkcję: rozdzielanie bloków:

Ograniczniki bloków informują WordPress, jaki blok ma być renderowany na ekranie. Dostarczają również wartości dla właściwości bloku w obiekcie JSON. Te rekwizyty dyktują sposób renderowania bloku na ekranie:

Konfigurowanie środowiska programistycznego WordPress

Stworzenie nowoczesnego środowiska programistycznego JavaScript wymaga solidnej znajomości zaawansowanych technologii, takich jak Webpack, React i JSX, Babel, ESLint itp.

Zastraszony? Nie bądź! Społeczność WordPressa już przyszła na ratunek, dostarczając potężne narzędzia, które pozwalają uniknąć niechlujnego procesu ręcznej konfiguracji.

Aby uprościć sprawę, w tym artykule nie będziemy omawiać transpilowania (z czym jednak zalecamy zapoznanie się po zapoznaniu się z podstawami tworzenia bloków). Zamiast tego przedstawimy dwa alternatywne narzędzia, których możesz użyć do szybkiego i łatwego skonfigurowania nowoczesnego środowiska programistycznego JavaScript w ciągu kilku minut. Od Ciebie zależy, który z nich będzie najwygodniejszy dla Twojego projektu.

Konfigurowanie środowiska programistycznego JavaScript do budowania bloków Gutenberga to trzyetapowy proces:

1. Zainstaluj Node.js i npm
2. Skonfiguruj środowisko programistyczne
3. Skonfiguruj wtyczkę blokową

Zacznijmy.

1. Zainstaluj Node.js i npm

Przed zainstalowaniem środowiska programistycznego i zarejestrowaniem pierwszego bloku, musisz zainstalować Node.js i menedżera pakietów Node (npm).

Możesz zainstalować Node.js i npm na kilka różnych sposobów. Ale najpierw możesz sprawdzić, czy oprogramowanie jest już zainstalowane na twoim komputerze.

Aby to zrobić, uruchom terminal i uruchom następujące polecenie:

 node -v

Jeśli wynikiem jest command not found , oznacza to, że Node.js nie jest zainstalowany na twoim komputerze i możesz kontynuować instalację.

W tym artykule wybraliśmy najłatwiejszą opcję instalacji, którą jest Instalator węzła. Wystarczy pobrać wersję odpowiadającą Twojemu systemowi operacyjnemu i uruchomić kreatora instalacji:

Po zainstalowaniu Node.js uruchom ponownie polecenie node -v w terminalu. Możesz również uruchomić polecenie npm -v , aby potwierdzić, że masz dostępny pakiet npm.

Jesteś teraz wyposażony w następujące narzędzia:

• Program uruchamiający pakiet npx Node.js (patrz dokumentacja). Pozwala to na uruchomienie polecenia npm bez uprzedniego instalowania go.
• Menedżer pakietów npm Node.js (patrz dokumentacja). Służy do instalowania zależności i uruchamiania skryptów.

Następnym krokiem jest zainstalowanie środowiska programistycznego.

2. Skonfiguruj swoje środowisko programistyczne

Po zainstalowaniu najnowszych wersji Node.js i npm na komputerze lokalnym będziesz potrzebować środowiska programistycznego dla WordPress.

Możesz użyć lokalnego środowiska programistycznego, takiego jak DevKinsta, lub użyć oficjalnego narzędzia WordPress. Rzućmy okiem na obie opcje.

Opcja 1: Lokalne środowisko programistyczne (DevKinsta)

Wystarczy kilka kliknięć, aby zainstalować WordPress lokalnie za pomocą DevKinsta, naszego nowoczesnego lokalnego narzędzia programistycznego WordPress. Możesz też wybrać inne narzędzie do programowania lokalnego, takie jak MAMP lub XAMPP:

Opcja 2: wp-env

Możesz także wybrać oficjalne narzędzie wp-env , które zapewnia lokalne środowisko programistyczne WordPress, które możesz uruchomić bezpośrednio z wiersza poleceń. Noah Alen definiuje to w następujący sposób:

Lokalne środowiska WordPress są teraz tak proste, jak uruchomienie jednego polecenia. wp-env to zerowe narzędzie konfiguracyjne dla bezbolesnych lokalnych środowisk WordPress. Zapewnia decyzje dotyczące opcji, dzięki czemu użytkownicy mogą szybko uruchomić WordPress bez marnowania czasu. Rzeczywiście, celem jest uczynienie tych środowisk łatwo dostępnymi dla wszystkich — niezależnie od tego, czy jesteś programistą, projektantem, menedżerem, czy kimkolwiek innym.

Jeśli zdecydujesz się spróbować, instalacja wp-env wymaga minimalnego wysiłku. Wystarczy wykonać następujące kroki:

Krok 1: Potwierdź instalację Dockera i Node.js

Aby spełnić wymagania techniczne, musisz najpierw zainstalować na swoim komputerze zarówno Docker, jak i Node.js. Dzieje się tak, ponieważ wp-env tworzy instancję Dockera z witryną WordPress. Wszelkie zmiany wprowadzone w kodzie są natychmiast odzwierciedlane w instancji WordPress.

Krok 2: Zainstaluj @wordpress/env z wiersza poleceń

Z Dockerem i Node.js działającymi na Twoim komputerze, możesz przejść dalej i zainstalować środowisko programistyczne WordPress.

Możesz zainstalować wp-env globalnie lub lokalnie. Aby zrobić to globalnie, musisz uruchomić następujące polecenie z katalogu wtyczek (więcej na ten temat w polu „Ważne” poniżej):

 npm install -g @wordpress/env

Rozłóżmy to:

• npm install instaluje pakiet.
• -g dołączona do polecenia instaluje określony pakiet globalnie.
• @wordpress/env to pakiet, który zamierzasz zainstalować.

Aby potwierdzić, że wp-env został pomyślnie zainstalowany, uruchom następujące polecenie:

 wp-env --version

Powinieneś zobaczyć aktualną wersję wp-env , co oznacza, że ​​możesz teraz uruchomić środowisko za pomocą następującego polecenia z folderu wtyczki:

 wp-env start

Możesz uzyskać dostęp do pulpitu WordPress pod następującym adresem:

• http://localhost:8888/wp-admin/

Domyślne poświadczenia są następujące:

• Nazwa użytkownika: admin
• Hasło: password

Skonfiguruj wtyczkę blokującą

Teraz potrzebujesz wtyczki bloku startowego, na której możesz budować. Ale zamiast ręcznie tworzyć wtyczkę blokową ze wszystkimi niezbędnymi plikami i folderami, możesz po prostu uruchomić narzędzie programistyczne zawierające wszystkie pliki i konfiguracje, których potrzebujesz, aby rozpocząć tworzenie bloków.

Ponownie masz kilka opcji do wyboru. Przyjrzyjmy się każdemu.

Opcja 1: Konfigurowanie wtyczki blokującej za pomocą @wordpress/create-block

@wordpress/create-block to oficjalne narzędzie do konfiguracji zerowej do tworzenia bloków Gutenberga:

Utwórz blok to oficjalnie obsługiwany sposób tworzenia bloków do rejestracji bloku dla wtyczki WordPress. Oferuje nowoczesną konfigurację kompilacji bez konfiguracji. Generuje kod PHP, JS, CSS i wszystko inne, czego potrzebujesz do uruchomienia projektu.

Jest w dużej mierze inspirowany aplikacją create-react-app. Wielkie uznanie dla @gaearon, całego zespołu Facebooka i społeczności React.

Po uruchomieniu środowiska lokalnego możesz skonfigurować blok startowy, po prostu uruchamiając polecenie npx @wordpress/create-block , które zapewni wszystkie pliki i foldery potrzebne do utworzenia rusztowania wtyczki i zarejestrowania nowego bloku .

Przeprowadźmy test, aby zobaczyć, jak to działa.

W narzędziu wiersza poleceń przejdź do katalogu /wp-content/plugins/ i uruchom następujące polecenie:

 npx @wordpress/create-block my-first-block

Gdy pojawi się prośba o potwierdzenie, wprowadź y , aby kontynuować:

Proces trwa kilka chwil. Po zakończeniu powinieneś otrzymać następującą odpowiedź:

I to wszystko!

Teraz uruchom środowisko programistyczne WordPress i przejdź do ekranu Wtyczki na pulpicie nawigacyjnym WordPress. Nowa wtyczka o nazwie „Mój pierwszy blok” powinna zostać dodana do Twojej listy wtyczek:

W razie potrzeby aktywuj wtyczkę, utwórz nowy post na blogu, przewiń w dół moduł wstawiania bloków do sekcji Widgety i wybierz nowy blok:

Teraz wróć do terminala i zmień bieżący katalog na mój-pierwszy-blok :

 cd my-first-block

Następnie uruchom następujące polecenie:

 npm start

Umożliwia to uruchomienie wtyczki w trybie programistycznym. Aby utworzyć kod produkcyjny, należy użyć następującego polecenia:

 npm run build

Opcja 2: Konfigurowanie wtyczki blokującej za pomocą create-guten-block

create-guten-block to zewnętrzne narzędzie programistyczne do budowania bloków Gutenberga:

create-guten-block to zestaw narzędzi programistycznych o zerowej konfiguracji (#0CJS) do tworzenia bloków WordPress Gutenberg w ciągu kilku minut bez konfigurowania React, webpack, ES6/7/8/Next, ESLint, Babel itp.

Podobnie jak oficjalne narzędzie do create-block , create-guten-block opiera się na aplikacji create-react-app i może pomóc w bezproblemowym wygenerowaniu pierwszej wtyczki bloku.

Zestaw narzędzi zapewnia wszystko, czego potrzebujesz do stworzenia nowoczesnej wtyczki WordPress, w tym:

• Obsługa składni React, JSX i ES6.
• Za kulisami proces tworzenia i tworzenia pakietu webpack.
• Dodatki językowe poza ES6, takie jak operator rozsyłania obiektów.
• CSS z automatycznym prefiksem, więc nie potrzebujesz -webkit ani innych prefiksów.
• Skrypt kompilacji do łączenia JS, CSS i obrazów do produkcji z mapami źródłowymi.
• Bezproblemowe aktualizacje powyższych narzędzi z pojedynczą zależnością cgb-scripts.

Zwróć uwagę na następujące zastrzeżenie:

Kompromis polega na tym, że narzędzia te są wstępnie skonfigurowane do pracy w określony sposób. Jeśli Twój projekt wymaga większego dostosowania, możesz go „wysunąć” i dostosować, ale wtedy będziesz musiał zachować tę konfigurację.

Gdy masz już pod ręką lokalną witrynę WordPress, uruchom narzędzie wiersza poleceń, przejdź do folderu /wp-content/plugins swojej instalacji i uruchom następujące polecenie:

 npx create-guten-block my-first-block

Będziesz musiał poczekać minutę lub dwie, aż struktura projektu zostanie utworzona i pobrane zależności:

Po zakończeniu procesu powinieneś zobaczyć następujący ekran:

Ten następny obraz przedstawia strukturę projektu z terminalem działającym w Visual Studio Code:

Teraz wróć do pulpitu WordPress. Nowy element powinien pojawić się na ekranie Wtyczki — jest to wtyczka mój pierwszy blok :

Aktywuj wtyczkę i wróć do terminala. Zmień bieżący katalog na my-first-block , a następnie uruchom npm start :

 cd my-first-block npm start

Powinieneś otrzymać następującą odpowiedź:

Ponownie, umożliwia to uruchomienie wtyczki w trybie programistycznym. Aby stworzyć kod produkcyjny, powinieneś użyć:

 npm run build

Aktywuj wtyczkę i utwórz nowy post lub stronę, a następnie przeglądaj swoje bloki i wybierz nowy blok Gutenberga:

Aby uzyskać bardziej szczegółowy przegląd lub w przypadku błędów, zapoznaj się z dokumentacją dostarczoną przez Ahmada Awaisa.

Przewodnik po rusztowaniu bloku startowego

Niezależnie od tego, które z dwóch narzędzi programistycznych — create-block lub create-guten-block — wybierzesz, masz teraz rusztowanie blokowe, którego możesz użyć jako punktu wyjścia do zbudowania wtyczki blokowej.

Ale czym właściwie jest rusztowanie blokowe?

Rusztowanie blokowe to skrót opisujący strukturę katalogów pomocniczych potrzebną do rozpoznawania bloku przez WordPress. Zazwyczaj ten katalog zawiera pliki takie jak index.php , index.js , style.css i inne — które z kolei przechowują wywołania takie jak register_block_type .

Zdecydowaliśmy się na oficjalne narzędzie programistyczne do tworzenia bloków , ponieważ jest ono używane w podręczniku edytora bloków. Ale nawet jeśli zdecydujesz się skorzystać z narzędzia innej firmy, takiego jak create-guten-block , Twoje wrażenia nie będą się zbytnio różnić.

Powiedziawszy to, zagłębmy się głębiej w narzędzie do create-block .

Bliższe spojrzenie na narzędzie tworzenia bloków tworzenia bloków

Jak wspomnieliśmy powyżej, Utwórz blok jest oficjalnym narzędziem wiersza poleceń do tworzenia bloków Gutenberga. Uruchomienie @wordpress/create-block w terminalu generuje pliki PHP, JS i SCSS oraz kod potrzebny do zarejestrowania nowego typu bloku:

 npx @wordpress/create-block [options] [slug]

• [slug] (opcjonalne) — służy do przypisywania slug bloku i instalowania wtyczki
• [options] (opcjonalne) — dostępne opcje

Domyślnie przypisany jest szablon ESNext. Oznacza to, że otrzymasz następną wersję JavaScript, z dodatkiem składni JSX.

Jeśli pominiesz nazwę bloku, polecenie działa w trybie interaktywnym, umożliwiając dostosowanie kilku opcji przed wygenerowaniem plików:

 npx @wordpress/create-block

Poniższy obrazek pokazuje strukturę pliku wtyczki blokowej utworzonej za pomocą oficjalnego narzędzia Utwórz blok:

Mając to na uwadze, przejrzyjmy główne pliki i foldery naszej nowej wtyczki blokowej.

Plik wtyczki

Za pomocą głównego pliku wtyczki rejestrujesz blok na serwerze:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

Funkcja register_block_type rejestruje typ bloku na serwerze przy użyciu metadanych zapisanych w pliku block.json .

Funkcja przyjmuje dwa parametry:

• Nazwa typu bloku wraz z przestrzenią nazw lub ścieżka do folderu, w którym znajduje się plik block.json , lub kompletny obiekt WP_Block_Type
• Tablica argumentów typu blokowego

W powyższym kodzie argument typu bloku jest dostarczany przez magiczną stałą __DIR__ . Oznacza to, że plik block.json znajduje się w tym samym folderze co plik wtyczki.

Plik package.json

Plik package.json definiuje właściwości i skrypty JavaScript dla Twojego projektu. Tutaj możesz zainstalować zależności projektu.

Aby lepiej zrozumieć, do czego służy ten plik, otwórz go za pomocą ulubionego edytora kodu:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

Właściwość scripts to słownik zawierający polecenia, które są uruchamiane w różnych momentach cyklu życia pakietu przy użyciu npm run [cmd] .

W tym artykule będziemy używać następujących poleceń:

• npm run build — utwórz (skompresowaną) wersję produkcyjną
• npm run start — utwórz (nieskompresowany) build rozwojowy

dependencies i devDependencies to dwa obiekty mapujące nazwę pakietu na wersję. dependencies są wymagane w produkcji, podczas gdy devDependences są potrzebne tylko do lokalnego rozwoju (czytaj więcej).

Jedyną domyślną zależnością dewelopera jest pakiet @wordpress/scripts , który jest zdefiniowany jako „zbiór skryptów wielokrotnego użytku dostosowanych do programowania WordPress”.

Plik block.json

Począwszy od WordPress 5.8, plik metadanych block.json jest kanonicznym sposobem rejestrowania typów bloków.

Posiadanie pliku block.json zapewnia kilka korzyści, w tym lepszą wydajność i lepszą widoczność w katalogu wtyczek WordPress:

Z punktu widzenia wydajności, gdy motywy obsługują leniwe ładowanie zasobów, bloki zarejestrowane w block.json będą miały zoptymalizowane kolejkowanie zasobów. Zasoby CSS i JavaScript frontendu wymienione we właściwościach style lub script zostaną umieszczone w kolejce tylko wtedy, gdy blok będzie obecny na stronie, co spowoduje zmniejszenie rozmiarów strony.

Uruchomienie polecenia @wordpress/create-block generuje następujący plik block.json :

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Oto pełna lista domyślnych właściwości:

• apiVersion — wersja API używanego przez blok (aktualna wersja to 2)
• name — unikalny identyfikator bloku zawierający przestrzeń nazw
• version — aktualna wersja bloku
• title — wyświetlany tytuł bloku
• category — kategoria blokowa
• icon — ślimak Dashicon lub niestandardowa ikona SVG
• description — krótki opis widoczny w inspektorze bloku
• supports — zestaw opcji do sterowania funkcjami używanymi w edytorze
• textdomain — wtyczka text-domain
• editorScript — definicja skryptu edytora
• editorStyle — definicja stylu edytora
• style — udostępnia alternatywne style dla bloku

Oprócz właściwości wymienionych powyżej, możesz (i prawdopodobnie tak zrobisz) zdefiniować obiekt attributes dostarczający informacji o danych przechowywanych przez Twój blok. W swoim block.json możesz ustawić dowolną liczbę atrybutów w parach klucz/wartość , gdzie klucz jest nazwą atrybutu, a wartość jest definicją atrybutu.

Spójrz na następujący przykład definicji atrybutów:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

Zagłębimy się w plik block.json w dalszej części artykułu, ale możesz również sprawdzić Podręcznik edytora bloków, aby uzyskać bardziej szczegółowe informacje na temat metadanych i atrybutów block.json .

Folder src

Folder src to miejsce, w którym odbywa się rozwój. W tym folderze znajdziesz następujące pliki:

• index.js
• edit.js
• save.js
• edytor.scss
• styl.scss

index.js

Plik index.js jest Twoim punktem wyjścia. Tutaj zaimportujesz zależności i zarejestrujesz typ bloku na kliencie:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

Pierwsza instrukcja importuje funkcję registerBlockType z pakietu @wordpress/blocks . Poniższe instrukcje importu importują arkusz stylów wraz z funkcjami Edit i save .

Funkcja registerBlockType rejestruje komponent na kliencie. Funkcja przyjmuje dwa parametry: namespace/block-name (taka sama jak zarejestrowana na serwerze) oraz obiekt konfiguracji bloku.

Funkcja Edit zapewnia interfejs bloku renderowany w edytorze bloków, podczas gdy funkcja save zapewnia strukturę, która zostanie zserializowana i zapisana w bazie danych (czytaj więcej).

edit.js

edit.js to miejsce, w którym zbudujesz blokowy interfejs administratora:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Najpierw importuje funkcję __ z pakietu @wordpress/i18n (ten pakiet zawiera wersję JavaScript funkcji tłumaczących), hak useBlockProps React i plik editor.scss .

Następnie eksportuje komponent React (przeczytaj więcej o zestawieniach importu i eksportu).

save.js

W pliku save.js budujemy strukturę bloków do zapisania w bazie danych:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss i style.scss

Oprócz skryptów w folderach src znajdują się dwa pliki SASS. Plik editor.scss zawiera style zastosowane do bloku w kontekście edytora, podczas gdy plik style.scss zawiera style bloku do wyświetlenia w interfejsie użytkownika. Zagłębimy się w te pliki w drugiej części tego przewodnika.

Node_modules i foldery kompilacji

Folder node_modules zawiera moduły węzłów i ich zależności. Nie będziemy zagłębiać się w pakiety węzłów, ponieważ wykracza to poza zakres tego artykułu, ale możesz przeczytać więcej w tym artykule o tym, gdzie npm instaluje pakiety.

Folder build zawiera pliki JS i CSS wynikające z procesu kompilacji. Możesz zagłębić się w proces kompilacji w przewodnikach dotyczących składni ESNext i JavaScript Build Setup.

Projekt: Zbuduj swój pierwszy blok Gutenberg

Czas ubrudzić sobie ręce. W tej sekcji dowiesz się, jak stworzyć wtyczkę udostępniającą blok CTA o nazwie Affiliate Block.

Blok będzie składał się z dwóch kolumn, z obrazem po lewej stronie i akapitem tekstowym po prawej stronie. Pod tekstem zostanie umieszczony przycisk z konfigurowalnym linkiem:

To tylko prosty przykład, ale pozwala nam omówić podstawy tworzenia bloków Gutenberga. Po jasnym zrozumieniu podstaw możesz tworzyć coraz bardziej złożone bloki Gutenberga za pomocą Podręcznika edytora bloków i wszelkich innych dostępnych tam ogromnych zasobów.

Zakładając, że masz najnowszą wersję WordPressa działającą w lokalnym środowisku programistycznym, oto czego dowiesz się z tego miejsca:

• Jak skonfigurować wtyczkę startową?
• block.json w pracy
• Używanie wbudowanych komponentów: komponent RichText
• Dodawanie kontrolek do paska narzędzi bloku
• Dostosowywanie paska bocznego ustawień bloku
• Dodawanie i dostosowywanie zewnętrznego łącza
• Dodawanie wielu stylów bloków
• Zagnieżdżanie bloków z komponentem InnerBlocks
• Dodatkowe ulepszenia

Gotowi do startu start!

Jak skonfigurować wtyczkę startową?

Uruchom narzędzie wiersza poleceń i przejdź do folderu /wp-content/plugins :

Teraz uruchom następujące polecenie:

 npx @wordpress/create-block

To polecenie generuje pliki PHP, SCSS i JS do zarejestrowania bloku w trybie interaktywnym, umożliwiając łatwe dodanie niezbędnych danych do bloku. W naszym przykładzie użyjemy następujących szczegółów:

• Zablokuj slug : blok-moj-stowarzyszony
• Wewnętrzna przestrzeń nazw : my-affiliate-plugin
• Wyświetlany tytuł bloku: Blok partnerski
• Krótki opis bloku : Przykładowy blok dla czytelników Kinsta
• Dashicon : pieniądze
• Nazwa kategorii : projekt
• Autor wtyczki : Twoje imię i nazwisko
• Licencja : –
• Link do tekstu licencji : –
• Aktualna wersja wtyczki : 0.1.0

Instalacja wtyczki i wszystkich zależności zajmuje kilka minut. Po zakończeniu procesu zobaczysz następującą odpowiedź:

Teraz uruchom następujące polecenie z folderu /wp-content/plugins :

 cd my-affiliate-block

Na koniec, z poziomu folderu wtyczki (w naszym przykładzie my-affiliate-block ), możesz rozpocząć programowanie za pomocą:

 npm start

Teraz otwórz ekran wtyczek, aby znaleźć i aktywować wtyczkę Affiliate Block :

Utwórz nowy post, otwórz moduł wstawiania bloków i przewiń w dół do kategorii Projekt . Kliknij, aby dodać blok partnerski:

block.json w pracy

Jak wspomnieliśmy wcześniej, rejestracja bloku po stronie serwera odbywa się w głównym pliku .php . Nie będziemy jednak określać ustawień w pliku .php . Zamiast tego użyjemy pliku block.json .

Więc ponownie otwórz block.json i przyjrzyj się domyślnym ustawieniom:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Skrypty i style

editorScript , editorStyle i style zapewniają względne ścieżki do skryptów i stylów frontendu i backendu.

Nie musisz ręcznie rejestrować zdefiniowanych tutaj skryptów i stylów, ponieważ są one automatycznie rejestrowane i umieszczane w kolejce przez WordPress. Aby to udowodnić, uruchom inspektora przeglądarki i otwórz kartę Sieć :

Jak widać na powyższym obrazku, nasz skrypt index.js znajdujący się w folderze budowania jest regularnie umieszczany w kolejce bez konieczności dodawania kodu PHP .

Zapisz się do newslettera

Chcesz wiedzieć, jak zwiększyliśmy ruch o ponad 1000%?

Dołącz do ponad 20 000 innych osób, które otrzymują nasz cotygodniowy biuletyn z poufnymi wskazówkami dotyczącymi WordPressa!

Zapisz się teraz

Etykiety interfejsu użytkownika

Właściwości title i description zapewniają etykiety potrzebne do identyfikacji bloku w edytorze:

Słowa kluczowe

Jak wspomnieliśmy wcześniej, możesz dokładnie skonfigurować ustawienia bloku za pomocą właściwości i atrybutów. Na przykład możesz dodać jedno lub więcej keywords , aby ułatwić użytkownikom wyszukiwanie bloków:

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Localization

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Ten kod generuje statyczny blok z prostym, nieedytowalnym tekstem. Ale możemy to łatwo zmienić:

Aby umożliwić edycję tekstu, musisz zastąpić bieżący <p> komponentem, który umożliwia edycję treści wejściowej. W tym celu Gutenberg udostępnia wbudowany komponent RichText.

Dodanie wbudowanego komponentu do bloku to 5-etapowy proces:

1. Zaimportuj wymagane komponenty z pakietu WordPress
2. Dołącz odpowiednie elementy do swojego kodu JSX
3. Zdefiniuj niezbędne atrybuty w pliku block.json
4. Zdefiniuj obsługę zdarzeń
5. Zapisz dane

Krok 1: Importuj wymagane składniki z pakietu WordPress

Teraz otwórz plik edit.js i zmień następującą instrukcję import :

 import { useBlockProps } from '@wordpress/block-editor';

…do:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

W ten sposób importujesz funkcję useBlockProps i komponent RichText z pakietu @wordpress/block-editor .

użyjBlockProps

Hak useBlockProps React oznacza element opakowania bloku:

Korzystając z interfejsu API w wersji 2, należy użyć nowego zaczepu useBlockProps w funkcji edit bloku, aby oznaczyć element opakowania bloku. Hak wstawi atrybuty i programy obsługi zdarzeń potrzebne do włączenia zachowania blokowego. Wszelkie atrybuty, które chcesz przekazać do elementu block, muszą zostać przekazane przez useBlockProps , a zwrócona wartość zostanie rozłożona na element.

Mówiąc prościej, useBlockProps automatycznie przypisuje atrybuty i klasy do elementu wrappera (element p w naszym przykładzie):

Jeśli usuniesz useBlockProps z elementu wrappera, otrzymasz prosty ciąg tekstowy bez dostępu do funkcji i stylu blokowania:

Jak wyjaśnimy później, możesz również przekazać do useBlockProps obiekt właściwości, aby dostosować wyjście.

Tekst sformatowany

Komponent RichText zapewnia edytowalne dane wejściowe, umożliwiające użytkownikom edycję i formatowanie zawartości.

Udokumentowany komponent znajdziesz na GitHub w gutenberg/packages/block-editor/src/components/rich-text/README.md.

Krok 2: Dołącz odpowiednie elementy do swojego kodu JSX

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Skomentuj kod linijka po linijce:

• tagName — nazwa tagu edytowalnego elementu HTML
• onChange — funkcja wywoływana, gdy zmienia się zawartość elementu
• allowedFormats — tablica dozwolonych formatów. Domyślnie wszystkie formaty są dozwolone
• value — ciąg HTML, który ma być edytowalny
• placeholder — tekst zastępczy do pokazania, gdy element jest pusty

Krok 3: Zdefiniuj niezbędne atrybuty w pliku block.json

Atrybuty dostarczają informacji o danych przechowywanych przez blok, takich jak bogata zawartość, kolor tła, adresy URL itp.

Możesz ustawić dowolną liczbę atrybutów w obiekcie attributes w parach klucz/wartość, gdzie klucz to nazwa atrybutu, a wartość to definicja atrybutu.

Teraz otwórz plik block.json i dodaj następujące attributes prop:

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

Atrybut content pozwala na przechowywanie tekstu wpisanego przez użytkownika w polu edytowalnym:

• type wskazuje typ danych przechowywanych przez atrybut. Typ jest wymagany, chyba że zdefiniujesz właściwość enum .
• source określa, w jaki sposób wartość atrybutu jest wyodrębniana z treści posta. W naszym przykładzie jest to zawartość HTML. Pamiętaj, że jeśli nie podasz właściwości źródłowej, dane są przechowywane w ograniczniku bloku (czytaj więcej).
• selector to znacznik HTML lub dowolny inny selektor, taki jak nazwa klasy lub atrybut identyfikatora.

Funkcji Edit przekażemy obiekt o właściwościach. Wróć więc do pliku edit.js i wprowadź następującą zmianę:

 export default function Edit( { attributes, setAttributes } ) { ... }

Krok 4: Zdefiniuj programy obsługi zdarzeń

Element RichText ma atrybut onChange , udostępniający funkcję do wywołania, gdy zmieni się zawartość elementu.

Zdefiniujmy tę funkcję i zobaczmy cały skrypt edit.js :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Teraz zapisz plik i uruchom npm run start w oknie terminala. Następnie wróć do pulpitu WordPress, utwórz nowy post lub stronę i dodaj blok partnerski:

Dodaj tekst i przejdź do widoku kodu. Oto jak powinien wyglądać Twój kod:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Jeśli teraz zapiszesz stronę i sprawdzisz wynik frontendu, możesz być trochę rozczarowany, ponieważ Twoje zmiany nie wpływają na witrynę. Dzieje się tak, ponieważ musisz zmodyfikować plik save.js , aby przechowywać dane wejściowe użytkownika w bazie danych, gdy wpis jest zapisywany.

Krok 5: Zapisz dane

Teraz otwórz plik save.js i zmień skrypt w następujący sposób:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

To właśnie tutaj robimy:

• Zaimportuj składnik RichText z pakietu block-editor .
• Przekaż kilka właściwości przez argument obiektu do funkcji save (w tym przykładzie przekazujemy tylko właściwość attributes )
• Zwróć zawartość komponentu RichText

Możesz przeczytać więcej o komponencie RichText w Podręczniku edytora bloków i znaleźć pełną listę właściwości na Github.

Przejdźmy teraz o krok dalej. W następnej sekcji dowiesz się, jak dodawać kontrolki do paska narzędzi bloku.

Dodawanie kontrolek do paska narzędzi bloku

Pasek narzędzi bloku zawiera zestaw elementów sterujących umożliwiających użytkownikom manipulowanie częściami zawartości bloku. Dla każdej kontrolki paska narzędzi znajdziesz komponent:

Na przykład możesz dodać kontrolkę wyrównania tekstu do swojego bloku. Wystarczy zaimportować dwa komponenty z pakietu @wordpress/block-editor .

Przejdziemy przez te same kroki, co w poprzednim przykładzie:

1. Importuj wymagane komponenty z pakietów WordPress
2. Dołącz odpowiednie elementy do swojego kodu JSX
3. Zdefiniuj niezbędne atrybuty w pliku block.json
4. Zdefiniuj programy obsługi zdarzeń
5. Zapisz dane

Krok 1: Importuj BlockControls i AlignmentControl Components z @wordpress/block-editor

Aby dodać kontrolkę wyrównania do paska narzędzi bloku, potrzebne są dwa komponenty:

• BlockControls renderuje dynamiczny pasek narzędzi kontrolek (nieudokumentowane).
• AlignmentControl renderuje menu rozwijane, które wyświetla opcje wyrównania dla wybranego bloku (czytaj więcej)

Otwórz plik edit.js i edytuj instrukcję import , jak pokazano poniżej:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Krok 2: Dodaj BlockControls i AlignmentControl Elements

Przejdź do funkcji Edit i wstaw element <BlockControls /> na tym samym poziomie co <RichText /> . Następnie dodaj i <AlignmentControl /> w ramach <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

W powyższym kodzie <> i </> to krótka składnia do deklarowania fragmentów Reacta, dzięki którym zwracamy wiele elementów w React.

W tym przykładzie AlignmentControl ma dwa atrybuty:

• value zapewnia bieżącą wartość elementu
• onChange zapewnia obsługę zdarzeń do uruchomienia po zmianie wartości

Zdefiniowaliśmy również dodatkowe atrybuty dla elementu RichText (sprawdź pełną listę atrybutów wraz z przykładami)

Krok 3: Zdefiniuj atrybut align w block.json

Teraz przejdź do pliku block.json i dodaj atrybut align :

 "align": { "type": "string", "default": "none" }

Wróć do terminala, zatrzymaj bieżący proces za pomocą ^C i uruchom skrypt ponownie za pomocą npm run start . Następnie wróć do edytora bloków, odśwież stronę i wybierz blok. Powinieneś zobaczyć pasek narzędzi bloku z kontrolką wyrównania:

Teraz, jeśli spróbujesz sformatować zawartość bloku za pomocą nowych kontrolek wyrównania, zobaczysz, że nic się nie dzieje. Dzieje się tak, ponieważ nie zdefiniowaliśmy jeszcze obsługi zdarzeń.

Krok 4: Zdefiniuj programy obsługi zdarzeń

Teraz zdefiniuj onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Jeśli newAlign jest undefined , ustawiamy newAlign na none . W przeciwnym razie używamy newAlign .

Nasz skrypt edit.js powinien być kompletny (na razie):

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Teraz możesz wrócić do edytora i wyrównać zawartość bloku.

Musimy zmodyfikować funkcję zapisywania, aby przechowywać zawartość bloku i atrybuty w bazie danych.

Krok 5: Zapisz dane

Otwórz save.js i zmień funkcję save w następujący sposób:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Na koniec, aby uczynić kod bardziej czytelnym, możesz wyodrębnić poszczególne właściwości z obiektu attribute przy użyciu składni przypisania destrukturyzującego:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Zapisz plik, zrestartuj proces i wróć do edytora w trybie edytora kodu. Kod powinien wyglądać mniej więcej tak:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

I to wszystko! Właśnie dodałeś kontrolkę wyrównania do paska narzędzi bloku

Więcej informacji na temat elementów sterujących paska narzędzi bloku można znaleźć w Podręczniku edytora bloku.

Dostosowywanie paska bocznego ustawień bloku

Możesz także dodać kontrolki do paska bocznego ustawień bloku (lub nawet utworzyć nowy pasek boczny dla swojej aplikacji).

API zapewnia do tego komponent InspectorControls .

Podręcznik edytora bloków wyjaśnia, jak korzystać z paska bocznego ustawień:

Pasek boczny ustawień służy do wyświetlania rzadziej używanych ustawień lub ustawień, które wymagają więcej miejsca na ekranie. Pasek boczny Ustawienia powinien być używany tylko do ustawień na poziomie bloku .

Jeśli masz ustawienia, które mają wpływ tylko na wybraną zawartość w bloku (na przykład: ustawienie „pogrubienia” dla zaznaczonego tekstu w akapicie): nie umieszczaj ich na pasku bocznym ustawień. Pasek boczny ustawień jest wyświetlany nawet podczas edycji bloku w trybie HTML, więc powinien zawierać tylko ustawienia na poziomie bloku.

Ponownie:

1. Importuj wymagane komponenty z pakietów WordPress
2. Dołącz odpowiednie elementy do swojego kodu JSX
3. Zdefiniuj niezbędne atrybuty w pliku block.json
4. Zdefiniuj programy obsługi zdarzeń
5. Zapisz dane

Krok 1. Importuj składniki InspectorControls i PanelColorSettings z @wordpress/block-editor

Możesz dodać kilka kontrolek, aby umożliwić użytkownikom dostosowanie określonych aspektów bloku. Na przykład możesz udostępnić kolorowy panel sterowania. Aby to zrobić, musisz zaimportować składniki InspectorControls i PanelColorSettings z modułu block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Krok 2: Dołącz odpowiednie elementy do swojego kodu JSX

Teraz możesz dodać odpowiednie elementy do JSX zwróconego przez funkcję Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Zauważ, że zaktualizowaliśmy również atrybut style elementu RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Krok 3: Zdefiniuj niezbędne atrybuty w block.json

Teraz zdefiniuj atrybuty backgroundColor i textColor w pliku block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Krok 4: Zdefiniuj programy obsługi zdarzeń

Teraz musisz zdefiniować dwie funkcje, aby zaktualizować backgroundColor i textColor podczas wprowadzania danych przez użytkownika:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Krok 5: Zapisz dane

Ostatni krok: Otwórz plik save.js i zmień skrypt w następujący sposób:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Teraz zatrzymaj proces (^C) i uruchom ponownie npm run start . Odśwież stronę, usuń dowolne wystąpienie swojego bloku i dodaj go ponownie do swojego postu:

Wprowadź zmiany, zapisz post i wyświetl go w interfejsie użytkownika. Zmiany wprowadzone w edytorze bloków powinny zostać odzwierciedlone na pierwszej stronie.

Dodawanie i dostosowywanie zewnętrznego łącza

W tej sekcji dodasz nowe komponenty do typu bloku:

• Komponent ExternalLink umożliwiający użytkownikom dodawanie konfigurowalnego linku do bloku afiliacyjnego
• Kilka elementów sterujących paska bocznego umożliwiających użytkownikom dostosowanie ustawień linków

Krok 1. Importuj komponenty z @wordpress/components

Teraz musisz zaimportować kilka komponentów z @wordpress/components . Otwórz plik edit.js i dodaj następującą instrukcję import :

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody dodaje zwijany kontener do paska bocznego ustawień.
• PaneRow tworzy ogólny kontener dla kontrolek paska bocznego.
• TextControl zapewnia kontrolkę wprowadzania tekstu.
• ToggleControl zapewnia przełącznik umożliwiający użytkownikom włączenie/wyłączenie określonej opcji
• ExternalLink to prosty komponent do dodawania zewnętrznego linku.

Krok 2. Dołącz odpowiednie elementy do swojego kodu JSX

Najpierw dodasz element ExternalLink na tym samym poziomie RichText w kontenerze div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

Komponent ExternalLink nie jest udokumentowany, więc odwołaliśmy się do samego komponentu, aby uzyskać listę dostępnych atrybutów. Tutaj używamy atrybutów href , className i rel .

Domyślnie wartość atrybutu rel jest ustawiona na noopener noreferrer . Nasz kod doda słowo kluczowe nofollow do atrybutu rel wynikowego tagu a gdy kontrolka przełączania jest włączona .

Teraz możesz dodać ustawienia linków do paska bocznego bloku.

Najpierw dodasz element PanelBody wewnątrz InspectorControls na tym samym poziomie co PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Oto, co z tym robimy:

1. Atrybut title zapewnia tytuł panelu.
2. initialOpen określa, czy panel jest początkowo otwarty.

Następnie dodamy dwa elementy PanelRow wewnątrz PanelBody i element TextControl wewnątrz każdego PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

Powyższy kod powinien teraz wyglądać całkiem prosto. Dwie kontrolki tekstowe pozwalają użytkownikom ustawić etykietę linku i adres URL.

Dodamy również dodatkowy PanelRow z ToggleControl , aby włączyć/wyłączyć określoną opcję, na przykład czy dołączyć atrybut, czy nie:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Krok 3: Zdefiniuj niezbędne atrybuty w block.json

Teraz zdefiniuj atrybuty affiliateLink , linkLabel i hasLinkNofollow w pliku block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

Nic więcej do dodania! Przejdźmy do definiowania funkcji obsługi zdarzeń.

Krok 4: Zdefiniuj programy obsługi zdarzeń

Wróć do pliku edit.js i dodaj następujące funkcje:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Te funkcje aktualizują odpowiednie wartości atrybutów po wprowadzeniu przez użytkownika.

Krok 5: Zapisz dane

Na koniec musimy zaktualizować funkcję save w save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Zauważ, że tutaj użyliśmy zwykłego elementu a zamiast ExternalLink :

Teraz zapisz dane i zrestartuj swoje środowisko.

Dodawanie wielu stylów bloków

W poprzedniej sekcji dowiedziałeś się, jak dodać blokową kontrolkę paska narzędzi, umożliwiającą użytkownikom wyrównanie danych wprowadzanych przez użytkownika. Do paska narzędziowego bloku możemy dodać więcej elementów sterujących stylami, ale możemy również zapewnić zestaw predefiniowanych stylów bloków, z których użytkownik może wybierać za pomocą jednego kliknięcia.

W tym celu użyjemy przydatnej funkcji API Bloku: Style blokowe.

Wszystko, co musisz zrobić, to zdefiniować właściwość styles block.json i zadeklarować odpowiednie style w swoich arkuszach stylów.

Na przykład możesz dodać następującą tablicę stylów:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

Dzięki temu właśnie dodałeś styl domyślny i dodatkowy styl o nazwie border . Teraz wróć do edytora bloków:

Style będą dostępne dla użytkownika po kliknięciu przełącznika bloków, a następnie wyszukaniu panelu Style na pasku bocznym Ustawienia blokowania .

Wybierz styl i sprawdź klasy zastosowane do elementu p . Kliknij prawym przyciskiem myszy blok i Sprawdź . Dodano nową klasę o nazwie o następującej strukturze:

 is-style-{style-name}

Jeśli zaznaczyłeś styl „Border”, to do elementu p zostanie dodana klasa is-style-border . Jeśli zaznaczysz styl „Domyślny”, zamiast tego zostanie dodana klasa is-style-default .

Teraz wystarczy zadeklarować właściwości CSS. Otwórz plik editor.scss i zastąp aktualne style następującymi:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Teraz możesz zrobić to samo z style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Zatrzymaj proces (^C) i uruchom ponownie npm run start .

I to wszystko! Odśwież stronę i baw się nowymi stylami bloków:

Zagnieżdżanie bloków Gutenberga za pomocą komponentu InnerBlocks

Chociaż w pełni funkcjonalny, nasz blok partnerski nadal nie jest zbyt atrakcyjny. Aby było bardziej angażować odbiorców, moglibyśmy dodać obraz.

Może to dodać warstwę złożoności do naszego bloku, ale na szczęście nie musisz wymyślać koła na nowo, ponieważ Gutenberg zapewnia konkretny komponent, którego możesz użyć do stworzenia struktury zagnieżdżonych bloków.

Składnik InnerBlocks jest zdefiniowany w następujący sposób:

InnerBlocks eksportuje parę komponentów, których można użyć w implementacjach blokowych, aby włączyć zagnieżdżoną zawartość bloków.

Najpierw musisz utworzyć nowy plik .js w folderze src . W naszym przykładzie nazwiemy ten plik container.js .

Teraz musisz zaimportować nowy zasób do pliku index.js :

 import './container';

Wróć do pliku container.js i zaimportuj niezbędne komponenty:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

Kolejnym krokiem jest zdefiniowanie szablonu określającego strukturę, w której zostaną umieszczone bloki. W poniższym przykładzie definiujemy szablon składający się z dwóch kolumn zawierających podstawowy blok obrazu i nasz niestandardowy blok Affiliate:

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

Szablon ma strukturę tablicy blockTypes (nazwa bloku i opcjonalne atrybuty).

W powyższym kodzie użyliśmy kilku atrybutów do skonfigurowania bloków kolumn i kolumn. W szczególności atrybut templateLock: 'all' blokuje bloki kolumn, dzięki czemu użytkownik nie dodaje, nie zmienia kolejności ani nie usuwa istniejących bloków. templateLock może przyjąć jedną z następujących wartości:

• all — InnerBlocks jest zablokowany i nie można dodawać, zmieniać kolejności ani usuwać żadnych bloków.
• insert — Bloki można tylko zmieniać lub usuwać.
• false — Szablon nie jest zablokowany.

Szablon jest następnie przypisywany do elementu InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Aby zapobiec wszelkim problemom ze zgodnością, dodaliśmy również atrybut templateLock do składnika InnerBlocks (zobacz także problem #17262 i pull #26128).

Oto nasz ostateczny plik container.js :

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Dodatkowe ulepszenia

Nasz blok jest w pełni funkcjonalny, ale możemy go nieco ulepszyć, wprowadzając drobne zmiany.

Przypisaliśmy atrybut backgroundColor do akapitu wygenerowanego przez komponent RichText . Możemy jednak preferować przypisanie koloru tła do kontenera div :

Zmień więc plik edit.js i div div.js w następujący sposób:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Umożliwi to użytkownikowi zmianę tła całego bloku.

Z drugiej strony bardziej istotna zmiana dotyczy metody useBlockProps . W oryginalnym kodzie zdefiniowaliśmy stałą blockProps w następujący sposób:

 const blockProps = useBlockProps();

Ale możemy użyć useBlockProps efektywniej przekazując zestaw właściwości. Na przykład możemy zaimportować nazwy classnames z modułu classnames klas i odpowiednio ustawić nazwę klasy opakowującej.

W poniższym przykładzie przypisujemy nazwę klasy na podstawie wartości atrybutu align ( edit.js ):

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Tę samą zmianę wprowadzimy w pliku save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

I to jest okład! Możesz teraz uruchomić kompilację do produkcji.

Streszczenie

I oto jesteśmy na końcu tej niesamowitej podróży! Zaczęliśmy od konfiguracji środowiska programistycznego, a skończyliśmy na stworzeniu kompletnego typu bloku.

Jak wspomnieliśmy we wstępie, solidna znajomość Node.js, Webpack, Babel i React jest niezbędna do tworzenia zaawansowanych bloków Gutenberga i pozycjonowania się na rynku jako profesjonalny programista Gutenberg.

Ale nie musisz mieć doświadczenia z React, aby zacząć bawić się tworzeniem bloków. Rozwój bloków może dać Ci motywację i cele do zdobycia coraz szerszych umiejętności w zakresie technologii stojących za blokami Gutenberga.

Dlatego ten przewodnik jest daleki od ukończenia. To tylko wprowadzenie do szerokiej gamy tematów, które pomogą Ci zacząć budować swoje pierwsze klocki Gutenberga.

Z tego powodu zalecamy pogłębienie swojej wiedzy poprzez uważne przeczytanie dokumentacji i poradników online. Wśród wielu dostępnych zasobów zalecamy następujące:

• Oficjalny samouczek tworzenia bloku dla początkujących
• Oficjalny samouczek blokowy dla średnio zaawansowanych programistów
• Bloki dynamiczne
• Meta Pudełka
• Tworzenie paska bocznego dla Twojej wtyczki

Jeśli dopiero zaczynasz z programowaniem WordPress, możesz chcieć zrozumieć podstawowe pojęcia programowania frontendowego. Oto krótka lista zasobów, które mogą pomóc w rozpoczęciu pracy:

• Jak zainstalować WordPress lokalnie (bezpłatny ebook)
• Prawdziwa wartość zarządzanego hostingu WordPress (bezpłatny ebook)
• Co to jest JavaScript?
• HTML a HTML5
• Jak edytować CSS w WordPress
• Co to jest PHP?
• Bootcamp WordPress Hooks: Jak korzystać z akcji, filtrów i niestandardowych hooków

I pamiętaj, że pełny kod przykładów tego przewodnika jest dostępny na Gist.

Teraz twoja kolej: czy opracowałeś jakieś klocki Gutenberga? Jakie są główne trudności, których do tej pory doświadczyłeś? Daj nam znać o swoim doświadczeniu w komentarzach!