跳转到正文

用 3 个文件创建自定义区块

无需JavaScript,无需构建步骤,也没有样板代码。

在JSON中定义字段

在block.json中添加blockstudio键。定义带有text、toggle和color等类型的属性。Blockstudio会自动生成编辑器UI,提供27种字段类型,从文本输入框到重复器和代码编辑器,还支持你自行注册的字段类型。

完整的JSON Schema 支持可在VS Code、PhpStorm和所有兼容的编辑器中提供自动补全和验证。

每个字段都可以为新建区块设置一个 default,以及一个在字段为空时传递给模板的 fallback。

block.json
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "showCta", "type": "toggle", "label": "Show CTA" },
      { "id": "background", "type": "color", "label": "Background" }
    ]
  }
}

三文件工作流

block.json用于字段,一个模板用于标记,还可选配一个样式表。

React用于PHP

RichText、InnerBlocks 和useBlockProps可直接用于PHP、Twig或Blade。

SCSS和Tailwind

使用 CSS、SCSS 或 Tailwind。SCSS 支持导入路径和共享前导代码;编辑嵌套的局部模板时,所有导入它的文件都会重新编译。

27 种字段类型

文本、颜色、图像、重复器、选择框、代码编辑器等,都在JSON中配置。

JSON Schema

在VS Code、PhpStorm和兼容的编辑器中提供自动补全和验证。

三种模板语言

PHP、Twig和Blade共用相同的变量和组件。

npm导入

在script.js中导入软件包;生产环境使用本地版本,编辑器中则由CDN提供支持。

Interactivity API

只需设置一个标志,即可启用WordPress Interactivity API。

React组件用于PHP模板

在一个模板中使用<RichText />实现内联编辑和静态前端HTML,使用<InnerBlocks />处理子区块,并使用useBlockProps作为包装器。

在编辑器中,它们会变成真正的React组件。在前端,它们会渲染为服务器端HTML,不会向访客发送任何JavaScript。

index.php
<div useBlockProps class="container">
  <RichText
    class="text-xl font-semibold"
    tag="h1"
    attribute="headline"
    placeholder="Enter headline"
  />

  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>

  <InnerBlocks class="mt-4 p-4 border" />
</div>

使用PHP、Twig或Blade编写

使用你熟悉的模板语言。PHP 开箱即用;安装 Timber 后即可使用 Twig;Blade 则通过 Blockstudio\Blade_Renderer 在 illuminate/view 8 到 12 上运行。变量、组件和行为都保持一致。

所有语言中都可使用$a(属性)、$b(区块)、$c(上下文)和$innerBlocks。

Twig 模板也会接收完整的 Timber 上下文。Blade 也会渲染页面、区块样板和站点编辑器模板。较旧的 jenssegers/blade 封装器在 illuminate/view 10 及更高版本中无法运行,因此请改用 Blade_Renderer。

index.twig
<div useBlockProps class="card">
  <RichText tag="h2" attribute="title" placeholder="Card title" />
  {% if a.image %}
    <img src="{{ a.image.url|esc_url }}"
      alt="{{ a.image.alt|esc_attr }}" />
  {% endif %}
  <div class="card__body">{{ a.description|esc_html }}</div>
  <InnerBlocks allowedBlocks='["core/button"]' />
</div>

条件逻辑和动态选项

使用包括==、!=、includes、empty和比较运算符在内的运算符来显示或隐藏字段。使用 OR 逻辑组合条件。

选项可以依赖其他字段。将 {attributes.post_type.value} 放入填充参数中,该字段发生变化时列表就会重新加载。添加 fetch: true,即可在编辑者输入时搜索文章。

通过 type: custom 和 blockstudio/blocks/attributes/populate 过滤器,让多个区块共用一个选项列表;还可以通过 blockstudio/blocks/conditions 注册自己的全局条件,例如购买检查。

block.json
{
  "name": "starter/posts",
  "title": "Posts",
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post type",
        "options": [
          { "value": "page", "label": "Pages" },
          { "value": "post", "label": "Posts" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": { "post_type": "{attributes.post_type.value}" }
        }
      },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "populate": { "type": "custom", "custom": "cardStyles" },
        "conditions": [[
          { "type": "purchasedProduct", "operator": "==", "value": "yes" }
        ]]
      }
    ]
  }
}

让重复器始终易于管理

设置 min 和 max,用 default 行创建新区块,并用 minimized 折叠现有行。textMinimized 会使用该行自身的某个字段(例如名称)为折叠行添加标签。

行接受除选项卡之外的所有字段类型,包括嵌套重复器。行内的条件可通过 "context": "main" 检查行外字段;<RichText /> 和 <MediaPlaceholder /> 则可编辑单行,条件是其 attribute 指向 repeaterId[index].fieldId。

block.json
{
  "name": "starter/team",
  "title": "Team",
  "blockstudio": {
    "attributes": [
      {
        "id": "members",
        "type": "repeater",
        "label": "Team members",
        "min": 1,
        "max": 12,
        "minimized": true,
        "textMinimized": { "id": "name", "fallback": "Team member" },
        "attributes": [
          { "id": "name", "type": "text", "label": "Name" },
          { "id": "bio", "type": "richtext", "label": "Bio" }
        ]
      }
    ]
  }
}

可复用字段集

在 field.json 中定义一次字段组,然后通过 "type": "custom/cta" 在任意区块中引用。字段会内联展开,因此模板读取它们的方式与读取其他属性相同。

使用 idStructure(例如 hero_{id})重复使用同一组字段,并通过 overrides 为每个区块修改标签、默认值或条件。block 字段类型也能对整个区块执行相同操作:它会内联展开该区块的字段,并返回其渲染后的 HTML。

fields/cta/field.json
{
  "name": "cta",
  "title": "Call to action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
    { "id": "url", "type": "link", "label": "Button URL" }
  ]
}

无需构建步骤的 ES 模块

添加script.js即可将其作为 ES 模块加载。使用npm:前缀导入npm软件包,Blockstudio会在本地下载这些软件包,以供生产环境使用。

编辑器可即时预览;前端使用本地模块,无任何外部依赖,而且只会入队一次。

样式表也可以用相同方式导入。import "npm:swiper@11.0.0/swiper.min.css" 会下载文件,并按版本仅入队一次,即使多个区块都使用它也是如此。

script.js
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";

for (const el of document.querySelectorAll(".swiper")) {
  new Swiper(el, {
    slidesPerView: 3,
    spaceBetween: 20,
    loop: true,
  });
}

模板之外的区块标签

在 blockstudio.json 中将简短前缀映射到命名空间,或通过别名过滤器将单个标签映射到单个区块,然后由 <acme-card> 渲染 acme/card。启用 blockTags.enabled 后,可在文章内容和小工具中渲染标签,并由 allow 和 deny 模式限制范围。

data-* 属性会传递到区块的根元素;html-* 属性也会传递到那里,但不带前缀。使用 blockstudio/block_tags/builders 添加自己的标签构建器,并通过 migrate-block-tags 命令将简写改写为可移植的 <bs:acme-card> 拼写形式。

blockstudio.json
{
  "blockTags": {
    "enabled": true,
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    },
    "deny": ["acme-ui/admin-*"]
  }
}

自定义字段类型

注册自己的字段控件,并像使用内置字段一样使用它。

区块孤岛

缓存整个页面,并在访客的请求中渲染一个区块。

条件注册

仅针对某种文章类型、用户角色或其他全局条件注册区块;如果缺少所需插件或插件版本,也可以跳过注册。

文章元数据和选项

将值与区块属性一同存储在文章元数据或选项中。

条件逻辑

根据值使用相等、包含、空值检查和比较来显示字段。

动态填充

从文章、用户、术语、函数或 API 填充选项。

覆盖

将共享区块的名称与 override: true 一起设置,即可按 id 合并属性、替换文件名匹配的资源,并替换模板。Twig 模板可以使用 extends 覆盖单个区块。

变体

在 block.json 中声明预设字段值的变体,并使用 hidden 隐藏驱动这些变体的字段。

组件

为仅通过 PHP 或区块标签渲染的区块设置 component: true。它会保留字段、模板、资源和 Tailwind,但不会出现在插入器中。

内部区块规则

允许使用 namespace/*、category: 和 @theme 标记的区块,通过选择选项切换内部模板,并使用过滤器在前端移除包装器。

代码字段资源

将代码字段设置为 asset: true 后,编辑器输入内容会变成该区块的 CSS、SCSS 或 JavaScript,并通过 %selector% 限定到具体实例。

按文件名管理资源

*.view.js 仅在前端加载;global-、admin- 和 block-editor- 前缀则分别让文件在每个页面、wp-admin 中或区块编辑器中加载。

图标和区块文件夹

为区块指定自定义 SVG 或 HTML 图标,使用 blockstudio/path 过滤器调整发现路径,并通过 Blockstudio\Build::init() 添加文件夹。

ACF 和 Meta Box 值

模板会接收 $post_id,因此 get_field() 和 rwmb_get_value() 会读取编辑后的文章;保存后,refreshOn 会重新加载预览。

Query Loop 上下文

在 Query Loop 中,$block[‘context’][‘postId’] 会跟随当前条目,而 $block[‘postId’] 仍指向正在查看的文章。

WPML

wp bs wpml config 会写入用于标记可翻译文本字段的 wpml-config.xml;存储在字段中的图片也会加入 WPML 翻译任务,并附带替代文本和说明文字。

Plus

官方扩展套件

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

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