跳转到正文

媒体

主题图像位于媒体库之外,因此 WordPress 不知道它们的尺寸,未设样式的图像在加载时都会导致布局偏移。Blockstudio 通过生成的元数据清单、始终输出实际尺寸的模板助手以及可选的延迟加载器来解决这一问题。

渲染图像

bs_media_image() 会以实际宽度、高度和预留宽高比来渲染主题资源:

PHP
<?php
echo bs_media_image([
    'src' => 'assets/images/hero.webp',
    'alt' => 'Hero',
    'class' => 'hero-media',
    'sources' => [
        ['srcset' => '/hero-small.webp', 'media' => '(max-width: 640px)'],
    ],
]);
?>

输出是一个 figure.blockstudio-media,其中 img 带有真实的 width、height、loading 和 decoding 值,并由内联 aspect-ratio 包围。

src 接受相对于主题的路径、绝对路径或完整的 URL;attachmentId 则用于处理媒体库图像。eager 可停用首屏上方内容的延迟加载;sources 会生成一个 <picture> 元素,并附带给定的备用项。

只要存在元数据,助手就始终会输出已知的宽度、高度和宽高比值。延迟加载模式只使用 blockstudio-* 类、属性、句柄和全局变量。

元数据清单

尺寸来自 assets/media.json,可在构建步骤中由 Blockstudio\Media_Metadata_Builder 写入,也可手动编写:

PHP
use Blockstudio\Media_Metadata_Builder;

(new Media_Metadata_Builder())->write(
    get_stylesheet_directory(),
    true
);

这会为主题资源写入确定性元数据;使用第二个参数时,还会包含可选的 WordPress 附件。每当 assets/ 下的文件发生变化时,都应重新生成清单。

Media_Metadata_Builder::build( string $root ) 返回清单但不写入;write() 是会持久化清单的变体。重建后,Blockstudio\Media_Metadata::reset() 会清除进程内缓存;长期运行的构建进程在使用新元数据渲染前需要执行此操作。

延迟加载

performance.media 设置控制前端加载器:

JSON
{
  "performance": {
    "media": {
      "lazy": true,
      "skeleton": true,
      "metadata": true,
      "rootMargin": "300px"
    }
  }
}

启用 lazy 后,真实的 URL 会移至 data-src,并由尺寸正确的占位图代替。当图像接近视口时,Blockstudio 基于交叉检测的加载器会将其换入,并提前加载 rootMargin。skeleton 会显示内置加载占位图;metadata 则声明正在使用 assets/media.json。

speed 和 strict 性能配置文件默认启用加载器;compat 则默认关闭。每个子项值都可以覆盖其配置文件默认值。

设置

完整的 performance.media 选项表。

静态预渲染

媒体元数据是生产环境采用顺序中的第二步。