Pular para o conteúdo

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
<?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:

PHP
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:

JSON
{
  "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.

Configurações

A tabela completa de opções performance.media.

Pré-renderização estática

Os metadados de mídia são a segunda etapa na ordem de adoção para produção.