Assets registrieren
Blockstudio reiht automatisch alle Dateien mit den Endungen .css, .scss und .js ein, wenn dein Block auf einer Seite verwendet wird. Mit den folgenden Dateinamen kannst du festlegen, wie Assets eingereiht werden. * ist ein Platzhalter, den du durch eine beliebige Zeichenfolge ersetzen kannst.
In Blockdateien CSS und SCSS wird %selector% zur umschließenden Klasse des Blocks. Damit kannst du dasselbe Element ansprechen, das auch bs_get_scoped_class() erhält, selbst wenn die Datei kein bereichsbezogenes Asset ist.
| Muster | Verhalten |
|---|---|
*.(s)css |
Wird im Editor und im Frontend als <link>-Tag eingereiht |
*.inline.(s)css |
Inhalt wird im Editor und im Frontend in einem Inline-<style>-Tag eingereiht |
*.editor.(s)css |
Wird nur im Editor als <link>-Tag eingereiht |
*.scoped.(s)css |
Bereichsbezogener Inhalt wird im Editor und im Frontend in einem Inline-<style>-Tag eingereiht |
*.js |
Wird im Editor und im Frontend als <script>-Tag eingereiht |
*.inline.js |
Inhalt wird im Editor und im Frontend in einem Inline-<script>-Tag eingereiht |
*.editor.js |
Wird nur im Editor als <script>-Tag eingereiht |
*.view.js |
Wird nur im Frontend als <script>-Tag eingereiht |
Hinweis
Die Bindestrichschreibweise (
*-inline.css,*-editor.cssusw.) wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, ist aber veraltet. Verwende für neue Blöcke die Punktnotation.
Inline
Inline-Styles und -Skripte werden direkt als Style- oder Script-Tags in die Seite eingefügt. Das kann die Ladezeiten verkürzen, da dadurch zusätzliche Anfragen entfallen.
.js-Dateien werden am Ende des Bodys inline eingefügt.(s)css-Dateien werden am Ende des Heads inline eingefügt- Jede Datei wird nur einmal inline eingefügt
Kleine Stylesheets inline einfügen
Eine *.(s)css-Datei wird standardmäßig verknüpft, was eine Anfrage pro Datei kostet. Die Einstellung assets.inlineLimit gibt stattdessen kleine Stylesheets inline aus und folgt dabei der Regel, die WordPress auf die eigenen Stile anwendet: Die externen Block-Stylesheets einer Seite werden vom kleinsten zum größten genommen und als <style> ausgegeben, solange ihre laufende Gesamtsumme innerhalb des Limits bleibt. Für jede andere Datei bleibt ihr <link>-Tag erhalten.
{
"assets": {
"inlineLimit": 40000
}
}
Das Limit wird in Bytes angegeben; 0, der Standardwert, deaktiviert das Verhalten. Gemessen wird die kompilierte Datei, die <link> laden würde, bei aktiviertem assets.minify.css minifiziert. Nur die Entscheidung zwischen <link> und <style> hängt von der Größe ab. Jedes Tag bleibt dort, wo <link> gestanden hätte, sodass sich Ladereihenfolge und Kaskade nicht ändern. Das Element behält sein id.
Die Einstellung gilt nicht für *.inline.(s)css– und *.scoped.(s)css-Dateien, die immer inline eingefügt werden, nicht für Editor- und Admin-Assets und auch nicht für Stylesheets, die aus importierten JavaScript-Modulen extrahiert wurden. Globale Stylesheets zählen wie Block-Stylesheets. Eine Datei bleibt verknüpft, wenn das Inline-Einfügen sie verändern würde:
- Sie enthält einen relativen URL in
url()oder@import, der bei einer Verknüpfung relativ zum Stylesheet und bei Inline-Einfügung relativ zur Seite aufgelöst wird. Absolute Pfade, vollständige URLs,data:-URIs und#-Fragmente sind unproblematisch. - Sie verwendet
image-set()oder enthält eine schließende</style-Sequenz. - Sie enthält CSS-Escapes, einen öffnenden HTML-Kommentar oder eine
@charset-Deklaration. Diese Dateien bleiben vorsichtshalber verknüpft, damit sich URL oder das Parsen des Dokuments nicht ändern.
Verwende den Einstellungsfilter, um das Limit ab PHP zu ändern:
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);
Inline eingefügtes CSS wird Teil des HTML der Seite. Nach einer Änderung am Stylesheet muss der Seitencache geleert werden, und der Browser kann diese Bytes nicht seitenübergreifend zwischenspeichern. Deshalb gilt das Limit insgesamt pro Seite.
Bereichsbezogen
Bereichsbezogene Styles werden ebenfalls inline eingefügt, erhalten jedoch einen Präfix mit einer ID, die für jeden Block eindeutig ist. Verwende die Funktion bs_get_scoped_class, um die Klasse zu deiner Vorlage hinzuzufügen.
<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;
}
Das obige Beispiel erzeugt den folgenden bereichsbezogenen Style:
<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>
Normale Selektoren in einer bereichsbezogenen Datei sprechen weiterhin die Nachfahren des umschließenden Bereichs an. Verwende %selector%, wenn du den umschließenden Bereich selbst gestalten möchtest.
Global
Zusätzlich zu blockspezifischen Assets kannst du auch globale Assets einreihen, die auf allen Seiten verfügbar sind, unabhängig davon, ob ein Block vorhanden ist. Dazu fügst du den Präfix global- zum Dateinamen hinzu. Alle Suffixe (e.g. -inline) lassen sich damit kombinieren.
Mögliche Kombinationen:
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
Admin
Admin-Assets werden nur im Adminbereich von WordPress eingereiht. Der Präfix admin- kennzeichnet Admin-Assets.
admin-styles.(s)cssadmin-scripts.js
Block-Editor
Assets für den Block-Editor werden nur im Block-Editor eingereiht. Der Präfix block-editor- kennzeichnet Assets für den Block-Editor.
block-editor-styles.(s)cssblock-editor-scripts.js
Hinweis
Wenn WordPress das Editor-Iframe deaktiviert, weil ein clientseitiger Block mit
apiVersionunter 3 registriert ist, verwenden die Editor-Leinwand und die WordPress-Adminoberfläche dasselbe Dokument. Globale Skripte oder Editor-Skripte, die anwindow,document,body, Wheel-Ereignisse oder das Scrollen des Dokuments gebunden sind, sollten aufbody.block-editor-pageprüfen oder WordPress-Editorbereiche wie.interface-complementary-areaund.interface-navigable-regionausschließen.
Ladereihenfolge
Im Frontend fügt Blockstudio bei aktivierter automatischer Asset-Einreihung und Ausgabepufferung die Block-Tags CSS <link> und <style> direkt vor dem schließenden </head>-Tag in die gepufferte Seite ein, statt sie mit wp_enqueue_style() zu registrieren. Das Block-CSS kommt daher nach den Stylesheets, die WordPress bereits im Head ausgegeben hat, einschließlich Theme- und Plugin-Styles, die mit wp_enqueue_style() eingereiht wurden, unabhängig von ihrer Einreihungspriorität oder ihren Abhängigkeiten. Admin- und block-editor--Assets verwenden stattdessen das Einreihungssystem von WordPress.
Bei Regeln mit gleicher Wichtigkeit, Cascade-Ebene und Spezifität hat das Block-Stylesheet Vorrang vor einem Theme-Stylesheet. Um das zu ändern, erhöhst du entweder die Spezifität der Theme-Regel oder hängst das Theme-Stylesheet an den Head an, den Blockstudio mit dem blockstudio/render/headFilter erzeugt. Vom Filter hinzugefügter Inhalt wird nach den Block-Assets platziert. Entferne das Stylesheet auch aus WordPress, damit es nicht doppelt geladen wird.
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')) . '">';
});
Der head-Filter wird nur ausgeführt, wenn Blockstudio die Seite puffert. In der Customizer-Vorschau und wenn blockstudio/buffer/enabled false zurückgibt, ist das Puffern deaktiviert. bs_is_buffering() zeigt dir, welcher Fall vorliegt. So kann ein Theme sein Stylesheet über den Filter anhängen, wenn die Seite gepuffert wird, und es andernfalls mit WordPress einreihen. Die Antwort ist ab wp_enqueue_scripts verfügbar und liegt vor template_redirect bei false.
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);
});
Verwende blockstudio/buffer/output, wenn du das endgültige Dokument anders anordnen musst.
Einreihung deaktivieren
Die automatische Einreihung von Assets lässt sich mit der Einstellung assets/enqueue deaktivieren. Das ist nützlich, wenn du die Einreihung aller Assets selbst verwalten möchtest.
add_filter('blockstudio/settings', function($settings) {
$settings['assets']['enqueue'] = false;
return $settings;
});
Pro Block
Wenn eine Blockvorlage nichts zurückgibt, reiht Blockstudio keine Assets für diesen Block ein. So lässt sich die Einreihung bei erfüllten Bedingungen deaktivieren.
PHP
<?php
if ( !$a['slides'] ) {
// or return '';
return false;
}
?>
<div>my slider</div>
Twig
{% if not a.slides %}
<div>my slider</div>
{% endif %}