Registro de recursos
Blockstudio enfileirará automaticamente todos os arquivos com final .css, .scss e .js quando o bloco for usado em uma página. É possível definir como os recursos serão enfileirados usando um dos seguintes nomes de arquivo. * é um curinga que pode ser substituído por qualquer texto de sua escolha.
Nos arquivos CSS e SCSS dos blocos, %selector% se expande para a classe envoltória específica do bloco. Isso permite selecionar o mesmo elemento que recebe bs_get_scoped_class(), mesmo quando o arquivo não é um recurso com escopo específico.
| Padrão | Comportamento |
|---|---|
*.(s)css |
Enfileira como uma tag <link> no editor e no frontend |
*.inline.(s)css |
Enfileira o conteúdo em uma tag <style> em linha no editor e no frontend |
*.editor.(s)css |
Enfileira como uma tag <link> somente no editor |
*.scoped.(s)css |
Enfileira o conteúdo com escopo em uma tag <style> em linha no editor e no frontend |
*.js |
Enfileira como uma tag <script> no editor e no frontend |
*.inline.js |
Enfileira o conteúdo em uma tag <script> em linha no editor e no frontend |
*.editor.js |
Enfileira como uma tag <script> somente no editor |
*.view.js |
Enfileira como uma tag <script> somente no frontend |
Observação
A notação com hífen (
*-inline.css,*-editor.cssetc.) ainda é compatível com versões anteriores, mas está obsoleta. Use a notação com ponto em blocos novos.
Em linha
Estilos e scripts em linha têm a grande vantagem de serem renderizados diretamente como tags de estilo ou script na página. Isso pode acelerar o carregamento, pois evita solicitações adicionais que seriam necessárias de outra forma.
- Arquivos
.jssão inseridos em linha no fim do corpo - Arquivos
.(s)csssão inseridos em linha no fim do cabeçalho - Cada arquivo é inserido em linha uma única vez
Folhas de estilo pequenas inline
Por padrão, um arquivo *.(s)css é vinculado, o que custa uma solicitação por arquivo. A configuração assets.inlineLimit imprime folhas de estilo pequenas inline, seguindo a regra que o núcleo de WordPress aplica aos próprios estilos: as folhas de estilo externas dos blocos de uma página são ordenadas da menor para a maior e impressas como <style> enquanto o total acumulado permanecer dentro do limite. Todos os outros arquivos mantêm sua tag <link>.
{
"assets": {
"inlineLimit": 40000
}
}
O limite é em bytes e 0, o valor padrão, desativa esse comportamento. Ele mede o arquivo compilado que <link> carregaria, minificado quando assets.minify.css está ativado. Somente a escolha entre <link> e <style> depende do tamanho. Cada tag permanece no lugar onde <link> estaria, portanto a ordem de carregamento e a cascata não mudam. O elemento mantém seu id.
A configuração não se aplica a arquivos *.inline.(s)css e *.scoped.(s)css, que são sempre inline, nem a recursos do editor e do admin ou a folhas de estilo extraídas de módulos JavaScript importados. Folhas de estilo globais contam como folhas de estilo de blocos. Um arquivo continua vinculado sempre que colocá-lo inline causaria alguma alteração:
- Contém um URL relativo em
url()ou@import, que é resolvido em relação à folha de estilo quando vinculado e à página quando inline. Caminhos absolutos, URLs completas, URIsdata:e fragmentos#são aceitos. - Usa
image-set()ou contém uma sequência de fechamento</style. - Contém escapes CSS, um abridor de comentário HTML ou uma declaração
@charset. Por precaução, esses arquivos continuam vinculados para evitar alterações em URL ou na análise do documento.
Use o filtro da configuração para alterar o limite a partir de PHP:
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);
O CSS colocado inline passa a fazer parte do HTML da página. É preciso limpar o cache da página após uma alteração na folha de estilo, e o navegador não pode armazenar esses bytes em cache entre páginas, por isso o limite é um total por página.
Com escopo
Os estilos com escopo também são inseridos em linha, mas recebem como prefixo um ID exclusivo para cada bloco. Use a função bs_get_scoped_class para adicionar a classe ao seu modelo.
<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;
}
O resultado acima será o seguinte estilo com escopo:
<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>
Seletores comuns dentro de um arquivo com escopo ainda selecionam descendentes do elemento envoltório com escopo. Use %selector% quando quiser estilizar o próprio elemento envoltório.
Global
Além dos recursos específicos dos blocos, também é possível enfileirar recursos globais, que ficam disponíveis em todas as páginas, independentemente da presença de um bloco. Para enfileirar um recurso global, adicione o prefixo global- ao nome do arquivo. Qualquer um dos sufixos (e.g. -inline) pode ser usado em combinação.
As combinações possíveis são:
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
Administração
Os recursos de administração são enfileirados somente na área de administração do WordPress. O prefixo admin- é usado para definir recursos de administração.
admin-styles.(s)cssadmin-scripts.js
Editor de blocos
Os recursos do editor de blocos são enfileirados somente no editor de blocos. O prefixo block-editor- é usado para definir esses recursos.
block-editor-styles.(s)cssblock-editor-scripts.js
Observação
Se WordPress desativar o iframe do editor porque um bloco do lado do cliente foi registrado com
apiVersioninferior a 3, a tela do editor e a interface administrativa WordPress compartilham o mesmo documento. Scripts globais ou do editor que se associem awindow,document,body, eventos de roda do mouse ou à rolagem do documento devem se proteger contrabody.block-editor-pageou excluir regiões do editor WordPress, como.interface-complementary-areae.interface-navigable-region.
Ordem de carregamento
No frontend, com o enfileiramento automático de recursos e o buffer de saída ativados,
Blockstudio adiciona as tags de bloco CSS <link> e <style> à página armazenada no buffer,
logo antes da tag de fechamento </head>, em vez de registrá-las com
wp_enqueue_style(). Assim, CSS do bloco vem depois das folhas de estilo que
WordPress já imprimiu no cabeçalho, incluindo os estilos de temas e plugins
enfileirados com wp_enqueue_style(), independentemente da prioridade de enfileiramento ou
das dependências. Os recursos de administração e block-editor- usam, em vez disso, o sistema de enfileiramento de WordPress.
Para regras com a mesma importância, camada de cascata e especificidade, a folha de estilo do bloco prevalece sobre a folha de estilo do tema. Para mudar isso, aumente a especificidade da regra do tema ou acrescente a folha de estilo do tema ao cabeçalho Blockstudio gerado com o filtro blockstudio/render/head. O conteúdo adicionado pelo filtro é colocado após os recursos do bloco. Remova também a folha de estilo da fila de WordPress para que ela não seja carregada duas vezes.
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')) . '">';
});
O filtro head só é executado quando Blockstudio armazena a página em buffer. O armazenamento em buffer fica desativado na pré-visualização do Personalizador e quando blockstudio/buffer/enabled retorna false. bs_is_buffering() informa em qual caso você está, para que um tema possa adicionar sua folha de estilo pelo filtro quando a página estiver em buffer e enfileirá-la com WordPress nos demais casos. A resposta fica disponível a partir de wp_enqueue_scripts e é 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 se precisar reorganizar o documento final de outra maneira.
Desativar enfileiramento
O enfileiramento automático de recursos pode ser desativado usando a configuração assets/enqueue. Isso é útil se você quiser cuidar pessoalmente do enfileiramento de todos os recursos.
add_filter('blockstudio/settings', function($settings) {
$settings['assets']['enqueue'] = false;
return $settings;
});
Por bloco
Quando o modelo de um bloco não retorna nada, Blockstudio não enfileira recursos para esse bloco. Esse método é útil para desativar o enfileiramento quando determinada condição é atendida.
PHP
<?php
if ( !$a['slides'] ) {
// or return '';
return false;
}
?>
<div>my slider</div>
Twig
{% if not a.slides %}
<div>my slider</div>
{% endif %}