Реєстрація ресурсів
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>.
{
"assets": {
"inlineLimit": 40000
}
}
Ліміт указується в байтах, а значення 0 за замовчуванням вимикає цю поведінку. Вимірюється скомпільований файл, який завантажив би <link>, зі стисненням, якщо ввімкнено assets.minify.css. Від розміру залежить лише вибір між <link> і <style>. Кожен тег залишається на місці, де був би <link>, тому порядок завантаження та каскад не змінюються. Елемент зберігає свій id.
Налаштування не застосовується до файлів *.inline.(s)css і *.scoped.(s)css, які завжди вбудовуються, до ресурсів редактора й адміністративної панелі або до таблиць стилів, видобутих з імпортованих модулів JavaScript. Глобальні таблиці стилів враховуються так само, як таблиці стилів блоків. Файл залишається підключеним, якщо вбудовування змінило б його:
- Він містить відносний URL в
url()або@import, який відносно таблиці стилів, коли вона підключена, і відносно сторінки, коли її вбудовано. Абсолютні шляхи, повні URL-адреси, URIdata:і фрагменти#допустимі. - У ньому використовується
image-set()або є послідовність закриття</style. - Він містить екранування CSS, відкривач коментаря HTML або декларацію
@charset. Такі файли задля обережності залишаються підключеними, щоб не ризикувати зміною URL або розбором документа.
Використовуйте фільтр налаштування, щоб змінити ліміт з PHP:
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);
Вбудований CSS стає частиною HTML сторінки. Після зміни таблиці стилів потрібно очистити кеш сторінки, а браузер не може кешувати ці байти між сторінками, тому ліміт є загальним для кожної сторінки.
Задана область дії
Стилі із заданою областю дії також додаються вбудовано, але отримують префікс із ID, унікальним для кожного блока. Використовуйте функцію bs_get_scoped_class, щоб додати клас до шаблону.
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
<h1 class="hero__title">Scope me!</h1>
</section>
%selector% {
--hero-gap: var(--wp--preset--spacing--space-10);
}
%selector%.hero {
border-bottom: 1px solid currentColor;
}
.hero__title {
color: red;
}
Наведений вище приклад створить такий стиль із заданою областю дії:
<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)cssglobal-styles.inline.(s)cssglobal-styles.editor.(s)cssglobal-styles.scoped.(s)cssglobal-scripts.jsglobal-scripts.inline.jsglobal-scripts.editor.jsglobal-scripts.view.js
Адміністрування
Адміністративні ресурси додаються в чергу лише в адмінрозділі WordPress. Префікс admin- використовується для визначення адміністративних ресурсів.
admin-styles.(s)cssadmin-scripts.js
Редактор блоків
Ресурси редактора блоків додаються в чергу лише в редакторі блоків. Для їх визначення використовується префікс block-editor-.
block-editor-styles.(s)cssblock-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, щоб вона не завантажувалася двічі.
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.
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. Це стане в пригоді, якщо ви хочете самостійно керувати додаванням усіх ресурсів у чергу.
add_filter('blockstudio/settings', function($settings) {
$settings['assets']['enqueue'] = false;
return $settings;
});
Для окремого блока
Якщо шаблон блока нічого не повертає, Blockstudio не додаватиме ресурси в чергу для цього блока. Це зручно для вимкнення додавання в чергу за певної умови.
PHP
<?php
if ( !$a['slides'] ) {
// or return '';
return false;
}
?>
<div>my slider</div>
Twig
{% if not a.slides %}
<div>my slider</div>
{% endif %}