跳转到正文

注册资源

在页面上使用区块时,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> 标签。

JSON
{
  "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 更改为:

PHP
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);

内联的 CSS 会成为页面 HTML 的一部分。样式表发生更改后,必须清除页面缓存;浏览器也无法在不同页面间缓存这些字节,因此该限制按每页总量计算。

作用域限定

作用域限定的样式也会内联,但会添加一个 ID 前缀,该 ID 对每个区块都是唯一的。使用 bs_get_scoped_class 函数将类添加到模板中。

PHP
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
  <h1 class="hero__title">Scope me!</h1>
</section>
CSS
%selector% {
  --hero-gap: var(--wp--preset--spacing--space-10);
}

%selector%.hero {
  border-bottom: 1px solid currentColor;
}

.hero__title {
  color: red;
}

以上内容会生成如下作用域限定的样式:

HTML
<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)css
  • global-styles.inline.(s)css
  • global-styles.editor.(s)css
  • global-styles.scoped.(s)css
  • global-scripts.js
  • global-scripts.inline.js
  • global-scripts.editor.js
  • global-scripts.view.js

管理后台

管理后台资源只会在 WordPress 管理区域加入队列。使用 admin- 前缀来定义管理后台资源。

  • admin-styles.(s)css
  • admin-scripts.js

区块编辑器

区块编辑器资源只会在区块编辑器中加入队列。使用 block-editor- 前缀来定义区块编辑器资源。

  • block-editor-styles.(s)css
  • block-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 中取消该样式表的队列,以免重复加载。

PHP
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 状态。

PHP
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 设置停用自动资源队列。如果你想自行处理所有资源队列,这会很有用。

PHP
add_filter('blockstudio/settings', function($settings) {
  $settings['assets']['enqueue'] = false;
  return $settings;
});

按区块设置

当区块模板返回空内容时,Blockstudio 不会为该区块加入任何资源队列。这种方式适合在满足特定条件时停用资源入队。

PHP

PHP
<?php
  if ( !$a['slides'] ) {
    // or return '';
    return false;
  }
?>

<div>my slider</div>

Twig

Twig
{% if not a.slides %}
  <div>my slider</div>
{% endif %}