Registro de recursos
Blockstudio añadirá automáticamente todos los archivos que terminen en .css, .scss y .js cuando se use su bloque en una página. Puede definir cómo se añaden los recursos usando uno de los siguientes nombres de archivo. * es un comodín que puede sustituir por cualquier texto que elija.
Dentro de los archivos CSS y SCSS del bloque, %selector% se expande a la clase contenedora del bloque con ámbito propio. Esto permite seleccionar el mismo elemento que recibe bs_get_scoped_class(), aunque el archivo no sea un recurso con ámbito propio.
| Patrón | Comportamiento |
|---|---|
*.(s)css |
Se añade como etiqueta <link> en el editor y en la interfaz |
*.inline.(s)css |
Añade el contenido en una etiqueta <style> en línea en el editor y en la interfaz |
*.editor.(s)css |
Se añade como etiqueta <link> solo en el editor |
*.scoped.(s)css |
Añade el contenido con ámbito propio en una etiqueta <style> en línea en el editor y en la interfaz |
*.js |
Se añade como etiqueta <script> en el editor y en la interfaz |
*.inline.js |
Añade el contenido en una etiqueta <script> en línea en el editor y en la interfaz |
*.editor.js |
Se añade como etiqueta <script> solo en el editor |
*.view.js |
Se añade como etiqueta <script> solo en la interfaz |
Nota
La notación con guiones (
*-inline.css,*-editor.css, etc.) sigue siendo compatible con versiones anteriores, pero está obsoleta. Use la notación con puntos para los bloques nuevos.
En línea
Los estilos y scripts en línea tienen la gran ventaja de renderizarse directamente como etiquetas de estilo o script dentro de la página. Esto puede mejorar los tiempos de carga, ya que evita solicitudes adicionales que de otro modo habría que realizar.
- Los archivos
.jsse insertan al final del cuerpo - Los archivos
.(s)cssse insertan al final del encabezado - Cada archivo se inserta una sola vez
Hojas de estilo pequeñas en línea
Por defecto, se enlaza un archivo *.(s)css, lo que supone una solicitud por archivo. La opción assets.inlineLimit imprime en línea las hojas de estilo pequeñas, siguiendo la regla que WordPress core aplica a sus propios estilos: las hojas de estilo externas de los bloques de una página se ordenan de menor a mayor y se imprimen como <style> mientras el total acumulado no supere el límite. Todos los demás archivos conservan su etiqueta <link>.
{
"assets": {
"inlineLimit": 40000
}
}
El límite se expresa en bytes y 0, el valor predeterminado, desactiva este comportamiento. Mide el archivo compilado que cargaría <link>, minificado si assets.minify.css está activado. Solo la elección entre <link> y <style> depende del tamaño. Cada etiqueta permanece donde habría estado <link>, por lo que el orden de carga y la cascada no cambian. El elemento conserva su id.
La opción no se aplica a los archivos *.inline.(s)css y *.scoped.(s)css, que siempre se insertan en línea; tampoco se aplica a los recursos del editor y de administración ni a las hojas de estilo extraídas de los módulos JavaScript importados. Las hojas de estilo globales cuentan como hojas de estilo de bloques. Un archivo sigue enlazado siempre que insertarlo en línea pudiera cambiarlo:
- Contiene un URL relativo en
url()o@import, que se resuelve respecto a la hoja de estilo cuando está enlazada y respecto a la página cuando está en línea. Las rutas absolutas, las URL completas, los URIdata:y los fragmentos#son válidos. - Usa
image-set()o contiene una secuencia de cierre</style. - Contiene escapes CSS, un inicio de comentario HTML o una declaración
@charset. Estos archivos siguen enlazados por precaución, para evitar alterar URL o el análisis del documento.
Use el filtro de opciones para cambiar el límite de PHP:
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);
El CSS insertado en línea pasa a formar parte del HTML de la página. Hay que purgar la caché de la página después de modificar una hoja de estilo, y el navegador no puede almacenar esos bytes en caché entre páginas; por eso el límite se aplica al total por página.
Con ámbito propio
Los estilos con ámbito propio también se insertan en línea, pero llevan como prefijo un ID único para cada bloque. Use la función bs_get_scoped_class para añadir la clase a su plantilla.
<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;
}
Lo anterior generará el siguiente estilo con ámbito propio:
<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>
Los selectores normales dentro de un archivo con ámbito propio siguen seleccionando los elementos descendientes del contenedor. Use %selector% si quiere aplicar estilos al propio contenedor.
Global
Además de los recursos específicos de cada bloque, también es posible añadir recursos globales, disponibles en todas las páginas, haya bloques presentes o no. Para añadir un recurso global, incluya el prefijo global- en el nombre del archivo. Puede combinarlo con cualquiera de los sufijos (e.g. -inline).
Estas son las combinaciones posibles:
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
Administración
Los recursos de administración solo se añaden en el área de administración de WordPress. El prefijo admin- sirve para definirlos.
admin-styles.(s)cssadmin-scripts.js
Editor de bloques
Los recursos del editor de bloques solo se añaden en el editor de bloques. El prefijo block-editor- sirve para definirlos.
block-editor-styles.(s)cssblock-editor-scripts.js
Nota
Si WordPress desactiva el iframe del editor porque se registra un bloque del lado del cliente con
apiVersionmenor que 3, el lienzo del editor y la interfaz de administración de WordPress comparten el mismo documento. Los scripts globales o del editor que se vinculen awindow,document,body, eventos de rueda o el desplazamiento del documento deben protegerse frente abody.block-editor-pageo excluir regiones del editor WordPress, como.interface-complementary-areay.interface-navigable-region.
Orden de carga
En la interfaz, con la inclusión automática de recursos y el almacenamiento temporal de salida activados,
Blockstudio añade las etiquetas CSS <link> y <style> de sus bloques a la página almacenada en búfer
justo antes de la etiqueta de cierre </head>, en lugar de registrarlas con
wp_enqueue_style(). Por ello, CSS del bloque aparece después de las hojas de estilo que
WordPress ya ha imprimido en el encabezado, incluidas las hojas de estilo del tema y de los plugins
añadidas con wp_enqueue_style(), independientemente de su prioridad o dependencias de inclusión. Los recursos de administración y de block-editor- usan en su lugar el sistema de inclusión de WordPress.
Para reglas con la misma importancia, capa de cascada y especificidad, la hoja de estilo del bloque prevalece sobre la del tema. Para cambiar esto, aumente la especificidad de la regla del tema o
agregue la hoja de estilo del tema al encabezado Blockstudio generado mediante el filtro
blockstudio/render/head. El contenido añadido
por el filtro se coloca después de los recursos del bloque. Desactive también la inclusión de la hoja de estilo desde
WordPress para evitar que se cargue dos veces.
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')) . '">';
});
El filtro head solo se ejecuta cuando Blockstudio almacena en búfer la página. El almacenamiento en búfer está desactivado en la vista previa del Personalizador y cuando blockstudio/buffer/enabled devuelve false. bs_is_buffering() indica en qué caso se encuentra, para que un tema pueda añadir su hoja de estilos mediante el filtro cuando la página está en búfer y ponerla en cola con WordPress en caso contrario. La respuesta está disponible a partir de wp_enqueue_scripts y es false antes de 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);
});
Use blockstudio/buffer/output si necesita
reorganizar el documento final de otra manera.
Desactivar la inclusión
La inclusión automática de recursos se puede desactivar con el ajuste assets/enqueue. Esto resulta útil si prefiere encargarse de incluir todos los recursos por su cuenta.
add_filter('blockstudio/settings', function($settings) {
$settings['assets']['enqueue'] = false;
return $settings;
});
Por bloque
Si la plantilla de un bloque no devuelve nada, Blockstudio no añadirá recursos para ese bloque. Esto resulta práctico para desactivar la inclusión cuando se cumple una condición determinada.
PHP
<?php
if ( !$a['slides'] ) {
// or return '';
return false;
}
?>
<div>my slider</div>
Twig
{% if not a.slides %}
<div>my slider</div>
{% endif %}