跳转到正文

使用捆绑的 UI 构建应用屏幕

大多数 WordPress 项目最终都需要一个更像应用而非页面的屏幕:记录列表、用于打开表单的按钮,以及保存成功时的一些反馈。通常的做法是使用一个 JavaScript 框架、一组 REST 控制器和一个组件库,并将它们与主题一起维护。

Blockstudio 已经集成了这些组件。db.php提供区块存储、验证和 CRUD 端点。rpc.php则添加自定义服务器操作。捆绑的 UI 组件提供对话框、表单字段、按钮、徽章和提示消息。Interactivity API 存储将它们连接起来。本指南将在一个区块文件夹中端到端构建一个屏幕:

  • 项目表格在服务器端渲染,并在客户端保持同步。
  • 新建项目对话框,带有根据架构验证的表单。
  • 归档和恢复按钮会调用 RPC 函数,并进行乐观更新和回滚。
  • 删除按钮会直接使用数据 API。
  • 创建成功后显示提示消息,未能保存更改时也会显示另一条提示。

开始之前

捆绑的组件默认不启用。请在 blockstudio.json 中启用它们:

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
<?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
<?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() 会根据架构进行验证,因此 db.php 中的 enum 仍会检查该值。使用未知状态调用此函数时,会返回与数据 API 相同的错误格式:

JSON
{"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:区块定义

JSON
{
  "$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
<?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() 将记录交给服务器端指令处理器和客户端 store。data-wp-each 模板会在服务器端展开为实际行,每条记录对应一个 tr。isArchived 是一个闭包:服务器处理期间,WordPress 会为每一行对其求值,并由 wp_interactivity_get_context() 返回该行的上下文,因此归档行在 hydration 之前就会显示正确的徽标和按钮。在浏览器中,同名的 store getter 会接手。hasProjects 同样是一个普通值:没有它,服务器就无法判断是否应隐藏空状态段落。

对话框和表单使用系统组件。trigger_label 会传递给触发器中的 bsui/button,如 UI组合 中所述。bsui/form 配合 block="acme/projects" 使用时,会通过 FormData 序列化字段,并将其发送到该区块的创建端点。每个 bsui/field 都带有其输入名称,因此架构返回的字段错误会显示在对应控件下方。提交空表单时,Name 下方会显示“至少需要 2 个字符。”,Owner email 下方会显示“请输入有效的电子邮件地址。”,表单底部还会显示“验证失败。”。隐藏的 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:存储

JavaScript
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() 会阻止表单将字段替换为成功消息;表单仍会自行重置。随后,该操作会将记录添加到列表开头,通过 bsui/dialog 存储的 close 操作关闭对话框,并显示提示消息。close 会关闭最上方打开的对话框,并将焦点还给其触发器,因此创建完成后,键盘焦点会回到新建项目按钮上。

出错时回滚。bs.mutate() 会立即应用乐观更改,并在 fn 返回的 Promise 被拒绝时恢复之前的值。bs.fn() 和 bs.db() 不会因 HTTP 错误而拒绝:RPC 函数返回的 WP_Error、验证失败或记录缺失,都会以错误主体作为结果正常返回。ok() 辅助函数会将带有 code 的结果转换为拒绝状态,因此该行会恢复原样,并显示失败提示消息。如果没有它,更新失败时错误主体会被合并到该行中,删除失败时该行则会继续处于删除状态。

指定区块名称。 Blockstudio 会将内联脚本打印为 <script type="module">,而模块脚本没有 document.currentScript,因此 bs.fn() 无法检测是哪个区块在调用。请像存储中那样,将区块名称作为第三个参数传入:BLOCK。

步骤 6:将屏幕放到页面上

基于文件的页面通过标签放置区块:

JSON
{
  "$schema": "https://blockstudio.dev/schema/page",
  "name": "projects",
  "title": "Projects",
  "slug": "projects",
  "postStatus": "private"
}
PHP
<h1>Projects</h1>
<bs:acme-projects />

解析器会将标签转换为原生区块:

HTML
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->

运行 wp bs pages sync 来创建页面。postStatus: "private" 会阻止匿名访客访问;他们无论如何都只会看到登录提示。

屏幕的运行时行为

以编辑者身份打开页面后:

  1. 表格加载时,两行都已渲染;归档的行会显示已归档徽章和恢复按钮。
  2. 点击新建项目会打开对话框。弹出层和背景遮罩会移动到 document.body,焦点会落在 Name 字段中,按 Escape 或点击取消即可关闭对话框。
  3. 提交有效值后,会向 /wp-json/blockstudio/v1/db/acme-projects/default 发送一个 POST。对话框关闭,新行出现在最上方,角落中会显示“项目已创建。”,持续四秒。
  4. 点击归档会立即切换徽章,并通过 /wp-json/blockstudio/v1/fn/acme/projects/set_status 发送 set_status。如果记录在此期间已在其他位置删除,函数会返回 404 错误;该行会恢复为活跃状态,并显示“未保存此更改。”。
  5. 点击删除会立即移除该行。删除最后一条记录后,会显示“暂无项目。”

样式

屏幕自身的 CSS 会读取库中的设计令牌,因此表格会与周围组件相匹配,并遵循对 --bs-ui-* 属性所做的主题覆盖:

CSS
.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;
}

40 中的 z-index 会使提示消息区域位于对话框背景遮罩下方;背景遮罩的层级为 50。如需为整个屏幕更换主题,请按照样式中的说明覆盖设计令牌;组件和表格都会随之更新。

后续步骤

  • UI组件:设计系统、设计令牌和完整组件集。
  • UI组合:复合组件系列、触发器传递,以及对话框背后的分层模型。
  • 数据库:存储模式、访问控制、bs.db() 和 bs.mutate()。
  • RPC:访问控制、HTTP方法和跨区块调用。
  • 全栈区块:在待办事项应用和新闻简报注册页面中使用相同的构建模块。