Mídia
As imagens do tema ficam fora da biblioteca de mídia, então WordPress não conhece suas dimensões e cada imagem sem estilo desloca o layout enquanto carrega. Blockstudio preenche essa lacuna com um manifesto de metadados gerado, um auxiliar de modelo que sempre emite as dimensões reais e um carregador lento opcional.
Renderização de imagens
bs_media_image() renderiza recursos do tema com largura, altura e proporção reservada reais:
<?php
echo bs_media_image([
'src' => 'assets/images/hero.webp',
'alt' => 'Hero',
'class' => 'hero-media',
'sources' => [
['srcset' => '/hero-small.webp', 'media' => '(max-width: 640px)'],
],
]);
?>
A saída é um figure.blockstudio-media com um aspect-ratio inline em torno de um img que contém valores reais de width, height, loading e decoding.
src aceita um caminho relativo ao tema, um caminho absoluto ou um URL completo, e attachmentId abrange imagens da biblioteca de mídia. eager desativa o carregamento lento acima da dobra, e sources emite um elemento <picture> com as alternativas fornecidas.
Quando há metadados, o auxiliar sempre emite valores conhecidos de largura, altura e proporção. O modo lento usa apenas classes, atributos, identificadores e variáveis globais de blockstudio-*.
O manifesto de metadados
As dimensões vêm de assets/media.json, gravado por Blockstudio\Media_Metadata_Builder em uma etapa de build ou manualmente:
use Blockstudio\Media_Metadata_Builder;
(new Media_Metadata_Builder())->write(
get_stylesheet_directory(),
true
);
Isso grava metadados determinísticos para os recursos do tema e, com o segundo argumento, anexos opcionais de WordPress. Gere novamente sempre que os arquivos em assets/ mudarem.
Media_Metadata_Builder::build( string $root ) retorna o manifesto sem gravá-lo; write() é a variante que o persiste. Blockstudio\Media_Metadata::reset() limpa o cache em processo após uma recompilação, algo necessário em processos de build de longa duração antes de renderizar com metadados atualizados.
Carregamento lento
As configurações performance.media controlam o carregador do frontend:
{
"performance": {
"media": {
"lazy": true,
"skeleton": true,
"metadata": true,
"rootMargin": "300px"
}
}
}
Com lazy ativado, o URL real é movido para data-src atrás de um espaço reservado com dimensões corretas, e o carregador de Blockstudio baseado em interseção o substitui quando a imagem se aproxima da janela de visualização, carregando rootMargin antecipadamente. skeleton exibe o espaço reservado de carregamento integrado, e metadata declara que assets/media.json está em uso.
Os perfis de speed e strict desempenho ativam o carregador por padrão; compat o mantém desativado. Cada valor filho pode substituir o padrão do perfil.
A tabela completa de opções
performance.media.
Os metadados de mídia são a segunda etapa na ordem de adoção para produção.