Vai al contenuto

Media

Le immagini del tema si trovano fuori dalla libreria multimediale, quindi WordPress non ne conosce le dimensioni e ogni immagine senza stile sposta il layout durante il caricamento. Blockstudio colma questa lacuna con un manifesto di metadati generato, un helper per i template che emette sempre le dimensioni effettive e un caricatore differito opzionale.

Rendering delle immagini

bs_media_image() esegue il rendering delle risorse del tema con larghezza e altezza effettive e un rapporto d’aspetto riservato:

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)'],
    ],
]);
?>

L’output è un figure.blockstudio-media con un aspect-ratio inline attorno a un img che contiene i valori effettivi di width, height, loading e decoding.

src accetta un percorso relativo al tema, un percorso assoluto o un URL completo, mentre attachmentId gestisce le immagini della libreria multimediale. eager esclude il caricamento differito per i contenuti above the fold e sources emette un elemento <picture> con le varianti specificate.

Quando i metadati sono disponibili, l’helper emette sempre i valori noti di larghezza, altezza e rapporto d’aspetto. La modalità differita usa solo classi, attributi, handle e variabili globali blockstudio-*.

Il manifesto dei metadati

Le dimensioni provengono da assets/media.json, scritto da Blockstudio\Media_Metadata_Builder durante una fase di build o manualmente:

PHP
use Blockstudio\Media_Metadata_Builder;

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

Questo genera metadati deterministici per le risorse del tema e, con il secondo argomento, per gli allegati WordPress facoltativi. Rigenerateli ogni volta che cambiano i file in assets/.

Media_Metadata_Builder::build( string $root ) restituisce il manifesto senza scriverlo; write() è la variante che lo salva. Blockstudio\Media_Metadata::reset() svuota la cache del processo dopo una ricostruzione, operazione necessaria nei processi di build di lunga durata prima di eseguire il rendering con metadati aggiornati.

Caricamento differito

Le impostazioni performance.media controllano il caricatore frontend:

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

Quando lazy è attivo, il vero URL viene spostato in data-src dietro un segnaposto delle dimensioni corrette e il caricatore di Blockstudio basato sull’intersezione lo sostituisce quando l’immagine si avvicina all’area visibile, con rootMargin caricato in anticipo. skeleton mostra il segnaposto di caricamento integrato e metadata dichiara che è in uso assets/media.json.

I profili speed e strict prestazioni abilitano il caricatore per impostazione predefinita; compat lo lascia disattivato. Ogni valore secondario può sovrascrivere l’impostazione predefinita del profilo.

Impostazioni

La tabella completa delle opzioni performance.media.

Prerendering statico

I metadati multimediali sono il secondo passaggio nell’ordine di adozione in produzione.