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

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

## 在JSON中定义字段

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

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

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

[字段类型参考](https://blockstudio.dev/zh/docs/blocks/attributes/field-types/)

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。

[探索组件](https://blockstudio.dev/zh/docs/blocks/react-components/)

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`。

[模板语言](https://blockstudio.dev/zh/docs/blocks/templating/blade/)

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` 注册自己的全局条件，例如购买检查。

[条件逻辑](https://blockstudio.dev/zh/docs/blocks/attributes/conditional-logic/)

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`。

[重复器模式](https://blockstudio.dev/zh/guides/field-patterns/#repeater-patterns)

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。

[自定义字段](https://blockstudio.dev/zh/docs/blocks/attributes/custom-fields/)

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"` 会下载文件，并按版本仅入队一次，即使多个区块都使用它也是如此。

[资源处理](https://blockstudio.dev/zh/docs/blocks/assets/)

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>` 拼写形式。

[阅读指南](https://blockstudio.dev/zh/guides/block-tags/)

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 社区

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