# Пользовательские блоки в 3 файлах

Никакого JavaScript, этапа сборки и шаблонного кода.

## Определяйте поля в JSON

Добавьте ключ `blockstudio` в block.json. Задайте атрибуты с типами, такими как `text`, `toggle` и `color`. Blockstudio автоматически создаёт редактор UI с 27 типами полей: от текстовых полей ввода до повторителей и редакторов кода, а также с типами полей, которые вы зарегистрируете самостоятельно.

Полная поддержка схемы JSON обеспечивает автодополнение и проверку в VS Code, PhpStorm и всех совместимых редакторах.

Для каждого поля можно задать `default` для новых блоков и `fallback`, который шаблон получает, пока поле пустое.

[Справочник по типам полей](https://blockstudio.dev/ru/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 с помощью API одним флагом.

## Компоненты React в шаблонах PHP

Используйте `<RichText />` для встроенного редактирования и статической выдачи HTML, `<InnerBlocks />` для вложенных блоков и `useBlockProps` для обертки — все в одном шаблоне.

В редакторе они становятся полноценными компонентами React. На сайте они отображаются как серверные HTML, а посетителям не отправляется JavaScript.

[Посмотреть компоненты](https://blockstudio.dev/ru/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 работает сразу после установки, Twig запускается после установки Timber, а Blade работает на версиях `illuminate/view` с 8 по 12 через `Blockstudio\Blade_Renderer`. Переменные, компоненты и поведение остаются одинаковыми.

`$a` (атрибуты), `$b` (блок), `$c` (контекст) и `$innerBlocks` доступны в любом языке.

Twig шаблоны также получают полный контекст Timber. Blade также отображает страницы, паттерны и шаблоны редактора сайта. Старая обертка `jenssegers/blade` не работает с `illuminate/view` 10 и более поздними версиями, поэтому используйте `Blade_Renderer`.

[Языки шаблонов](https://blockstudio.dev/ru/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` и сравнения. Объединяйте условия с помощью логического ИЛИ.

Параметры могут зависеть от другого поля. Добавьте `{attributes.post_type.value}` в аргументы populate, и список будет обновляться при изменении этого поля. Добавьте `fetch: true`, чтобы искать записи по мере ввода редактором текста.

Используйте один список параметров для разных блоков с помощью `type: custom` и фильтра `blockstudio/blocks/attributes/populate`, а собственные глобальные условия, например проверку покупки, регистрируйте через `blockstudio/blocks/conditions`.

[Условная логика](https://blockstudio.dev/ru/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/ru/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/ru/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/ru/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`, а сокращения преобразуйте в переносимый формат `<bs:acme-card>` командой `migrate-block-tags`.

[Открыть руководство](https://blockstudio.dev/ru/guides/block-tags/)

blockstudio.json

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

## Пользовательские типы полей

Зарегистрируйте собственный элемент управления полем и используйте его как встроенное поле.

## Островки блоков

Кэшируйте всю страницу, а один блок отображайте во время запроса посетителя.

## Условная регистрация

Регистрируйте блок только для определенного типа записей, роли пользователя или другого глобального условия либо пропускайте его, если отсутствует необходимый плагин или нужная версия плагина.

## Метаданные записей и параметры

Храните значения в метаданных записей или параметрах вместе с атрибутами блока.

## Условная логика

Показывайте поля на основе значений, используя равенство, включение, проверку на пустоту и сравнения.

## Динамическое заполнение

Заполняйте варианты значениями из записей, пользователей, терминов, функций или API.

## Переопределения

Чтобы объединить атрибуты по идентификатору, заменить ресурсы с совпадающими именами файлов и изменить шаблон, задайте override: true, указав имя общего блока. Шаблоны Twig могут переопределять отдельные блоки с помощью extends.

## Вариации

Объявляйте варианты в block.json, чтобы задавать значения полей по умолчанию, а управляющее ими поле скрывайте с помощью hidden.

## Компоненты

Задайте component: true для блока, который отображается только из PHP или тегов блоков. Он сохраняет поля, шаблоны, ресурсы и Tailwind, но не появляется в панели вставки.

## Правила InnerBlocks

Разрешите блоки с токенами namespace/*, category: и @theme, переключайте внутренний шаблон с помощью параметра select и удаляйте внешнюю обертку на фронтенде через фильтр.

## Ресурсы для полей кода

Поле кода с 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 обновляет предпросмотр после сохранения.

## Контекст цикла запросов

В цикле запросов $block[‘context’][‘postId’] следует за текущим элементом, а $block[‘postId’] остается идентификатором просматриваемой записи.

## WPML

Команда wp bs wpml config создает wpml-config.xml, помечающий текстовые поля как переводимые, а изображения, сохраненные в полях, включаются в задания на перевод WPML вместе с альтернативными текстами и подписями.

Plus

## Официальный набор расширений

Премиум-шаблоны сайтов, системные инструкции для ИИ и закрытое сообщество Discord. Разовая покупка, обновления навсегда.

- 500+ шаблонов сайтов
- Системные инструкции для ИИ
- Пожизненные обновления
- Закрытое сообщество Discord

[Получить Plus](https://blockstudio.dev/ru/plus/)
