为编辑内容的人而打造

更宽的字段抽屉、工具栏控件、编辑器策略和管理后台清单，配置于 block.json 和 blockstudio.json。

容纳各种字段

重复器、代码字段和嵌套组在侧边栏中显得拥挤。区块标题中有一个 Open Expanded Editor 按钮，可从右侧打开更宽的抽屉，显示相同的字段。点击完成、背景或按 Esc 即可关闭，区块仍保持选中状态。

它使用相同的字段渲染器写入相同的属性，因此预览会随输入即时更新，而且无需设置 block.json。属于内容旁边的字段可以通过 "position": "toolbar" 移至区块工具栏。

block.json

{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      {
        "id": "alignment",
        "type": "select",
        "label": "Alignment",
        "position": "toolbar",
        "options": [
          { "value": "left", "label": "Left" },
          { "value": "center", "label": "Center" },
          { "value": "right", "label": "Right" }
        ]
      },
      {
        "id": "title",
        "type": "text",
        "label": "Title"
      }
    ]
  }
}

根据你的 CSS 自动补全

列出 blockEditor.cssClasses 和 cssVariables 中的样式表 URL；类名和代码字段则能提示这些文件定义的内容。

悬停和选中提示

设置 blockEditor.enhance，即可将 Blockstudio 的悬停和选中提示添加到编辑器中。

谁可以访问编辑器

users.ids 和 users.roles 在 blockstudio.json 中指定拥有 Blockstudio 编辑器访问权限的用户 ID 和角色。

使用客户的语言

字段控件、管理界面和画布会使用网站语言或各用户的个人资料语言，译文来自随附的翻译文件。

仅供编辑器使用的资源

editor.assets 中的 blockstudio.json 会列出要在编辑器中加载的其他资源。

首个载荷中的媒体

文件字段会先从初始编辑器载荷中读取附件数据，包括嵌套组、选项卡和重复器中的数据，然后才请求媒体端点。

一次只处理一个预览请求

区块有新的预览请求时，浏览器会取消之前的请求，同时让当前预览继续显示。

每个区块保留各自的值

多选的区块各自保留其值；撤销和重做也涵盖 RichText 和侧边栏字段。

关闭字段，保留其值

编辑者可以在检查器中关闭某个字段：将鼠标悬停在字段左边缘，直到出现蓝色边框，然后点击。字段会变为半透明，其值仍会保存；在有人重新启用它之前，区块不会渲染该字段。

文件字段中的单个项目也可以这样处理，因此可以暂时隐藏一张图片，同时显示其他图片。设置 "switch": true 可为字段显示切换开关；当模板需要判断时，读取 $a['_disabled']。

禁用属性

block.json

{
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      {
        "id": "title",
        "type": "text",
        "label": "Title",
        "switch": true
      }
    ]
  }
}

index.php

<?php if (!empty($a['_disabled']) && in_array('title', $a['_disabled'])) : ?>
  <p>No title on this one.</p>
<?php else : ?>
  <h1><?php echo esc_html($a['title']); ?></h1>
<?php endif; ?>

插入器中的预览

在 block.json 中添加 example 键后，编辑者将鼠标悬停在区块插入器中的区块上时，就会看到预览。对于默认外观合适的区块，空对象就足够了。

为 example.attributes 提供你自定义字段的示例值，或为包含其他区块的区块提供初始树结构 example.innerBlocks。

插入器预览

block.json

{
  "name": "my-theme/hero",
  "title": "Hero",
  "category": "text",
  "example": {
    "attributes": {
      "title": "This title will be shown in the preview"
    }
  },
  "blockstudio": true
}

index.php

<h1><?php echo esc_html($a['title']); ?></h1>

在一个文件中设置编辑器策略

无需主题胶水代码，即可决定插入器提供哪些内容。blockEditor.blocks 接受带通配符的允许和拒绝列表（例如 core/*），可重命名和排序分类、移除在 PHP 中注册的区块样式、隐藏旧版小工具，还可以关闭区块目录。

blockEditor.patterns 可启用或关闭核心、远程、主题和 Blockstudio 图案来源，并筛选其分类。blockEditor.media 可关闭 Openverse，并限制编辑者可选择的图像尺寸。

区块编辑器设置

blockstudio.json

{
  "blockEditor": {
    "blocks": {
      "allow": ["core/*", "my-theme/*"],
      "deny": ["core/embed", "core/freeform"],
      "directory": false,
      "categories": {
        "rename": { "text": "Writing" },
        "order": ["my-theme", "text", "media"]
      },
      "styles": {
        "deny": { "my-theme/card": ["outline"] }
      },
      "legacyWidgets": { "hide": ["archives", "calendar"] }
    },
    "patterns": {
      "core": false,
      "remote": false,
      "categories": { "deny": ["gallery"] }
    },
    "media": {
      "openverse": false,
      "imageSizes": { "allow": ["thumbnail", "large"] }
    }
  }
}

快速呈现首屏

Blockstudio 区块在服务器上渲染。编辑器会预加载文章中已有区块的渲染输出，包括同步图案中的嵌套区块，并在首屏呈现时复用这些输出，而不是为每个已保存区块单独发送渲染请求。

代码、类、属性和所见即所得控件会在首次出现时下载，因此未选中的区块不会加载它们。不需要实时预览的区块可以设置 disableLoading 并显示占位内容，同时仍可编辑所有字段。

编辑器加载

block.json

{
  "name": "my-theme/map",
  "title": "Map",
  "blockstudio": {
    "blockEditor": {
      "disableLoading": true
    }
  }
}

blockstudio.json

{
  "blockEditor": {
    "disableLoading": true
  }
}

行为与页面一致的预览

Interactivity API 会在编辑器 iframe 中加载，因此 data-wp-context、绑定、事件处理程序和你的存储操作都会在画布中运行。打包好的 bsui/* 组件基于它构建，因此你编辑时，对话框会打开，下拉选择框也会展开。

预览中的链接无论被点击、通过修饰键打开，还是通过键盘激活，都不会跳转离开；点击仍会选中区块。使用 assets.reset.enabled 时，主题的 body 类会复制到画布中，因此诸如 .brand-a .site-card 这样的选择器在那里也能匹配。

交互性

block.json

{
  "name": "my-theme/disclosure",
  "title": "Disclosure",
  "blockstudio": {
    "interactivity": true
  }
}

functions.php

<?php
add_filter('blockstudio/editor/canvas/body_class', function (array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

位于 Tools > Blockstudio 的清单

管理界面会列出 Blockstudio 从文件系统注册的内容：区块、扩展、字段、带有同步状态的页面，以及 db.php 架构，并以原生 WordPress DataViews 表格呈现。数据库视图可浏览各架构的记录，这些记录通过 REST API 获取并分页显示。

当主题的 blocks.json 命名了注册表时，注册表视图会列出其中的区块，并可从 wp-admin 将它们导入你的区块目录。拥有 manage_options 的用户可以访问此界面，blockstudio/admin/enabled 筛选器则会将其关闭。

管理界面

blocks.json

{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json"
  }
}

functions.php

<?php
add_filter('blockstudio/admin/enabled', '__return_false');

Plus

官方扩展套件

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

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

获取 Plus