# 全栈区块

数据库、服务器函数、cron 和 CLI 都在同一个文件夹中。

[阅读指南](https://blockstudio.dev/zh/guides/full-stack-blocks/)

## db.php

定义架构，即可获得 CRUD 端点

db.php

```
<?php
return [
  'storage'    => 'sqlite',
  'userScoped' => true,
  'capability' => [
    'create' => true,
    'read'   => true,
    'update' => true,
    'delete' => true,
  ],
  'fields' => [
    'text' => ['type' => 'string', 'required' => true],
    'done' => ['type' => 'boolean', 'default' => false],
  ],
];
```

## rpc.php

自定义服务器函数

rpc.php

```
<?php
use Blockstudio\Db;

return [
  'toggle' => function (array $params): array {
    $db   = Db::get('my-theme/todo');
    $id   = (int) ($params['id'] ?? 0);
    $todo = $db->get_record($id);
    if ($todo) {
      $db->update($id, ['done' => !$todo['done']]);
    }
    return ['success' => (bool) $todo];
  },
  'clear_done' => function (): array {
    $db = Db::get('my-theme/todo');
    foreach ($db->list(['done' => true], 500) as $todo) {
      $db->delete((int) $todo['id']);
    }
    return ['cleared' => true];
  },
];
```

## 每项功能都是一个文件

每个文件添加一项功能。无需配置，也无需注册代码。

应用程序区块

blockstudio/

└── my-app/

├── block.json 区块定义

├── index.php 模板 + 交互性 API

├── style.css 作用域样式

├── script-inline.js 客户端逻辑

├── db.php 数据模型 + CRUD

├── rpc.php 服务器函数

├── cron.php 计划任务

└── db/default.sqlite

## 数据库

定义架构，即可获得 CRUD 端点。

## [6 种存储模式](https://blockstudio.dev/zh/docs/blocks/block-api/database/#storage-modes)

table, sqlite, jsonc, storh, meta, post_type。根据可移植性和查询需求进行选择。

## [Storh 个文件](https://blockstudio.dev/zh/docs/blocks/block-api/database/#storh-files-storage-storh)

每条记录在 uploads 下单独存为一个文件，索引根据 schema 构建，并支持更安全的并发写入。wp bs db migrate –to=storh 会迁移 JSONC 条记录，并保留其 ID。

## [数据表和文章类型](https://blockstudio.dev/zh/docs/blocks/block-api/database/#custom-table-storage-table)

table 存储会使用 dbDelta 管理 MySQL 表，并为新增字段添加列。post_type 存储会将每条记录保存为一篇文章，因此 WP_Query、REST API 插件和 GraphQL 工具都可以读取它。

## [多个 schema](https://blockstudio.dev/zh/docs/blocks/block-api/database/#multiple-schemas)

从一个 db.php 返回多个命名 schema。每个 schema 都有自己的存储、端点和访问控制。

## [按用户隔离的数据](https://blockstudio.dev/zh/docs/blocks/block-api/database/#user-scoped-data)

设置 userScoped 即可自动隔离记录，无需手动筛选。

## [验证和钩子](https://blockstudio.dev/zh/docs/blocks/block-api/database/#validation)

类型、必填值、枚举、格式、长度、回调和生命周期钩子。

## RPC

可从前端调用的服务器函数。

## [bs.fn() 客户端](https://blockstudio.dev/zh/docs/blocks/block-api/rpc/#calling-from-javascript)

从 JavaScript 调用函数；内联脚本会自动检测区块名称。

## [访问控制](https://blockstudio.dev/zh/docs/blocks/block-api/rpc/#access-control)

每个函数都可单独设置为带 CSRF 防护的公开访问、供 Webhook 使用的开放访问，或基于能力的访问控制。

## [跨区块调用](https://blockstudio.dev/zh/docs/blocks/block-api/rpc/#cross-block-calling)

从 JavaScript 或 PHP 调用任意区块函数并组合逻辑。

## 客户端数据层

在浏览器中读取、缓存和写入记录。

## [bs.db() 客户端](https://blockstudio.dev/zh/docs/blocks/block-api/database/#javascript-client)

通过 JavaScript 创建、列出、获取、更新和删除记录。list 接受字段筛选条件、limit 和 offset。

## [bs.query()](https://blockstudio.dev/zh/docs/blocks/block-api/database/#query)

按键缓存获取结果。正在进行的调用会共用一个 promise；数据仍新鲜时，staleTime 会跳过请求。

## [bs.mutate()](https://blockstudio.dev/zh/docs/blocks/block-api/database/#mutate)

在响应式状态数组中乐观地创建、更新和删除记录；请求失败时回滚到快照。

## [bs.cache](https://blockstudio.dev/zh/docs/blocks/block-api/database/#cache)

bs.query() 和 bs.mutate() 背后的内存缓存。可直接读取、设置、失效或清除条目。

## [实时轮询](https://blockstudio.dev/zh/docs/blocks/block-api/database/#realtime-polling)

在 db.php 中启用实时功能后，客户端会按间隔比较数据哈希，然后更新 Interactivity API 存储。页面标签隐藏时会暂停轮询。

## [缓存页面](https://blockstudio.dev/zh/docs/blocks/block-api/rpc/#cached-pages)

bs.fn() 和 bs.db() 首次调用时会从未缓存的端点获取新凭据，因此即使页面由长期缓存提供服务，公开调用仍能正常工作。

## 表单和应用界面

根据 schema 渲染表单，并提供打包好的 UI 作为构建基础。

## [Schema 表单](https://blockstudio.dev/zh/docs/blocks/block-api/database/#form-rendering)

为字段指定组件键后，bs_db_form() 会通过这些区块渲染表单，并向每个区块传递其字段定义。

## [捆绑表单](https://blockstudio.dev/zh/guides/ui-app-screen/#step-4-the-template)

使用 ui.enabled 时，bsui/form block=”…” 会将字段发送到该区块的创建端点，在每个字段下显示对应的验证错误，并触发 formsuccess 或 formerror。

## [示例应用](https://blockstudio.dev/zh/docs/general/settings/#ui)

ui 设置还会注册 app/* 示例，例如 app/kitchen-sink 和 app/chat；这些示例基于相同的 bsui 组件构建。

## 基础设施

Cron、CLI、设置代码和可移植性。

## [计划任务](https://blockstudio.dev/zh/docs/blocks/block-api/cron/)

cron.php 作业会向 WP-Cron 注册。Composer 安装会通过 wp bs teardown 移除这些作业。

## [数据库 CLI](https://blockstudio.dev/zh/docs/dev/cli/#database)

wp bs db 可按字段筛选记录，获取、创建、更新和删除记录，并输出表格、JSON 或 CSV。

## [在终端中测试](https://blockstudio.dev/zh/docs/dev/cli/#call-a-function)

wp bs rpc call 使用 –key=value 参数运行函数；wp bs cron run 会立即触发任务，不受其计划时间影响。

## [初始化文件](https://blockstudio.dev/zh/docs/blocks/block-api/initialization/)

init.php 和区块文件夹中的其他 init*.php 文件会在 init 时运行一次，可用于注册文章类型等设置操作。

## [原生 PHP 定义](https://blockstudio.dev/zh/docs/blocks/block-api/rpc/#php-native-definitions)

rpc.php 和 cron.php 可以返回一个类，其中包含带有 #[Rpc] 和 #[Cron] 的方法，以及 Access、Method 和 Schedule 枚举。db.php 可以使用 Schema::make() 和 Field 构建器。

## [可移植性](https://blockstudio.dev/zh/guides/full-stack-blocks/)

SQLite 和 JSONC 会随代码一同移交：复制一个文件夹即可部署应用。

Plus

## 官方扩展套件

高级站点模板、AI 系统指令和私人 Discord 社区。一次购买，终身更新。

- 500+ 个网站模板
- AI 系统指令
- 终身更新
- 私有 Discord 社区

[获取 Plus](https://blockstudio.dev/zh/plus/)
