Перейти к содержимому

Настройки

Blockstudio включает мощный механизм настроек API, который позволяет задавать параметры с помощью файла blockstudio.json в папке темы и/или фильтров. Кроме того, пользователи с необходимыми правами могут менять настройки через визуальный интерфейс панели администратора.

Через JSON

Если в папке темы есть файл blockstudio.json, он будет использоваться для задания параметров сайта по умолчанию. Для проверки файла и поддержки автодополнения в IDE доступна схема JSON.

Файл необязателен. Если его нет, Blockstudio использует настройки, сохраненные в панели администратора, поверх встроенных значений по умолчанию. Добавление, изменение или удаление файла обнаруживается автоматически, поэтому очищать кэш или перезагружать страницу вручную не нужно.

Доступны следующие свойства:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "users": {
    "ids": [],
    "roles": []
  },
  "assets": {
    "enqueue": true,
    "reset": {
      "enabled": false,
      "fullWidth": []
    },
    "minify": {
      "css": false,
      "js": false
    },
    "process": {
      "scss": false
    }
  },
  "cache": {
    "enabled": true,
    "path": "blockstudio/cache"
  },
  "themeDefaults": {
    "titleTag": false,
    "suppressDirectoryUpdates": false
  },
  "performance": {
    "profile": "compat",
    "wordpress": {
      "headNoise": false,
      "embeds": false,
      "xmlrpc": false,
      "editor": false,
      "frontendAssets": false,
      "media": false,
      "heartbeat": false
    },
    "preload": {
      "links": "off"
    },
    "media": {
      "lazy": false,
      "skeleton": false,
      "metadata": false,
      "rootMargin": "300px"
    },
    "measurement": {
      "enabled": false,
      "queryMonitor": false,
      "headers": false,
      "timings": false
    }
  },
  "content": {
    "enabled": false,
    "id": "default",
    "path": "content",
    "includePageSyncManaged": false,
    "authors": "ignore",
    "postTypes": [],
    "meta": {
      "include": [],
      "exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
      "references": {}
    },
    "taxonomies": [],
    "media": "manifest"
  },
  "editor": {
    "formatOnSave": false,
    "assets": [],
    "markup": false
  },
  "tailwind": {
    "enabled": false,
    "config": "",
    "output": "inline"
  },
  "blockTags": {
    "enabled": false,
    "allow": [],
    "deny": [],
    "prefixes": {}
  },
  "ui": {
    "enabled": false
  },
  "blockEditor": {
    "disableLoading": false,
    "enhance": false,
    "cssClasses": [],
    "cssVariables": [],
    "blocks": {
      "allow": [],
      "deny": [],
      "directory": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      },
      "styles": {
        "deny": {}
      },
      "legacyWidgets": {
        "hide": []
      }
    },
    "patterns": {
      "core": true,
      "remote": true,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      }
    },
    "media": {
      "openverse": true,
      "imageSizes": {
        "allow": [],
        "deny": []
      }
    }
  },
  "dev": {
    "grab": {
      "enabled": false
    },
    "perf": false,
    "canvas": {
      "enabled": false,
      "adminBar": true
    }
  },
  "githooks": {
    "commit": false
  },
  "phpstan": {
    "preset": "base",
    "configuration": "",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "ai": {
    "enableContextGeneration": false
  }
}

Через фильтры

Также можно использовать фильтр blockstudio/settings/${setting}, чтобы задавать параметры через PHP и получить больше гибкости.

PHP
add_filter('blockstudio/settings/assets/enqueue', '__return_false');
add_filter('blockstudio/settings/editor/formatOnSave', '__return_true');
add_filter('blockstudio/settings/ui/enabled', '__return_true');
add_filter('blockstudio/settings/block_editor/patterns/remote', '__return_false');

Параметры, заданные через фильтр blockstudio/settings/${setting}, имеют приоритет над параметрами из файла blockstudio.json. Можно использовать оба способа одновременно.

Для значений времени выполнения также доступны фильтры blockstudio/performance/${setting} и заключительный фильтр blockstudio/performance/config. Последний должен возвращать допустимый объект конфигурации.

Порядок наложения источников

Все источники загружаются и объединяются в порядке возрастания приоритета:

  1. Встроенные значения по умолчанию
  2. Настройки, сохраненные через UI администратора (параметр blockstudio_settings)
  3. blockstudio.json в теме
  4. Фильтры blockstudio/settings/*

blockstudio.json переопределяет только указанные в нем ключи. Раньше он полностью заменял сохраненные настройки, поэтому после появления файла переставало применяться любое не связанное с ним значение, сохраненное администратором; теперь настройки из файла дополняют их. Обратная сторона: устаревшее значение, сохраненное через UI администратора, продолжает применяться, пока ключ не будет указан в файле или сохраненное значение не будет удалено. Если настройка работает не так, как указано в файле, проверьте сохраненный слой с помощью wp bs settings или Settings::get_raw(): эти функции возвращают только то, что явно указано в активном источнике JSON или в источнике параметров.

Чтение настроек из PHP

Blockstudio\Settings загружает активный источник, сообщает об ошибках в JSON и автоматически перезагружается при изменении blockstudio.json:

PHP
use Blockstudio\Settings;

$enabled = Settings::get_bool('performance/media/lazy');
$margin = Settings::get_string('performance/media/rootMargin', '300px');
$roles = Settings::get_array('users/roles');
$ttl = Settings::get_int('performance/staticPrerender/ttl', 86400);

foreach (Settings::errors() as $error) {
    error_log($error);
}

Используйте Settings::get_raw(), если интеграции нужны только значения, явно объявленные активным источником JSON или параметров. Settings::fingerprint() возвращает детерминированный идентификатор эффективных настроек. В длительно работающих процессах можно явно вызвать Settings::reload(), чтобы немедленно прочитать изменения файла. При обычном доступе файл проверяется не чаще одного раза в секунду в рамках запроса или длительно работающего процесса PHP, в том числе при изменении содержимого без изменения размера. Изменение настроенного пути вступает в силу при следующем чтении. Если активного файла JSON нет, сохраненные в базе данных настройки не задерживаются этим интервалом.

Определенный профиль производительности доступен через Blockstudio\Runtime_Settings::current(). Поддерживаются пути с косой чертой и с точкой:

PHP
use Blockstudio\Runtime_Settings;

$runtime = Runtime_Settings::current();

if ($runtime->enabled('measurement/queryMonitor')) {
    $hash = $runtime->hash();
}

Доступные настройки

users

Параметр Тип По умолчанию Описание
ids array [] Идентификаторы пользователей с доступом редактора
roles array [] Роли пользователей с доступом редактора

assets

Параметр Тип По умолчанию Описание
enqueue логический true Автоматически добавлять ресурсы блоков в очередь
reset.enabled логический false Удалять стили блоков ядра и применять сброс служебных стилей редактора
reset.fullWidth массив [] Типы записей, использующие полноширинную разметку редактора
minify.css логический false Минифицировать вывод CSS
minify.js логический false Минифицировать вывод JS
process.scss логический false Обрабатывать файлы SCSS
output строка source Путь для скомпилированных ресурсов: source или cache
inlineLimit целое число 0 Количество байтов внешних стилей блоков CSS, выводимых на каждой странице встроенно

По умолчанию output имеет значение source: рядом с каждым блоком создается каталог _dist. Задайте cache, чтобы записывать скомпилированные ресурсы в каталог кэша Blockstudio; так дерево исходных файлов блоков останется чистым, а развертывание можно будет выполнять из неизменяемой рабочей копии. Источники Blockstudio, которые не могут записывать файлы в исходные каталоги, в любом случае перенаправляются в кэш независимо от этой настройки.

inlineLimit выключен при значении 0, поэтому каждая внешняя таблица стилей сохраняет тег <link>. Вместо этого задайте количество байтов, чтобы выводить встроенно самые маленькие внешние таблицы стилей блоков страницы, если их общий размер не превышает это значение. 40000 — это предел, который ядро WordPress использует для того же правила. См. раздел Встраивание небольших таблиц стилей.

Если включен параметр reset.enabled, Blockstudio также копирует очищенные значения body_class для внешнего интерфейса в холст редактора. Используйте blockstudio/editor/canvas/body_class, чтобы настроить список классов только для редактора.

cache

Параметр Тип По умолчанию Описание
enabled boolean true Включить кэши на основе файлов Blockstudio
path string "blockstudio/cache" Путь к кэшу, относительный к WP_CONTENT_DIR или абсолютный
namespaceGrace integer 86400 Сколько секунд хранить выведенное из использования пространство имен кэша до очистки

По умолчанию файлы кэша записываются в wp-content/blockstudio/cache, за пределами каталога uploads. Относительный путь path разрешается относительно WP_CONTENT_DIR; абсолютный путь используется напрямую. Это подходит для хостов с отдельным доступным для записи томом кэша.

Если параметр включен, Blockstudio использует этот корневой каталог для полезных данных сборки, предварительно подготовленных данных регистрации блоков, разрешенных ресурсов редактора, Tailwind CSS, документов рендеринга, фрагментов островов, статических пререндеров, индексов графа, очередей и диагностических данных. Каждый объект изолирован по сети, сайту, полной идентичности времени выполнения и области действия. Идентичность времени выполнения учитывает Blockstudio, настройки, WordPress, PHP, активную тему, активные плагины, логические источники обнаружения, контекст хоста и явные хеши зависимостей, переданные выполняющей операцию подсистемой.

Изменения содержимого, терминов, пользователей и метаданных аннулируют заполненные варианты полей, но не структурное обнаружение блоков и не скомпилированные ресурсы. Варианты обновляются отдельно с блокировкой по фиксированному пути сборки. Серия записей, например синхронизация переводов или импорт, объединяется: первая запись после периода затишья запускает немедленное обновление, а последняя запись в серии учитывается один раз по истечении тридцати секунд; интервал можно настроить с помощью blockstudio/cache/populate_debounce. Метаданные, которые WordPress записывает для служебных целей, например блокировку после редактирования записи, не считаются изменением; blockstudio/cache/populate_ignored_meta_keys дополняет этот список. Редактор всегда запрашивает актуальные варианты, поэтому этот интервал влияет только на кэшированные варианты, считываемые при отображении. Исходные файлы и параметры сборки, как обычно, аннулируют структурный кэш. Перезапись вариантов не приводит к повторному сканированию каталога кэша при каждом изменении содержимого; периодическая очистка по-прежнему удаляет осиротевшие временные файлы. Среды выполнения для разных языков остаются изолированными; наличие нескольких каталогов пространств имён кэша на многоязычном сайте само по себе не свидетельствует о промахе кэша.

Активность журнала SQLite в каталоге данных db блока не сбрасывает кэшированные метаданные блока. Изменения db.php, отслеживаемых исходных файлов, а также структуры исходных файлов и подкаталогов каталога данных по-прежнему аннулируют кэш.

При параллельной пересборке среды выполнения выбирается один сборщик. Остальные запросы ждут до пяти секунд, а затем повторно используют последние корректные метаданные блоков, если исходные файлы и необходимые скомпилированные ресурсы по-прежнему существуют. Холодный запрос без безопасных полезных данных возвращает HTTP 503 с Retry-After, вместо того чтобы запускать еще одну сборку. Фильтр blockstudio/cache/build_wait_budget задает время ожидания в миллисекундах как для структурной пересборки, так и для обновления вариантов. Если на хосте нет блокировок файлов с уведомлением о конкуренции, варианты обновляются без блокировки и все равно публикуются, поэтому следующий запрос попадет в кэш.

Неиспользуемые файлы .build.lock с блокировкой для отдельных ключей, оставшиеся от прежних версий, очищаются во всех пространствах имен кэша этого сайта с помощью WP-Cron: очистка начинается через пять минут после обновления и удаляет до 10,000 блокировок в минуту в пределах десятисекундного лимита. wp bs cache status сообщает об оставшемся количестве, wp bs cache cleanup немедленно обрабатывает очередь, а wp bs cache clear очищает кэш среды выполнения. Если плановое задание просрочено более чем на десять минут из-за того, что cron не срабатывает, раз в час запросы очищают ограниченное количество блокировок, чтобы очередь не зависла. Недавно созданные блокировки и блокировки, удерживаемые в данный момент, не трогаются; новые блокировки с фиксированными путями никогда не удаляются. После обработки очереди то же пакетное задание удаляет заброшенные пространства имен кэша, когда истекает срок namespaceGrace. Это выполняется не чаще раза в час для каждого сайта, а задание запускается ежедневно. Отсчет льготного периода начинается с первой проверки, обнаружившей, что пространство имен выведено из использования, а не с даты появления его последнего файла. Пространство имен, которое по-прежнему используется хотя бы в одной области, никогда не удаляется. Внутренняя очистка кэша не вызывает фильтры удаления вложений WordPress. На хостах с отключенным WP-Cron нужно продолжать запускать обычный обработчик запланированных задач cron; не удаляйте все активные файлы блокировок, чтобы очистить очередь.

Фильтр настройки blockstudio/settings/cache/path изменяет заданное значение. Для разрешения путей с учетом конфигурации развертывания фильтр blockstudio/cache/dir получает базовый каталог после разрешения пути:

PHP
add_filter('blockstudio/cache/dir', function (string $directory): string {
    return WP_CONTENT_DIR . '/cache/blockstudio';
});

Хосты, где идентификатор арендатора отличается от сетевых идентификаторов или идентификаторов блогов WordPress, могут отфильтровать blockstudio/cache/site_key. Результат очищается и используется только как сегмент каталога. blockstudio/cache/context остается подходящим местом для сериализуемого варианта среды выполнения, который должен менять идентичность объектов.

themeDefaults

Параметр Тип По умолчанию Описание
titleTag boolean false Включить поддержку заголовка title в теме WordPress
suppressDirectoryUpdates boolean false Удалить активные дочернюю и родительскую темы из результатов обновления каталога

Для шаблонов по-прежнему используется существующий Blockstudio\Patterns API; эти значения по умолчанию не добавляют альтернативные фасады страниц или шаблонов.

performance

Профиль compat не меняет поведение универсальных WordPress. Параметры speed и strict включают одинаковые параметры внешнего интерфейса по умолчанию; значение каждого дочернего параметра можно переопределить.

Настройки включения функций служат переключателями регистрации. Если дополнительная функция false, Blockstudio не подключает ее обратные вызовы внешнего интерфейса, панели администратора, редактора, REST и запланированных заданий. Если после использования функции отключить Early Serve или запланированное разогревание, принадлежащие им ресурсы очищаются один раз; последующие запросы ничего не делают.

Параметр Тип Значение по умолчанию для совместимости Значение по умолчанию для скорости/строгого режима Описание
profile string "compat" Не применимо compat, speed или strict
wordpress.headNoise boolean false true Удалить общее обнаружение head и вывод эмодзи
wordpress.embeds boolean false true Удалить обнаружение oEmbed и скрипты хоста
wordpress.xmlrpc boolean false true Отключить XML-RPC и уведомления pingback
wordpress.editor boolean false true Отключить удаленные способы обнаружения редактора
wordpress.frontendAssets boolean false true Удалить общие ресурсы интерфейса ядра
wordpress.media boolean false true Применить настройки вывода изображений
wordpress.heartbeat boolean false true Ограничить частоту Heartbeat вне редакторов
preload.links string "off" "intent" Предварительно загружать документы с того же источника после действия пользователя
media.lazy boolean false true Использовать загрузчик изображений Blockstudio
media.skeleton boolean false true Показывать встроенный скелетон загрузки
media.metadata boolean false true Объявить использование assets/media.json
media.rootMargin string "300px" "300px" Отступ пересечения для отложенной загрузки
measurement.enabled boolean false false Включить API измерения во время выполнения
measurement.queryMonitor boolean false false Включать запросы длительностью не менее 50ms
measurement.headers boolean false false Отправлять заголовки с профилем и хешем конфигурации
measurement.timings boolean false false Отправлять заголовок с прошедшим временем выполнения
staticPrerender.enabled boolean false false Включить безопасное для анонимных пользователей кэширование HTML
staticPrerender.ttl integer 86400 86400 Максимальный срок хранения документа в кэше в секундах
staticPrerender.invalidate string "signature" "signature" Использовать идентификатор signature или инкрементный graph
staticPrerender.earlyServe boolean false false Отдавать безопасные результаты до запуска WordPress
staticPrerender.serveLoggedIn boolean false false Разрешить пользователям использовать результаты из кэша, но не добавлять их туда
staticPrerender.dynamicPaths array [] [] Префиксы путей, которые должны оставаться динамическими
staticPrerender.replayHeaders array ["Link"] ["Link"] Заголовки ответа, сохраняемые и отправляемые при выдаче результатов из кэша
staticPrerender.warm.enabled boolean false false Включить постоянную очередь прогрева по расписанию
staticPrerender.warm.interval integer 3600 3600 Интервал прогрева в секундах
staticPrerender.warm.concurrency integer 2 2 Максимальное число заданий за один проход прогрева
staticPrerender.warm.transport string "http" "http" Использовать http или предоставленный хостом рендерер internal

Статическая предварительная отрисовка отключена, если ее явно не включить. При выключенном главном переключателе хуки запросов предварительной отрисовки не регистрируются, а отключенные переключатели earlyServe и warm.enabled не регистрируют хуки администрирования или cron. Режим сигнатур использует дешевую активированную идентификацию при обычных запросах. Режим графа предназначен для явных сборок: он записывает зависимости исходников для каждой страницы, поэтому изменение одной страницы не инвалидирует несвязанные документы. Подробнее о прогреве, развертывании, ранней выдаче и безопасности см. в разделе Статическая предварительная отрисовка.

Измерения доступны программно:

PHP
use Blockstudio\Performance_Measurement;

$snapshot = Performance_Measurement::snapshot();

Когда заголовки включены, Blockstudio отправляет X-Blockstudio-Performance-Profile, X-Blockstudio-Performance-Config и, при необходимости, X-Blockstudio-Performance-Time. Действие blockstudio/performance/measurement_enabled получает разрешенные параметры среды выполнения.

Параметры media управляют bs_media_image(), манифестом assets/media.json и ленивым загрузчиком внешнего интерфейса. В разделе Медиа описаны вспомогательная функция, построитель манифеста и поведение загрузчика.

content

Параметр Тип Значение по умолчанию Описание
enabled boolean false Включить конфигурацию Content Sync
id string "default" Пространство имен набора контента, сохраняемое в синхронизированных сущностях
path string "content" Каталог файлов контента относительно темы
includePageSyncManaged boolean false Включать записи под управлением Page Sync, не владея их содержимым
authors string "ignore" Обработка авторов (ignore или login существующего пользователя)
postTypes array [] Разрешенные типы записей
meta.include array [] Шаблоны glob для синхронизации ключей метаданных
meta.exclude array ["_edit_lock", "_edit_last", "_wp_old_slug"] Шаблоны glob для исключения ключей метаданных
meta.references object {} Заданные ссылки на метаданные, преобразуемые между идентификаторами и UID
taxonomies array [] Разрешенные зарегистрированные таксономии для терминов и связей
media string "manifest" Поведение ссылок на вложения (manifest или none)

Content Sync управляется через wp bs content и экспортирует разрешенные записи, postmeta и объявленные ссылки в переносимые файлы. Описание процесса и формата файлов см. в разделе Синхронизация контента.

editor

Параметр Тип Значение по умолчанию Описание
formatOnSave boolean false Форматировать block.json при сохранении
assets array [] Дополнительные ресурсы для загрузки в редакторе
markup boolean false Включить редактирование разметки

tailwind

Параметр Тип Значение по умолчанию Описание
enabled boolean false Включить компиляцию Tailwind CSS
config string "" Конфигурация Tailwind v4 CSS-first

Описание поведения компиляции и формата конфигурации CSS-first см. в разделе Tailwind CSS.

blockTags

Параметр Тип Значение по умолчанию Описание
enabled boolean false Включить отображение тегов bs: на уровне страницы в содержимом записей и областях виджетов
allow array [] Список разрешенных шаблонов имен блоков; поддерживаются подстановочные знаки fnmatch()
deny array [] Список запрещенных шаблонов имен блоков; имеет приоритет над allow
prefixes object {} Префикс для сокращений пространства имен; каждое значение — пространство имен или упорядоченный массив

Отображение тегов на уровне шаблонов всегда включено; эти параметры управляют заменой на уровне страницы. Синтаксис тегов и правила их разрешения см. в разделе Отображение.

ui

Параметр Тип Значение по умолчанию Описание
enabled boolean false Зарегистрировать встроенные компоненты bsui/* UI и демонстрационные приложения app/*

blockEditor

Параметр Тип Значение по умолчанию Описание
disableLoading boolean false Отключить загрузку блоков в редакторе
enhance boolean false Включить интерактивные элементы наведения и выбора блока Blockstudio
cssClasses array [] URL таблиц стилей, из которых извлекаются классы CSS для автодополнения поля классов
cssVariables array [] URL таблиц стилей, из которых извлекаются переменные CSS для автодополнения поля кода

blockEditor.blocks

Используйте blockEditor.blocks для настройки политики вставки блоков во всем проекте. Параметры allow и deny принимают имена блоков и шаблоны с подстановочными знаками, например core/*.

JSON
{
  "blockEditor": {
    "blocks": {
      "allow": ["core/*", "my-theme/*"],
      "deny": ["core/embed", "core/freeform"],
      "directory": false,
      "categories": {
        "rename": {
          "text": "Writing",
          "design": "Layout"
        },
        "order": ["my-theme", "text", "media"]
      },
      "legacyWidgets": {
        "hide": ["archives", "calendar"]
      }
    }
  }
}

blocks.styles.deny отменяет регистрацию стилей, зарегистрированных через реестр стилей блоков WordPress’PHP:

JSON
{
  "blockEditor": {
    "blocks": {
      "styles": {
        "deny": {
          "my-theme/card": ["outline"],
          "my-theme/media": ["framed"]
        }
      }
    }
  }
}

blockEditor.patterns

Используйте blockEditor.patterns, чтобы отключить глобальные источники шаблонов и фильтровать их категории.

JSON
{
  "blockEditor": {
    "patterns": {
      "core": false,
      "remote": false,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "deny": ["gallery"],
        "rename": {
          "featured": "Featured Layouts"
        },
        "order": ["featured", "buttons"]
      }
    }
  }
}

blockEditor.media

Используйте blockEditor.media для настройки глобальной политики вставки медиафайлов.

JSON
{
  "blockEditor": {
    "media": {
      "openverse": false,
      "imageSizes": {
        "allow": ["thumbnail", "large"],
        "deny": ["medium_large"]
      }
    }
  }
}

dev

Параметр Тип Значение по умолчанию Описание
grab.enabled boolean false Включить инструмент выбора элементов на внешнем интерфейсе
perf boolean false Включить профилировщик производительности при каждой загрузке страницы
canvas.enabled boolean false Включить полотно
canvas.adminBar boolean true Показывать панель администратора WordPress при просмотре полотна

githooks

Параметр Тип Значение по умолчанию Описание
commit boolean false Создать хук предварительной фиксации только для анализа при запуске blockstudio-githooks sync

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

phpstan

Параметр Тип Значение по умолчанию Описание
preset string "base" Набор параметров анализа, если он не выбран в командной строке: base, theme, extreme-theme или wordpress-render
configuration string "" Конфигурация проекта PHPStan, включаемая вместе с набором параметров; определяется по blockstudio.json
roots array ["."] Корневые каталоги темы, анализируемые основной командой
excludePaths array [] Дополнительные исключения сканера относительно каждого настроенного корневого каталога
maxFiles integer 10000 Максимальное число файлов, проверяемых сканером темы
blockTags object {} Сопоставления элементов, псевдонимы тегов и scanPhp для правила тега блока

Эти параметры задают конфигурацию основной команды blockstudio-phpstan. Наборы параметров, уровни и подключение описаны в разделе PHPStan.

ai

Параметр Тип Значение по умолчанию Описание
enableContextGeneration boolean false Создать общий файл контекста с блоками, настройками, схемами и документацией для инструментов на базе LLM

Указатель на документацию и полный сгенерированный текст см. в разделе Интеграция с ИИ.

UI Компоненты

Включайте и комбинируйте встроенные бессерверные компоненты UI, появившиеся в версии Blockstudio 7.3.