W tym poście spróbuję stworzyć przegląd tworzenia niestandardowych punktów końcowych API REST i wykonywania żądań dla nich w niestandardowym bloku Gutenberga. Oznacza to wysyłanie żądań za pomocą fetchmetod informacji niedostępnych w zarejestrowanych magazynach danych WordPressa.
Przyjazne przypomnienie: większość podstawowych informacji jest już dostępna w magazynach danych WordPressa. Na przykład podstawowe zapytania dotyczące postów, stron, niestandardowych typów postów, taksonomii, autorów, mediów i innych są dostępne bez konieczności tworzenia własnych niestandardowych punktów końcowych. Aby uzyskać dostęp do tych sklepów, wolałbyś użyć podstawowego modułu danych WordPress (withSelecti select()). Poniżej znajduje się samouczek, który szczegółowo wyjaśnia, jak to zrobić.
WordPress REST API
Jeśli jeszcze nie wiedziałeś; WordPress REST API to interfejs JSON do wysyłania i odbierania danych z Twojej witryny WordPress. Może być używany zewnętrznie lub wewnętrznie. Dzięki edytorowi Gutenberg i przejściu na Javascript zdecydowanie wzrosło wykorzystanie REST API. WordPress REST API ma całą masę punktów końcowych, z których możemy korzystać. Zobacz pełne informacje na temat wszystkich punktów końcowych interfejsu API REST tutaj. Znajdziesz na przykład punkty końcowe dla postów i większość innych treści wewnętrznych – zarówno do czytania, jak i aktualizacji. Twórcy motywów lub wtyczek mogą rejestrować własne niestandardowe punkty końcowe.
Twoja witryna WordPress ma główny adres URL interfejsu API REST, domyślnie zlokalizowany pod adresem <your domain>/wp-json. Na przykład lokalny WordPress z adresem URL http://localhost/wordpress/może uzyskać dostęp do REST API pod adresem http://localhost/wordpress/wp-json. Stamtąd musimy dołączyć punkty końcowe. Odnosząc się do powyższego odniesienia do punktów końcowych, możemy pobrać listę najnowszych postów w punkcie końcowym /wp/v2/posts. Oznacza to, że jeśli przejdziesz do http://localhost/wordpress/wp-json/wp/v2/postsw przeglądarce, otrzymasz odpowiedź w formacie JSON na najnowsze posty w Twojej witrynie WordPress.
Uwaga dotycząca przestrzeni nazw jest w porządku. Adres URL interfejsu API REST zaczyna się od przestrzeni nazw (przestrzeń nazw wp/v2„ to WordPress", jak widać w przykładowych adresach URL powyżej). Przestrzenie nazw to koncepcja mająca na celu uniknięcie kolizji w podstawowym WordPressie, motywach i wtyczkach dodających punkty końcowe o tej samej nazwie. Stwórz swoją własną unikalną przestrzeń nazw — zazwyczaj formę ślimaka swojego motywu lub nazwy wtyczki. Po slugu ogólną zasadą jest dodawanie numeru wersji, zwykle zaczynając od v1. Jako przykład slug mojego motywu to „ awhitepixel“, więc gdybym miał utworzyć niestandardowe punkty końcowe w moim motywie, użyłbym przestrzeni nazw „ awhitepixel/v1“. Dzięki tej przestrzeni nazw mogłem zarejestrować punkt końcowy „ posts” i nie spowodowałoby to żadnych problemów, mimo że jest identyczny z nazwą punktu końcowego WordPressa.
Praca z REST API w WordPressie to obszerny temat, na którym dostępnych jest wiele dobrych informacji. W tym poście skupiam się na użyteczności w edytorze Gutenberg i jak je odzyskać w JavaScript.
Co zrobimy i czego potrzebujemy
Użyteczność żądania informacji niestandardowych ma szeroki zakres zastosowań, więc zwykle musisz dostosować poniższe przykłady kodu do swoich potrzeb. Dane mogą być niestandardowym zapytaniem post, niestandardowym zapytaniem SQL lub czymś zupełnie innym.
Kiedy tworzymy niestandardowy punkt końcowy, mamy pełną kontrolę nad jego zwrotem. Możemy wykonywać dowolne operacje i zapytania w WordPress/PHP i przekazywać je dalej jako JSON. A w naszym bloku Gutenberga będziemy mogli pobrać ten zwrot i zrobić z nim, co chcemy, w ramach funkcji bloku edit. Zazwyczaj używa się danych do przedstawienia użytkownikowi końcowemu wyboru lub informacji w edytorze bloków, ale można również przechowywać informacje z nich w bloku do dalszego wykorzystania. Możesz także tworzyć własne niestandardowe sklepy dla tych danych, ale nie będę się zastanawiał, jak to zrobić.
Zakładam, że wiesz już, jak tworzyć niestandardowe bloki Gutenberga, więc nie będę omawiał tego szczegółowo tutaj.
Tworzenie punktu końcowego REST API
Rejestracja niestandardowego punktu końcowego REST API odbywa się w PHP. Możesz dodać ten kod w swoim motywie functions.phplub w kodzie aktywnej wtyczki. Podłącz funkcję do action rest_api_initi uruchom funkcję [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()dla każdego punktu końcowego, który chcesz zarejestrować.
Podaj swoją przestrzeń nazw jako pierwszy parametr, trasę punktu końcowego jako drugi i tablicę ustawień jako trzeci parametr do register_rest_route(). Czwarty parametr określa, czy chcesz zastąpić istniejącą trasę; nie coś, na co tu przyjrzymy. W tablicy dla trzeciego parametru należy jako minimum ustawić właściwość ‘ callback‘ na funkcję, która jest odpowiedzialna za zwracanie danych punktu końcowego. methodPowszechne jest również ustawienie „ “, np. ustawienie punktu końcowego na „ ” GET, „ POST“, „ PUT” itd.
Zacznijmy od zarejestrowania prostego punktu końcowego;
Przestrzeń nazw mojego motywu to „ awhitepixel/v1” i rejestruję punkt końcowy „ mydata” w tej przestrzeni nazw. Oznacza to, że mogę uzyskać dostęp do mojego niestandardowego interfejsu API REST pod adresem http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
Rejestrując (lub zmieniając) trasy REST API, musisz usunąć swoje permalinki, aby działały. Możesz to zrobić, odwiedzając Ustawienia> Permalinki i po prostu kliknij Zapisz.
Powyższy kod jeszcze nie działa, ponieważ nie zdefiniowałem funkcji ustawionej jako callback: awhitepixel_rest_route_mydata. Funkcja callback otrzymuje jeden parametr; tablica danych z informacjami i argumentami przekazanymi z żądania. Na koniec musisz dokładnie rozważyć zwrot funkcji zwrotnej.
Po pierwsze, zawsze musisz zwrócić coś z wywołania zwrotnego punktu końcowego. Każdy zwrot zostanie automatycznie przekonwertowany do formatu JSON przez WordPress. Oznacza to, że możesz zwrócić praktycznie każdą formę danych w swojej funkcji; ciąg, null, tablica lub [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)instancja. Możesz również zdecydować się na zwrócenie [WP_REST_Response](https://developer.wordpress.org/reference/classes/wp_rest_response/)obiektu, aby uzyskać większą kontrolę nad np. kodem stanu lub informacjami nagłówka. Zalecam zawinięcie zwrotu w funkcję, [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()aby upewnić się, że Twoja odpowiedź jest prawidłową odpowiedzią REST.
Zdefiniujmy naszą funkcję zwrotną i jako początek zwróćmy prosty ciąg znaków;
function awhitepixel_rest_route_mydata($data) {
$response = 'Hello there!';
return rest_ensure_response($response);
}Za pomocą powyższego kodu (i opróżnionych permalinków) mogę teraz przejść do adresu URL http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
Od tego momentu możemy dodać dowolny kod w naszej funkcji zwrotnej, aby wygenerować odpowiednie dane do zwrócenia. Możesz wysyłać zapytania do treści WordPress za pomocą np [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)., tworzyć zapytania w bazie danych lub żądać danych zewnętrznych. Ta część zależy od Ciebie.
Przejdźmy teraz na przeciwną stronę; jak składać wnioski.
Wykonywanie żądań REST API w JavaScript
Wykonywanie żądania REST jest zwykle wykonywane przy użyciu [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)JavaScript. WordPress zapewnia własne opakowanie fetch, które upraszcza żądania WordPress REST API; [wp.apiFetch](https://developer.wordpress.org/block-editor/packages/packages-api-fetch/). To jest to, czego użyję w moim niestandardowym bloku Gutenberga. Należy pamiętać, że fetchżądania zwracają „obietnicę” – więc musimy powiązać a .then(), aby obsłużyć rzeczywisty zwrot żądania. Podstawowe użycie jest mniej więcej takie;
apiFetchpozwala nam dostarczyć pathwłaściwość zamiast budować pełny adres URL. Wszystko, co musimy podać, to przestrzeń nazw i punkt końcowy, a my apiFetchdołączymy to do głównego adresu URL interfejsu API REST WordPressa. Wewnątrz .then()funkcji mamy dostęp do danych, które są już przekonwertowane na JSON. To tutaj zrobisz coś z danymi. Zwykle zwrócone dane przechowujesz np. w stanie komponentu.
Poniżej znajduje się przykład niestandardowego editkomponentu bloku Gutenberga. Jest oparty na klasach w celu stateprzechowywania zwróconych danych z żądania REST API. Pozwala nam to również na uruchomienie żądania componentDidMount()przy pierwszym montowaniu (zobacz dokumentację React na temat metod cyklu życia ). Wszystko to stanowi prosty przykład, który pomoże ci zrozumieć podstawową koncepcję; nie jako przepis na zrobienie tego dokładnie w ten sposób. Możesz rozważyć użycie haków React i komponentów funkcjonalnych lub zamiast tego skonstruować komponent wyższego rzędu .
Powyższy przykład jest składem opartym na klasach, który jest dostarczany do funkcji bloku editw registerBlockType(). Ustawia obiekt stanu tablicy do przechowywania danych (oczywiście zależy to od zwracanych danych) oraz wartość logiczną stanu, aby wiedzieć, kiedy żądanie asynchroniczne zostało zwrócone. Po zamontowaniu komponentu (wyrenderowaniu po raz pierwszy) uruchamia funkcję wykonującą apiFetchżądanie. Ustawiamy ścieżkę do punktu końcowego, który zarejestrowaliśmy w PHP powyżej. Metodą jest domyślnie GET, więc nie musimy tego określać w apiFetch. A wewnątrz .then()funkcji, gdy żądanie jest gotowe, aktualizujemy stan komponentu o zwrócone dane.
Oczywiście funkcja renderowania twojego bloku zrobiłaby więcej z samymi zwróconymi danymi. Możesz chcieć przekazać dane użytkownikowi, przedstawiając w jakiś sposób listę do wyboru. Wszystko zależy od tego, jakie to dane i do czego chcesz je wykorzystać.
Przekazywanie argumentów do punktu końcowego
W niektórych przypadkach musimy przekazać pewne argumenty do punktu końcowego. Typowe zastosowania to przekazywanie identyfikatora po punkcie końcowym; na przykład http://localhost/wordpress/wp-json/wp/v2/posts/14zwróci identyfikator postu 14.
Jest to dość proste i odbywa się poprzez dodanie wzorca wyszukiwania wyrażeń regularnych do punktu końcowego podczas jego rejestracji. Budowa złożonych wzorców wymaga pewnej znajomości wyrażeń regularnych, ale poniżej znajduje się przykład, który pasuje do liczby i przypisuje jej nazwę „id”. Nazywanie dopasowań daje nam dostęp do zmiennej w naszej funkcji zwrotnej. Pokażę ci, co mam na myśli.
Zarejestrujmy nową trasę punktu końcowego. Używamy tego samego punktu końcowego, co wcześniej (‘ awhitepixel/v1/mydata‘), ale dla tej trasy dodajemy na końcu dopasowanie wyrażenia regularnego dla liczby.
Wzór regex (?P<id>[d]+)wydaje się tajemniczy, ale będzie dość jasny przy pewnym podstawowym zrozumieniu wyrażenia regularnego. Część [d]+pasuje do dowolnej liczby (0-9) 1 lub więcej razy. Części (?P<id>i )służą do dopasowywania nazwanej grupy. Nazwa grupy to w tym przypadku id, ale możesz nazwać swoją grupę (grupy) w dowolny sposób.
Możesz skierować ten punkt końcowy do oddzielnej funkcji zwrotnej, ale wybrałem tę samą funkcję do obsługi zarówno żądań, jak /mydatai /mydata/<ID>żądań. Oznacza to, że w mojej funkcji zwrotnej mogę wykonać:
function awhitepixel_rest_route_mydata($data) {
if ($data['id']) {
$response = 'Create return for ID: '. $data['id'];
} else {
$response = 'Create general return (no ID provided)';
}
return rest_ensure_response($response);
}Pamiętaj, że parametr funkcji zwrotnej zawiera zwrócone argumenty. Ponieważ nazwałem moją dopasowaną grupę „ id“, dopasowana wartość będzie dostępna w programie $data['id']. I wreszcie, ponieważ używam tej samej funkcji do obsługi żądań z identyfikatorem i bez, mogę łatwo przełączać się między dwoma różnymi zwrotami.
Dzięki temu (i odświeżonym permalinkom) otrzymam te odpowiedzi dla moich niestandardowych punktów końcowych:
