В этом посте я попытаюсь создать обзор того, как создавать пользовательские конечные точки REST API и выполнять запросы для них в пользовательском блоке Gutenberg. То есть выполнение запросов с помощью fetchметодов для получения информации, недоступной в зарегистрированных хранилищах данных WordPress.
Дружеское напоминание: основная информация уже доступна в хранилищах данных WordPress. Например, базовые запросы к сообщениям, страницам, пользовательским типам сообщений, таксономиям, авторам, медиа и т. д. доступны как есть без необходимости создавать собственные настраиваемые конечные точки. Чтобы получить доступ к этим магазинам, лучше использовать модуль данных ядра WordPress (withSelectи select()). Ниже приведена обучающая часть, в которой подробно рассказывается, как это сделать.
WordPress REST-API
Если вы еще не знали; WordPress REST API — это интерфейс JSON для отправки и получения данных с вашего сайта WordPress. Его можно использовать наружно или внутрь. С редактором Gutenberg и переходом на Javascript использование REST API определенно увеличилось. WordPress REST API имеет целую кучу конечных точек, которые мы можем использовать. Полный справочник по всем конечным точкам REST API смотрите здесь. Например, вы найдете конечные точки для сообщений и большей части другого внутреннего контента — как для чтения, так и для обновления. Разработчики тем или плагинов могут зарегистрировать свои собственные конечные точки.
Ваш сайт WordPress имеет корневой URL-адрес REST API, который по умолчанию находится по адресу <your domain>/wp-json. Например, локальный WordPress с URL-адресом http://localhost/wordpress/может получить доступ к REST API по адресу http://localhost/wordpress/wp-json. Оттуда нам нужно добавить конечные точки. Ссылаясь на приведенную выше ссылку на конечные точки, мы можем получить список последних сообщений в конечной точке /wp/v2/posts. Это означает, что если вы перейдете http://localhost/wordpress/wp-json/wp/v2/postsв своем браузере, вы получите ответ в формате JSON с последними сообщениями на вашем сайте WordPress.
Заметка о пространствах имен в порядке. URL-адрес REST API начинается с пространства имен (« wp/v2» — это пространство имен WordPress, как показано в приведенных выше примерах URL-адресов). Пространства имен — это концепция, позволяющая избежать конфликтов в ядре WordPress, темах и плагинах, добавляющих конечные точки с одинаковыми именами. Создайте свое собственное уникальное пространство имен — обычно это краткая форма имени вашей темы или плагина. Общее правило заключается в том, что после слага добавляется номер версии, обычно начиная с v1. Например, слаг моей темы — ‘ awhitepixel‘, поэтому, если бы мне нужно было создать пользовательские конечные точки в моей теме, я бы использовал пространство имен ‘ awhitepixel/v1‘. С этим пространством имен я мог бы зарегистрировать конечную точку ‘ posts‘, и это не вызвало бы проблем, даже если оно идентично имени конечной точки WordPress.
Работа с REST API в WordPress — это обширная тема, в которой доступно много полезной информации. В этом посте я сосредоточусь на удобстве использования редактора Gutenberg и на том, как получить их в Javascript.
Что мы будем делать и что нам нужно
Удобство использования для запроса пользовательской информации имеет широкий спектр вариантов использования, поэтому вам обычно нужно настроить приведенные ниже примеры кода в соответствии со своими потребностями. Данные могут быть настраиваемым почтовым запросом, настраиваемым SQL-запросом или чем-то совершенно другим.
Когда мы создаем пользовательскую конечную точку, мы полностью контролируем ее возврат. Мы можем выполнять любые операции и запросы в WordPress/PHP и передавать их в виде JSON. И в нашем блоке Гутенберга мы сможем получить этот возврат и делать с ним, что захотим, внутри функции блока edit. Обычно вы используете данные, чтобы предоставить конечному пользователю выбор или информацию в редакторе блоков, но вы также можете сохранить информацию из них в своем блоке для дальнейшего использования. Вы также можете создавать свои собственные хранилища для этих данных, но я не буду вдаваться в подробности того, как это сделать.
Я предполагаю, что вы уже знакомы с тем, как создавать собственные блоки Гутенберга, поэтому я не буду подробно описывать это здесь.
Создание конечной точки REST API
Регистрация пользовательской конечной точки REST API выполняется в PHP. Вы должны добавить этот код в свою тему functions.phpили активный код плагина. Подключите функцию к действию rest_api_initи запустите функцию [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()для каждой конечной точки, которую вы хотите зарегистрировать.
Укажите свое пространство имен в качестве первого параметра, маршрут конечной точки в качестве второго и массив настроек в качестве третьего параметра для register_rest_route(). Четвертый параметр определяет, хотите ли вы переопределить существующий маршрут; не то, что мы будем смотреть на здесь. В массиве для третьего параметра вы должны как минимум установить свойство ‘ callback‘ на функцию, которая отвечает за возврат данных конечной точки. Также распространена установка ‘ method‘, например, установка конечной точки на ‘ GET‘, ‘ POST‘, ‘ PUT‘ и т. д.
Начнем с регистрации простой конечной точки;
Пространство имен моей темы ‘ awhitepixel/v1‘, и я регистрирую конечную точку ‘ mydata‘ в этом пространстве имен. Это означает, что я могу получить доступ к своему пользовательскому REST API по адресу http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
При регистрации (или изменении) маршрутов REST API вам нужно будет сбросить ваши постоянные ссылки, чтобы он работал. Вы можете сделать это, посетив «Настройки» > «Постоянные ссылки» и просто нажав «Сохранить».
Приведенный выше код еще не работает, потому что я не определил набор функций как callback: awhitepixel_rest_route_mydata. Функция обратного вызова получает один параметр; массив данных с информацией и аргументами, переданными из запроса. Наконец, вам нужно тщательно рассмотреть возврат вашей функции обратного вызова.
Во-первых, вы всегда должны возвращать что-то из обратного вызова вашей конечной точки. Любой возврат будет автоматически преобразован WordPress в JSON. Это означает, что вы можете возвращать практически любую форму данных в своей функции; строка, нуль, массив или [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)экземпляр. Вы также можете выбрать возврат [WP_REST_Response](https://developer.wordpress.org/reference/classes/wp_rest_response/)объекта для большего контроля, например, кода состояния или информации заголовка. Я рекомендую обернуть возврат в функцию [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)(), чтобы убедиться, что ваш ответ является допустимым ответом REST.
Давайте определим нашу функцию обратного вызова и вернем простую строку в качестве начала;
function awhitepixel_rest_route_mydata($data) {
$response = 'Hello there!';
return rest_ensure_response($response);
}С приведенным выше кодом (и очищенными постоянными ссылками) теперь я могу перейти по URL-адресу http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
С этого момента мы можем добавить любой код в нашу функцию обратного вызова, чтобы сгенерировать правильные данные для возврата. Вы можете запрашивать контент WordPress, например [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/), делать запросы в базе данных или запрашивать внешние данные. Эта часть зависит от вас.
Теперь давайте перейдем к противоположной стороне; как делать запросы.
Выполнение запросов REST API в Javascript
Выполнение запроса REST обычно выполняется с использованием [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)Javascript. WordPress предоставляет собственную оболочку fetch, которая упрощает запросы WordPress REST API; [wp.apiFetch](https://developer.wordpress.org/block-editor/packages/packages-api-fetch/). Это то, что я буду использовать в своем пользовательском блоке Гутенберга. Имейте в виду, что fetchзапросы возвращают «обещание» — поэтому нам нужно связать a в цепочку .then(), чтобы обработать фактический возврат запроса. Базовое использование примерно такое;
apiFetchпозволяет нам предоставить pathсвойство вместо создания полного URL-адреса. Все, что нам нужно предоставить, — это пространство имен и конечная точка, и apiFetchмы добавим их к корневому URL-адресу REST API WordPress. Внутри .then()функции у нас есть доступ к данным, которые уже преобразованы в JSON. Именно здесь вы будете что-то делать с данными. Обычно возвращаемые данные хранятся, например, в состоянии компонента.
Ниже приведен пример пользовательского editкомпонента блока Гутенберга. Он основан на классе, чтобы использовать stateего для хранения возвращаемых данных из запроса REST API. Это также позволяет нам запускать запрос componentDidMount()при первом монтировании (см . документацию React по методам жизненного цикла ). Все это представляет собой простой пример, чтобы вы могли понять основную концепцию; не как рецепт, чтобы сделать это именно так. Вы можете рассмотреть возможность использования хуков и функциональных компонентов React или вместо этого создать компонент более высокого порядка .
Приведенный выше пример представляет собой компоновку на основе класса, которая передается функции блока в editфайле registerBlockType(). Он устанавливает объект состояния массива для хранения данных (очевидно, это зависит от возвращаемых вами данных) и логическое значение состояния, чтобы узнать, когда вернулся асинхронный запрос. После того, как компонент смонтирован (рендерится в первый раз), он запускает функцию для выполнения apiFetchзапроса. Мы устанавливаем путь к конечной точке, которую мы зарегистрировали в PHP выше. Метод по умолчанию GET, поэтому нам не нужно указывать его в apiFetch. А внутри .then()функции, когда запрос готов, мы обновляем состояние компонента возвращаемыми данными.
Очевидно, что функция рендеринга вашего блока будет делать больше с самими возвращаемыми данными. Возможно, вы захотите предоставить данные пользователю, каким-то образом представив список на выбор. Все зависит от того, какие это данные и для чего вы хотите их использовать.
Передача аргументов в конечную точку
В некоторых случаях нам нужно передать некоторые аргументы в конечную точку. Обычно используется передача идентификатора после конечной точки; например http://localhost/wordpress/wp-json/wp/v2/posts/14, вернет идентификатор сообщения 14.
Это довольно просто и делается путем добавления шаблона поиска регулярного выражения в конечную точку при ее регистрации. Для создания сложных шаблонов требуются некоторые знания регулярных выражений, но ниже приведен пример, который сопоставляет число и присваивает ему имя «id». Именование совпадений дает нам средства для доступа к переменной в нашей функции обратного вызова. Позвольте мне показать вам, что я имею в виду.
Давайте зарегистрируем новый маршрут конечной точки. Мы используем ту же конечную точку, что и раньше (‘ awhitepixel/v1/mydata‘), но для этого маршрута мы добавляем соответствие регулярному выражению для числа в конце.
Шаблон регулярных выражений (?P<id>[d]+)кажется загадочным, но будет довольно понятен при некотором базовом понимании регулярных выражений. Часть [d]+соответствует любому числу (0-9) 1 или более раз. Части (?P<id>и )предназначены для сопоставления именованной группы. Имя группы в данном случае id, но вы можете назвать свою группу (группы) как хотите.
Вы можете направить эту конечную точку на отдельную функцию обратного вызова, но я решил использовать одну и ту же функцию для обработки как запросов, так /mydataи /mydata/<ID>запросов. Это означает, что я могу в своей функции обратного вызова:
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);
}Помните, что параметр функции обратного вызова содержит возвращаемые аргументы. Поскольку я назвал совпадающую группу ‘ id‘, совпадающее значение будет доступно в $data['id']. И, наконец, поскольку я использую одну и ту же функцию для обработки запросов с идентификатором и без него, я могу легко переключаться между двумя разными возвратами.
С этим (и обновленными постоянными ссылками) я получу следующие ответы для своих пользовательских конечных точек:
