跳转到正文

处理资源

压缩

Blockstudio 能够自动压缩区块中的所有 CSS 和 JS 文件。

编译后的文件会保存到区块的 _dist 文件夹中,并在使用区块时加入队列。源文件更新时,Blockstudio 会检查是否存在时间戳相同的编译文件;如果不存在,就会创建该文件。

为此使用了 压缩库。

可以使用 assets/minify 设置启用压缩:

PHP
add_filter('blockstudio/settings/assets/minify/css', function() {
  return true;
});

add_filter('blockstudio/settings/assets/minify/js', function() {
  return true;
});

SCSS

如果你更喜欢用 SCSS 编写样式,可以启用 SCSS 处理:

PHP
add_filter('blockstudio/settings/assets/process/scss', function() {
  return true;
});

这会为 .css 文件启用 SCSS 处理。

或者,你可以使用 .scss 扩展,即使未启用上述设置 true,样式也会自动得到处理。

导入路径

使用 SCSS 时,可以导入其他 SCSS 文件。导入路径相对于发起导入的文件。

CSS
@import "modules.scss";

此外,还可以使用 blockstudio/assets/process/scss/import_paths 过滤器定义自定义导入路径,这样无需指定任何文件夹结构,也可以从其他目录导入文件。

导入时可以省略 .scss 扩展名,并解析诸如 _tokens.scss 这样的分部文件或目录的 _index.scss。

PHP
add_filter('blockstudio/assets/process/scss/import_paths', function($paths) {
  $paths[] = get_template_directory() . '/scss';
  return $paths;
});

预导入代码

如果你希望在每个 SCSS 文件中都能使用共享的 Sass 函数、变量、混入或实用工具,可以在编译前添加全局预导入代码。

这对 Bootstrap 之类的框架很有用,你可以使用断点等共享混入,而不必在每个区块资源中重复导入。

PHP
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);

结合 blockstudio/assets/process/scss/import_paths 使用后,所有编译文件都可以使用引用的 Sass 表面。

依赖项的修改时间发生变化时,区块资源会重新编译,包括其他分部文件导入的文件。Blockstudio 会跟踪本地 @import、@use 和 @forward 依赖项,包括预导入代码的依赖项和已配置的导入路径。共享依赖项只会跟踪一次,依赖发现过程也不会陷入循环。这些文件还会加入运行时缓存监视列表。

例如,编辑 mixins/_wysiwyg.scss 会重新编译 global-styles.scss(当它导入 scss/_wysiwyg.scss,而后者又导入该混入时)。无需修改入口文件即可应用更改。Sass 内置模块和远程导入不属于本地依赖关系图。

ES 模块

Blockstudio 中的所有脚本(内联脚本和默认脚本)默认都会应用 type="module" 加载。这意味着区块脚本无需额外设置即可使用 导入语法。

注意

如需深入了解 ES 模块,请参阅 MDN 网页文档。

假设 script.js 中有以下代码:

JavaScript
import { h, render } from "https://esm.sh/preact@10.15.1";
import htm from "https://esm.sh/htm@3.1.1";
import confetti from "https://esm.sh/canvas-confetti@1.6.0";

const html = htm.bind(h);

function App(props) {
  confetti();
  return html`<h1>Hello ${props.name}!</h1>`;
}

render(
  html`<${App} name="Hello from Preact!" />`,
  document.querySelector("#element")
);

上面的示例会使用 Preact 创建一个组件,从兼容 ESM 的 CDN 导入所有必需的组件和函数,本例中为 esm.sh。这种方式本身没有问题,但缺点是需要从外部网站请求所需资源;如果 CDN 宕机,脚本就可能无法运行。

Blockstudio 提供了一种便捷方式,可将 ES 模块下载到区块中,从而无需在生产环境中使用外部 ESM CDN。

设置

要将模块下载到区块目录,请使用 npm: 前缀,后接软件包名称和版本:

JavaScript
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";

此语法遵循 Deno 的 npm说明符约定。

注意

出于向后兼容的考虑,仍支持旧版 blockstudio/ 前缀(e.g.、blockstudio/preact@10.15.1),但我们建议新项目使用 npm: 前缀。详情请参阅 迁移指南。

Blockstudio 会自动检查已更改的 .js 文件中是否有导入,并将它们下载到本地区块目录。下载的文件会放在区块目录中的 modules 文件夹内。

保存时会重写脚本文件,以适配本地托管的模块:

JavaScript
import { h, render } from "./modules/preact/10.15.1.js";
import htm from "./modules/htm/10.15.1.js";
import confetti from "./modules/canvas-confetti/1.6.0.js";

在编辑器中预览和编辑区块时,仍会使用 CDN URL(Blockstudio 使用 esm.sh)。

注意事项

版本

通常,无需指定版本号即可从 CDN 使用模块,此时始终会使用最新版本。由于 Blockstudio 不会将任何信息保存到数据库,因此使用模块时必须指定版本号。

相同模块

模块的作用范围限定在各自的区块内。即使你在多个区块中使用相同版本的同一模块,Blockstudio 仍会将请求的模块下载到该区块。这主要是因为区块应该是独立的单元,便于在其他安装或网站之间共享。

此外,如果两个区块同时出现在一个页面上,同一模块也会被请求两次。使用 script.js 文件替代 script-inline.js 可以解决此问题。若模块名称和版本号相同,Blockstudio 会将每个导入重写为指向该模块首次出现的位置。

CSS 加载器

也可以使用上述相同语法导入 CSS 文件。

JavaScript
import "npm:swiper@11.0.0/swiper.min.css";

CSS 文件会下载到 modules 文件夹,并在使用区块时自动加入队列。只要版本相同,即使 CSS 文件存在于多个区块中,也只会有一个版本加入队列。