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

Регистрация ресурсов

Blockstudio автоматически подключает все файлы с окончаниями .css, .scss и .js при отображении блока на странице. Поведение подключения ресурсов можно задать с помощью одного из следующих имён файлов. * — это шаблон, который можно заменить любой строкой по вашему выбору.

В файлах CSS и SCSS блока %selector% раскрывается в ограниченный областью блока класс-обёртку. Это позволяет выбрать тот же элемент, к которому применяется bs_get_scoped_class(), даже если файл не является ресурсом с ограниченной областью действия.

Шаблон Поведение
*.(s)css Подключается тег <link> в редакторе и на сайте
*.inline.(s)css Содержимое подключается во встроенном теге <style> в редакторе и на сайте
*.editor.(s)css Подключается тег <link> только в редакторе
*.scoped.(s)css Содержимое с ограниченной областью действия подключается во встроенном теге <style> в редакторе и на сайте
*.js Подключается тег <script> в редакторе и на сайте
*.inline.js Содержимое подключается во встроенном теге <script> в редакторе и на сайте
*.editor.js Подключается тег <script> только в редакторе
*.view.js Подключается тег <script> только на сайте

Примечание

Обозначения с дефисом (*-inline.css, *-editor.css и т. д.) по-прежнему поддерживаются для обратной совместимости, но считаются устаревшими. Для новых блоков используйте обозначения с точкой.

Встроенные ресурсы

У встроенных стилей и скриптов есть важное преимущество: они выводятся непосредственно на странице как теги style или script. Это может ускорить загрузку, поскольку не приходится выполнять дополнительные запросы.

  • Файлы .js встраиваются в конец body
  • Файлы .(s)css встраиваются в конец head
  • Каждый файл встраивается только один раз

Встраивание небольших таблиц стилей

По умолчанию файл *.(s)css подключается отдельно, что означает один запрос на файл. Настройка assets.inlineLimit вместо этого встраивает небольшие таблицы стилей, следуя правилу, которое WordPress применяет к собственным стилям: внешние таблицы стилей блоков на странице сортируются от меньшей к большей и выводятся как <style>, пока их общий размер не превысит лимит. Для всех остальных файлов сохраняется тег <link>.

JSON
{
  "assets": {
    "inlineLimit": 40000
  }
}

Лимит задается в байтах, а значение 0 по умолчанию отключает эту функцию. Он измеряет размер скомпилированного файла, который загрузил бы <link>; при включенном assets.minify.css файл минифицируется. От размера зависит только выбор между <link> и <style>. Каждый тег остается на месте, где находился бы <link>, поэтому порядок загрузки и каскад не меняются. Элемент сохраняет свой id.

Настройка не применяется к файлам *.inline.(s)css и *.scoped.(s)css, которые всегда встраиваются, к ресурсам редактора и панели администратора, а также к таблицам стилей, извлеченным из импортированных модулей JavaScript. Глобальные таблицы стилей учитываются так же, как таблицы стилей блоков. Файл остается подключенным, если встраивание изменило бы его:

  • В нем содержится относительный URL в url() или @import, который разрешается относительно таблицы стилей при подключении и относительно страницы при встраивании. Допустимы абсолютные пути, полные URL, URI data: и фрагменты #.
  • В нем используется image-set() или содержится закрывающая последовательность </style.
  • В нем содержатся экранированные символы CSS, открывающий комментарий HTML или объявление @charset. В целях предосторожности такие файлы остаются подключенными, чтобы избежать изменения URL или разбора документа.

Используйте фильтр настройки, чтобы изменить лимит PHP:

PHP
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);

Встроенный CSS становится частью HTML страницы. После изменения таблицы стилей нужно очистить кэш страницы, а браузер не может кэшировать эти байты между страницами, поэтому лимит задан для общего объема на страницу.

Область действия

Стили с ограниченной областью действия также встраиваются, но к ним добавляется ID, уникальный для каждого блока. Используйте функцию bs_get_scoped_class, чтобы добавить класс в шаблон.

PHP
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
  <h1 class="hero__title">Scope me!</h1>
</section>
CSS
%selector% {
  --hero-gap: var(--wp--preset--spacing--space-10);
}

%selector%.hero {
  border-bottom: 1px solid currentColor;
}

.hero__title {
  color: red;
}

В результате получится следующий стиль с ограниченной областью действия:

HTML
<style>
  .bs-62df71e6cc9a {
    --hero-gap: var(--wp--preset--spacing--space-10);
  }

  .bs-62df71e6cc9a.hero {
    border-bottom: 1px solid currentColor;
  }

  .bs-62df71e6cc9a .hero__title {
    color: red;
  }
</style>

<section class="hero bs-62df71e6cc9a">
  <h1 class="hero__title">Scope me!</h1>
</section>

Обычные селекторы в файле с ограниченной областью действия по-прежнему выбирают дочерние элементы обёртки. Используйте %selector%, чтобы задать стиль самой обёртке.

Глобальные ресурсы

Помимо ресурсов для отдельных блоков, можно подключать глобальные ресурсы, доступные на всех страницах независимо от наличия блоков. Чтобы подключить глобальный ресурс, добавьте префикс global- к имени файла. В сочетании с ним можно использовать любой из суффиксов (e.g. -inline).

Возможные сочетания:

  • global-styles.(s)css
  • global-styles.inline.(s)css
  • global-styles.editor.(s)css
  • global-styles.scoped.(s)css
  • global-scripts.js
  • global-scripts.inline.js
  • global-scripts.editor.js
  • global-scripts.view.js

Административная панель

Ресурсы администратора подключаются только в панели администратора WordPress. Префикс admin- используется для обозначения ресурсов администратора.

  • admin-styles.(s)css
  • admin-scripts.js

Редактор блоков

Ресурсы редактора блоков подключаются только в редакторе блоков. Для их обозначения используется префикс block-editor-.

  • block-editor-styles.(s)css
  • block-editor-scripts.js

Примечание

Если WordPress отключает iframe редактора, поскольку клиентский блок зарегистрирован с apiVersion ниже 3, холст редактора и интерфейс администратора WordPress используют один документ. Для глобальных скриптов и скриптов редактора, работающих с window, document, body, событиями колёсика мыши или прокруткой документа, следует предусмотреть проверку на body.block-editor-page или исключить области редактора WordPress, например .interface-complementary-area и .interface-navigable-region.

Порядок загрузки

На сайте при включённых автоматическом подключении ресурсов и буферизации вывода Blockstudio добавляет теги CSS и <link> блока, а также тег <style> в буферизованную страницу непосредственно перед закрывающим тегом </head>, вместо регистрации через wp_enqueue_style(). Поэтому CSS блока следует после таблиц стилей, которые WordPress уже вывел в head, включая стили темы и плагинов, подключённые через wp_enqueue_style(), независимо от приоритета подключения и зависимостей. Для ресурсов администратора и block-editor- используется система подключения ресурсов WordPress.

Для правил с одинаковыми важностью, уровнем каскада и специфичностью таблица стилей блока имеет приоритет над таблицей стилей темы. Чтобы изменить это, повысьте специфичность правила темы или добавьте таблицу стилей темы в head Blockstudio, созданный с помощью фильтра blockstudio/render/head. Фильтр добавляет содержимое после ресурсов блока. Удалите таблицу стилей из WordPress, чтобы она не загружалась дважды.

PHP
add_action('wp_enqueue_scripts', function() {
  wp_dequeue_style('theme-overrides');
}, 100);

add_filter('blockstudio/render/head', function($head) {
  return $head . '<link rel="stylesheet" href="' . esc_url(get_theme_file_uri('overrides.css')) . '">';
});

Фильтр head срабатывает, только когда Blockstudio буферизует страницу. Буферизация отключена в предварительном просмотре в Customizer и когда blockstudio/buffer/enabled возвращает false. bs_is_buffering() сообщает, какой случай действует, поэтому тема может добавить таблицу стилей через фильтр, когда страница буферизуется, и добавить ее в очередь через WordPress в остальных случаях. Ответ доступен с момента wp_enqueue_scripts и является false до template_redirect.

PHP
add_action('wp_enqueue_scripts', function() {
  $url = get_theme_file_uri('overrides.css');

  if (bs_is_buffering()) {
    add_filter('blockstudio/render/head', function($head) use ($url) {
      return $head . '<link rel="stylesheet" href="' . esc_url($url) . '">';
    });
    return;
  }

  wp_enqueue_style('theme-overrides', $url);
});

Используйте blockstudio/buffer/output, если нужно изменить порядок элементов в итоговом документе.

Отключение подключения ресурсов

Автоматическое подключение ресурсов можно отключить с помощью настройки assets/enqueue. Это пригодится, если вы хотите самостоятельно управлять подключением всех ресурсов.

PHP
add_filter('blockstudio/settings', function($settings) {
  $settings['assets']['enqueue'] = false;
  return $settings;
});

Для отдельного блока

Если шаблон блока возвращает пустое значение, Blockstudio не подключит ресурсы для этого блока. Этот способ удобен, когда подключение нужно отключить при выполнении определённого условия.

PHP

PHP
<?php
  if ( !$a['slides'] ) {
    // or return '';
    return false;
  }
?>

<div>my slider</div>

Twig

Twig
{% if not a.slides %}
  <div>my slider</div>
{% endif %}