Создание экрана приложения с помощью встроенного UI
Большинству проектов WordPress рано или поздно нужен экран, больше похожий на приложение, чем на страницу: список записей, кнопка для открытия формы, уведомление об успешном сохранении. Обычно для этого берут фреймворк JavaScript, набор контроллеров REST и библиотеку компонентов, поддерживая их рядом с темой.
Blockstudio уже включает все эти части. db.php предоставляет хранилище для блоков, валидацию и конечные точки CRUD. rpc.php добавляет пользовательские действия на сервере. Встроенные компоненты UI предоставляют диалоговое окно, поля формы, кнопки, значки и всплывающие уведомления. Хранилище Interactivity API связывает их. В этом руководстве мы создадим экран от начала до конца в одной папке блока:
- Таблица проектов: строки отображаются на сервере и остаются синхронизированными с клиентом.
- Диалоговое окно Новый проект с формой, проверяемой по схеме.
- Кнопки Архивировать и Восстановить, которые вызывают функцию RPC с оптимистичным обновлением и откатом.
- Кнопки Удалить, которые напрямую используют данные API.
- Уведомление после успешного создания и другое, если изменение не удалось сохранить.
Перед началом
Встроенные компоненты подключаются по желанию. Включите их в blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Экран находится в одном блоке:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Шаг 1: Модель данных
<?php
return [
'storage' => 'sqlite',
'capability' => [
'create' => 'edit_posts',
'read' => 'edit_posts',
'update' => 'edit_posts',
'delete' => 'edit_posts',
],
'fields' => [
'name' => [
'type' => 'string',
'required' => true,
'minLength' => 2,
'maxLength' => 80,
],
'owner' => [
'type' => 'string',
'format' => 'email',
'required' => true,
],
'status' => [
'type' => 'string',
'enum' => ['active', 'archived'],
'required' => true,
],
],
];
Для каждой операции требуется разрешение edit_posts. Поэтому конечные точки отвечают кодом 401 на запрос без авторизации, а изменять данные могут только редакторы и пользователи с более высоким уровнем доступа. Хранилище SQLite сохраняет записи в projects/db/default.sqlite рядом с кодом.
status имеет тип required, а не default. При использовании SQLite и табличного хранилища схема не подставляет значение по умолчанию, если его нет при создании записи. Поэтому запись, созданная без status, сохраняется с пустым значением. Сделайте поле обязательным и передавайте его из формы, чтобы все строки оставались корректными.
Добавьте несколько начальных записей из командной строки:
wp bs db create acme/projects --name="Website relaunch" --owner=ana@example.com --status=active
wp bs db create acme/projects --name="Q3 report" --owner=ben@example.com --status=archived
wp bs db list acme/projects
Success: Record created (ID: 1).
Success: Record created (ID: 2).
id name owner status created_at updated_at
2 Q3 report ben@example.com archived ...
1 Website relaunch ana@example.com active ...
Список возвращается сначала с самой новой записью — именно такой порядок использует таблица.
Шаг 2: Действие на сервере
Архивирование с точки зрения пользователя — это не простое изменение поля, поэтому для него предусмотрена отдельная именованная функция:
<?php
use Blockstudio\Db;
return [
'set_status' => [
'callback' => function (array $params) {
$id = (int) ($params['id'] ?? 0);
$status = (string) ($params['status'] ?? '');
$db = Db::get('acme/projects');
if (!$db->get_record($id)) {
return new \WP_Error('not_found', 'Project not found.', ['status' => 404]);
}
return $db->update($id, ['status' => $status]);
},
'capability' => 'edit_posts',
],
];
Db::update() проверяет данные по схеме, поэтому enum в db.php по-прежнему контролирует значение. Вызов функции с неизвестным статусом возвращает ошибку в том же формате, что и данные API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Функцию также можно вызвать из командной строки:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Шаг 3: Определение блока
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/projects",
"title": "Projects",
"category": "widgets",
"icon": "list-view",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
supports.interactivity заставляет WordPress обрабатывать директивы шаблона на сервере. Благодаря этому строки таблицы отображаются до запуска любого JavaScript.
Шаг 4: Шаблон
<?php
$can_edit = current_user_can('edit_posts');
$projects = $can_edit ? \Blockstudio\Db::get('acme/projects')->list() : [];
wp_interactivity_state('acme/projects', [
'projects' => array_values($projects),
'hasProjects' => !empty($projects),
'notice' => '',
'isArchived' => function () {
$context = wp_interactivity_get_context();
return 'archived' === ($context['project']['status'] ?? '');
},
]);
?>
<div
useBlockProps
class="projects"
data-wp-interactive="acme/projects"
data-wp-on-document--formsuccess="actions.created"
>
<?php if (!$can_edit) : ?>
<p>Sign in with an editor account to manage projects.</p>
<?php else : ?>
<div class="projects__bar">
<bs:bsui-text content="Projects" variant="title" tag="h2" />
<bs:bsui-dialog>
<bs:bsui-dialog-trigger trigger_label="New project" />
<bs:bsui-dialog-backdrop />
<bs:bsui-dialog-popup>
<bs:bsui-dialog-header>
<bs:bsui-dialog-title content="New project" />
<bs:bsui-dialog-description content="Projects start out active." />
</bs:bsui-dialog-header>
<bs:bsui-dialog-content>
<bs:bsui-form block="acme/projects">
<bs:bsui-field name="name">
<bs:bsui-field-label text="Name" />
<bs:bsui-input name="name" placeholder="Spring campaign" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<bs:bsui-field name="owner">
<bs:bsui-field-label text="Owner email" />
<bs:bsui-input name="owner" type="email" placeholder="owner@example.com" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<input type="hidden" name="status" value="active" />
<bs:bsui-space size="2" />
<bs:bsui-button label="Create project" />
</bs:bsui-form>
</bs:bsui-dialog-content>
<bs:bsui-dialog-footer>
<bs:bsui-dialog-close label="Cancel" />
</bs:bsui-dialog-footer>
</bs:bsui-dialog-popup>
</bs:bsui-dialog>
</div>
<table class="projects__table">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Owner</th>
<th scope="col">Status</th>
<th scope="col">Actions</th>
</tr>
</thead>
<tbody>
<template data-wp-each--project="state.projects" data-wp-each-key="context.project.id">
<tr>
<td data-wp-text="context.project.name"></td>
<td data-wp-text="context.project.owner"></td>
<td>
<span data-wp-bind--hidden="state.isArchived"><bs:bsui-badge label="Active" variant="success" /></span>
<span data-wp-bind--hidden="!state.isArchived"><bs:bsui-badge label="Archived" variant="secondary" /></span>
</td>
<td class="projects__actions">
<span data-wp-on--click="actions.toggleArchived">
<span data-wp-bind--hidden="state.isArchived"><bs:bsui-button label="Archive" variant="outline" size="sm" /></span>
<span data-wp-bind--hidden="!state.isArchived"><bs:bsui-button label="Restore" variant="outline" size="sm" /></span>
</span>
<span data-wp-on--click="actions.remove"><bs:bsui-button label="Delete" variant="ghost" size="sm" /></span>
</td>
</tr>
</template>
</tbody>
</table>
<p class="projects__empty" data-wp-bind--hidden="state.hasProjects">No projects yet.</p>
<div class="projects__toasts">
<bs:bsui-toast-provider>
<div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isCreatedNotice" data-wp-on--click="actions.dismissNotice">
<bs:bsui-toast message="Project created." />
</div>
<div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isFailedNotice" data-wp-on--click="actions.dismissNotice">
<bs:bsui-toast message="That change was not saved." />
</div>
</bs:bsui-toast-provider>
</div>
<?php endif; ?>
</div>
Стоит внимательнее рассмотреть четыре части этого шаблона.
Состояние сервера формирует первую отрисовку. wp_interactivity_state() передаёт записи и обработчику директив на стороне сервера, и клиентскому хранилищу. Шаблон data-wp-each разворачивается на сервере в настоящие строки — по одному tr на запись. isArchived — это замыкание: WordPress вычисляет его для каждой строки при обработке на сервере, а wp_interactivity_get_context() возвращает контекст этой строки. Поэтому до гидратации у архивных строк уже отображаются нужные значок и кнопка. В браузере его заменяет геттер хранилища с тем же именем. По той же причине hasProjects — обычное значение: без него сервер не знал бы, скрывать ли абзац о пустом состоянии.
Диалоговое окно и форма — системные компоненты. trigger_label передаётся компоненту bsui/button внутри триггера, как описано в разделе UIСоставные компоненты. Компонент bsui/form с block="acme/projects" сериализует поля с помощью FormData и отправляет их в конечную точку создания этого блока. Каждый bsui/field содержит имя поля ввода, поэтому ошибки для отдельных полей из схемы отображаются под нужным элементом управления. При отправке пустой формы под полями «Имя» и «Электронная почта владельца» появляются сообщения «Должно быть не менее 2 символов.» и «Введите корректный адрес электронной почты.», а внизу формы — «Проверка не пройдена.». Скрытое поле status отправляется вместе с данными формы и позволяет новым проектам удовлетворять обязательному полю.
Таблица использует вашу разметку. bsui/table подходит для строк, описанных в шаблоне: ячейки заголовка сортируют их, перемещая уже существующие элементы tr, что конфликтовало бы с data-wp-each, претендующим на управление строками. До версии Blockstudio 7.7 его части также вставляли элемент div непосредственно внутрь table, thead, tbody и tr, откуда браузеры перемещают его за пределы таблицы. Для строк из хранилища создайте элемент table самостоятельно и поместите системные компоненты внутрь ячеек. Значки и кнопки в шаблоне строки — обычные теги bsui/badge и bsui/button. Каждая кнопка находится в span с директивой щелчка, поэтому кнопка остаётся системной, а действие принадлежит вашему хранилищу.
Всплывающее уведомление отвечает только за отображение. bsui/toast-provider создаёт вежливую живую область, а bsui/toast отображает сообщение о состоянии с кнопкой закрытия. Провайдер не задаёт своё положение на экране, а кнопка закрытия не скрывает уведомление, добавленное в разметку. Поэтому экран использует оба подхода: обёртка с position: fixed размещает область, а каждое уведомление находится в div, где привязка hidden и обработчик щелчка принадлежат хранилищу экрана. Щелчок по кнопке закрытия всплывает до этого div.
Шаг 5: Хранилище
import { store, getContext } from '@wordpress/interactivity';
const BLOCK = 'acme/projects';
let noticeTimer;
// bs.fn() and bs.db() resolve with the error body on a failed request.
// Throwing here is what lets bs.mutate() roll the optimistic change back.
const ok = (request) =>
request.then((result) => {
if (result?.code) {
throw result;
}
return result;
});
const notify = (notice) => {
state.notice = notice;
clearTimeout(noticeTimer);
noticeTimer = setTimeout(() => {
state.notice = '';
}, 4000);
};
const { state } = store(BLOCK, {
state: {
get hasProjects() {
return state.projects.length > 0;
},
get isArchived() {
return getContext().project.status === 'archived';
},
get isCreatedNotice() {
return state.notice === 'created';
},
get isFailedNotice() {
return state.notice === 'failed';
},
},
actions: {
created(event) {
const record = event.detail;
if (!record?.id || !('owner' in record)) {
return;
}
event.preventDefault();
state.projects = [record, ...state.projects];
store('bsui/dialog').actions.close();
notify('created');
},
dismissNotice() {
state.notice = '';
},
*toggleArchived() {
const project = getContext().project;
const status = project.status === 'archived' ? 'active' : 'archived';
try {
yield bs.mutate({
fn: () => ok(bs.fn('set_status', { id: project.id, status }, BLOCK)),
state,
key: 'projects',
action: 'update',
id: project.id,
optimistic: { status },
});
} catch (error) {
notify('failed');
}
},
*remove() {
const project = getContext().project;
try {
yield bs.mutate({
fn: () => ok(bs.db(BLOCK).delete(project.id)),
state,
key: 'projects',
action: 'delete',
id: project.id,
});
} catch (error) {
notify('failed');
}
},
},
});
Обработка формы. При успешном сохранении bsui/form отправляет всплывающее событие formsuccess, которое можно отменить и которое содержит созданную запись в event.detail. При неудаче сохраняется событие formerror с телом ошибки. Обработчик находится в документе (data-wp-on-document--formsuccess), а не в корневом элементе экрана: открытое всплывающее диалоговое окно перемещается в document.body, поэтому его события больше не всплывают через блок. Проверка owner пропускает события от других форм на той же странице.
Вызов event.preventDefault() не позволяет форме заменить поля сообщением об успехе; при этом форма всё равно сбрасывается. Затем действие добавляет запись в начало списка, закрывает диалог с помощью действия close хранилища bsui/dialog и показывает уведомление. close закрывает верхнее открытое диалоговое окно и возвращает фокус на его триггер. Поэтому после создания проекта фокус клавиатуры возвращается на кнопку Новый проект.
Откат при ошибках. bs.mutate() сразу применяет оптимистичное изменение и восстанавливает прежние значения, если промис из fn отклоняется. bs.fn() и bs.db() не отклоняются при ошибках HTTP: ошибка WP_Error функции RPC, ошибка валидации или отсутствие записи возвращают тело ошибки. Вспомогательная функция ok() превращает результат с code в отклонённый промис, поэтому строка возвращается к прежнему виду и появляется уведомление об ошибке. Без неё при неудачном обновлении тело ошибки попало бы в строку, а после неудачного удаления строка осталась бы удалённой.
Имя блока. Blockstudio выводит встроенные скрипты как <script type="module">, а у модульных скриптов нет document.currentScript, поэтому bs.fn() не может определить, какой блок вызывает функцию. Передайте имя блока третьим аргументом, как это делает хранилище с BLOCK.
Шаг 6: Разместите экран на странице
На странице, создаваемой из файла, блок размещается с помощью его тега:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Парсер преобразует тег в нативный блок:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Выполните wp bs pages sync, чтобы создать страницу. postStatus: "private" скрывает её от анонимных посетителей, которым всё равно показывалось бы сообщение о входе.
Работа экрана во время выполнения
Открыв страницу как редактор:
- Таблица отображается с двумя строками; у архивной строки уже есть значок В архиве и кнопка Восстановить.
- Кнопка Новый проект открывает диалоговое окно. Всплывающее окно и фон перемещаются в
document.body, фокус устанавливается на поле «Имя», а нажатие Escape или Отмена закрывает окно. - При отправке корректных данных один
POSTпередаётся в/wp-json/blockstudio/v1/db/acme-projects/default. Диалог закрывается, новая строка появляется вверху, а в углу на четыре секунды показывается сообщение «Проект создан.». - Кнопка Архивировать сразу меняет значок и отправляет
set_statusчерез/wp-json/blockstudio/v1/fn/acme/projects/set_status. Если запись тем временем удалили в другом месте, функция возвращает ошибку404, строка возвращается в состояние Активен, а на экране появляется сообщение «Изменение не сохранено.». - Кнопка Удалить сразу убирает строку. После удаления последней записи появляется сообщение «Проектов пока нет.».
Стилизация
Таблица считывает токены библиотеки из собственного CSS экрана, поэтому соответствует соседним компонентам и учитывает переопределения свойств --bs-ui-* в теме:
.projects__table {
width: 100%;
border-collapse: collapse;
font-size: var(--bs-ui-font-size);
}
.projects__table th,
.projects__table td {
padding: var(--bs-ui-space-2) var(--bs-ui-space-3);
border-bottom: 1px solid var(--bs-ui-border);
text-align: left;
}
/* ... */
.projects__toasts {
position: fixed;
right: var(--bs-ui-space-4);
bottom: var(--bs-ui-space-4);
z-index: 40;
}
z-index для 40 размещает область уведомлений под фоном диалогового окна, который находится на уровне 50. Чтобы изменить тему всего экрана, переопределите токены, как описано в разделе стилизация. Это повлияет и на компоненты, и на таблицу.
Следующие шаги
- UIКомпоненты: дизайн-система, токены и полный набор компонентов.
- UIСоставные компоненты: группы компонентов, передача триггеров и модель слоёв диалогового окна.
- База данных: режимы хранения, управление доступом,
bs.db()иbs.mutate(). - RPC: управление доступом, методы HTTP и вызовы между блоками.
- Полнофункциональные блоки: те же строительные блоки в приложении со списком дел и форме подписки на рассылку.