Перейти до вмісту

Реєстрація ресурсів

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 %}