注册资源
在页面上使用区块时,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()或@import中包含相对 URL,链接加载时会相对于样式表解析,内联时则会相对于页面解析。绝对路径、完整 URL、data:URI 和#片段均可正常使用。 - 如果文件使用
image-set(),或包含闭合的</style序列。 - 如果文件包含 CSS 转义字符、HTML 注释起始符或
@charset声明。为避免改变 URL 或影响文档解析,这些文件会保守地继续以链接方式加载。
使用设置筛选器,将限制从 PHP 更改为:
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);
内联的 CSS 会成为页面 HTML 的一部分。样式表发生更改后,必须清除页面缓存;浏览器也无法在不同页面间缓存这些字节,因此该限制按每页总量计算。
作用域限定
作用域限定的样式也会内联,但会添加一个 ID 前缀,该 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 因客户端区块注册时使用的
apiVersion低于 3 而停用了编辑器 iframe,编辑器画布和 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 的队列系统。
对于重要性、级联层和优先级相同的规则,区块样式表的优先级高于主题样式表。若要改变这一点,可以提高主题规则的优先级,或者将主题样式表追加到由 Blockstudio 生成的 head 中,并使用 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')) . '">';
});
只有在 Blockstudio 缓冲页面时,head 筛选器才会运行。在自定义器预览中,以及 blockstudio/buffer/enabled 返回 false 时,不会进行缓冲。bs_is_buffering() 会告知你当前所处的情况,因此主题可以在页面缓冲时通过筛选器附加其样式表,否则则使用 WordPress 将其加入队列。从 wp_enqueue_scripts 起即可获取该结果,并且该结果会在 template_redirect 之前处于 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);
});
如果需要以其他方式重新排列最终文档,请使用 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 %}