Téma-assetek és média

Egy téma kétféle képet használ, és ezek különböző helyen találhatók:

Az assetek együtt mozognak a témával: a téma duplikálásakor lemásolódnak, és a témával együtt települnek. A bolti fájlok a bolthoz tartoznak: a kereskedő egyszer tölti fel őket, és minden témában, terméknél, e-mailben és oldalon felhasználhatja őket. A rajzolt képeket, mintázatokat, ikonokat és betűkészleteket assetként mellékeld, a fotókat pedig bízd a kereskedőre. A mellékelt témák nem tartalmaznak fotókat.

Az assets/ mappaHivatkozás másolása

A téma minden bináris fájlja az assets/ mappa alatt található, tetszőleges almappákban (assets/images/hero.svg, assets/fonts/display.woff2). A máshol elhelyezett bináris fájlokat a kódszerkesztő, a CLI és a tématelepítés egyaránt elutasítja.

A méretek binárisak: 1 MB = 1024 × 1024 bájt.

• Az elérési út az assets/ mappához viszonyított relatív út, legfeljebb 256 karakter hosszú. Bármely írásrendszer betűit és számjegyeit, valamint a ., _ és - karaktereket tartalmazhatja az egyes mappanevekben; nem kezdődhet ponttal, nem tartalmazhat szóközt, és a fájlnak kötelező kiterjesztéssel rendelkeznie.
• A rendszer ellenőrzi a bájtokat a típus alapján: a képnek a kiterjesztése szerinti típusnak megfelelően kell dekódolhatónak lennie, a betűkészletnek és az ikonnak tartalmaznia kell a megfelelő fájlaláírást, az SVG pedig ugyanazon a tisztítási folyamaton megy keresztül, mint a bolt médiatára (szkriptek, event handlerek, külső hivatkozások és beágyazott raszterképek esetén a rendszer elutasítja a fájlt).
• Minden asset boltonként csak egyszer tárolódik a tartalma alapján, így ha két témában ugyanaz a fájl szerepel, osztoznak rajta, duplikált téma esetén pedig csak a hivatkozás másolódik le.

Példa assetekHivatkozás másolása

Minden mellékelt téma tartalmaz egy-két apró példát az assets/images/ mappában. Mindegyik használatban van, így a media/unused-asset nem jelez hibát, és együtt szemléltetik a gyakori mintákat:

• backdrop.svg: egy visszafogott csendélet a téma színpalettájával. Ez képezi az asset://images/backdrop.svg alapértelmezett értékét a képbeállításokban (az alapértelmezett téma promóciós kártyáján, az Editorial borítóképénél, valamint a Launch kiemelt képénél), és ezzel az értékkel indul a kezdőlap is.
• hatch.svg: egy finom vonalkázott textúra, amelyet az url(asset:images/hatch.svg) helyez el az üres képkeretek alatt az alapértelmezett, az Editorial és az Essential témákban.

A fájlok egyszerű SVG alakzatokból épülnek fel, így nem tartalmaznak licencköteles, harmadik féltől származó grafikákat. Ha egy téma kódját azelőtt módosítottad, hogy ezek a fájlok megjelentek volna, a téma nem kapta meg őket. Ha nincs rájuk szükséged, nyugodtan töröld őket.

Kódban: asset()Hivatkozás másolása

import { MediaImage, asset } from '@poltura/theme-sdk/media';

export function Hero() {
  return <MediaImage image={asset('images/hero.svg')} role='hero' alt='' />;
}

A szerepkörök megegyeznek a médiatár fájljainál használtakkal: thumb, card, tile, pdp, zoom, hero, og, logo és icon. A MediaImage ugyanúgy jeleníti meg az assetet, mint a médiatárban lévő fájlokat: egy <picture> elemet képez AVIF és WebP formátumokkal, ahol a szerepkör megengedi, srcset attribútummal a nagy pixelsűrűségű kijelzőkhöz, valamint a tárolt szélességgel és magassággal, hogy a layout ne ugorjon meg (layout shift).

A téma buildje minden buildelt verzióhoz elkészít egy asset manifestet: rögzíti az egyes assetek elérési útját, hash-ét, típusát, méretét, képpontméretét és URL-jeit. A manifestből hiányzó elérési út placeholdert jelenít meg, sosem törött képet, és az ellenőrzés hibát jelez miatta (lásd alább). Az elérési utat lehetőség szerint literálként add meg. Az asset() hívása dinamikusan számított elérési úttal is megengedett, de ez kikapcsolja a fel nem használt assetek vizsgálatát a teljes témára nézve.

A media:// soha nem szerepel a kódban. A bolt fájljait a kereskedő választja ki, így azok mindig egy beállításon keresztül érkeznek.

Beállításokban és oldalakon: asset://Hivatkozás másolása

A képbeállítások, a stílusok háttérképei, valamint az oldalak és layoutok JSON-fájljaiban szereplő minden képérték hivatkozást fogad: media://<id> formátumot a kereskedő által választott bolti fájlokhoz, és asset://<path> formátumot a téma-assetekhez.

import { field } from '@poltura/theme-sdk/elements';

const settings = {
  background: field.image({ label: 'Background', default: 'asset://patterns/dots.svg' }),
};

Egy image beállítás alapértelmezett értéke kizárólag téma-asset lehet. A media:// hivatkozás vagy a közvetlen webcím megadása defaultként hibát dob, mivel a téma nem ismerheti a bolt fájljait, és nem függhet külső servertől sem. A video beállítások nem fogadnak el alapértelmezett értéket. A témaszerkesztőben a kereskedő az alapértelmezett értéket a saját médiatárának egyik fájljára cseréli le; a beállítás az általa kiválasztott hivatkozást fogja tárolni.

CSS-ben: url(asset:…)Hivatkozás másolása

.hero {
  background-image: url(asset:patterns/dots.svg);
}

A téma buildje átírja az url(asset:<path>) kifejezéseket (az idézőjelek opcionálisak, az asset:// forma is támogatott) a fájl címére a bolt /media/ útvonalán. Ha az elérési út nem található az assets/ mappában, a build meghiúsul a THEME_ASSET_MISSING hibakóddal. Az url(asset:…) formát perjelek nélkül írd, mert az ellenőrzés ezt a formátumot vizsgálja.

A témateszt: media/* szabályokHivatkozás másolása

A CLI (poltura theme check), a tématelepítés és a kódszerkesztő ugyanazokat a szabályokat futtatja. A súlyosság csak ott tér el, ahol valamelyik kevesebbet tud, vagy ahol nagyobb a tét:

A szövegekben lévő placeholder címeket tiltó tesztszabály figyelmen kívül hagyja a kép- és hivatkozásértékeket. Az ott található címeket a media/* szabályok ellenőrzik helyette.

A kódszerkesztőbenHivatkozás másolása

• A mappa mindig jelen van. Az assets/, assets/images/ és assets/fonts/ mappák minden témánál megjelennek az Explorerben, akkor is, ha még egyetlen asset sincs bennük. Megmaradnak akkor is, ha az utolsó fájlt is törlöd vagy áthelyezed: ezek a workspace mappái, nem placeholder fájlok, és róluk semmilyen adat nem tárolódik a témával együtt.
• Az assetek fájlok. Húzz át képeket, SVG-ket, betűkészleteket és ikonokat a számítógépedről közvetlenül az Explorer assets/ mappájába. Egy fájl átnevezése vagy áthelyezése frissíti az összes rá mutató hivatkozást, és elmenti a módosított fájlokat. Ha egy fájlt nem fogadhat be a mappa (az assets/ területén kívüli bájtok, a korlátot meghaladó méret vagy nem támogatott típus miatt), a szerkesztő elutasítja, és egy értesítésben megjelöli az okot.
• Előnézetek. Az assets/ alatti képek, betűkészletek és ikonok egy előnézeti ablakban nyílnak meg, ahol látható a méretük, a bájtok száma és egy Hol használod lista. A betűkészleteknél egy mintaszöveg mutatja be a karakterkészletet. Az Explorer helyi menüjében a Fájl előnézete opcióval nyitható meg az előnézet, az SVG-fájloknál pedig egy külön előnézeti gomb található a szerkesztő címsorában.
• Médiatár. A Médiatár nézet (saját ikonnal a tevékenységsávon) típus szerint rendezi a bolt fájljait, és keresőt is biztosít. Húzz egy fájlt a JSON-fájlba a media:// hivatkozás beillesztéséhez, vagy válaszd ott a Válassz a médiatárból műveletet. Az Feltöltés a médiatárba opcióval új fájlt tölthetsz fel a bolt médiatárába. Videókat az adminfelület Médiatár oldalán tölthetsz fel.
• Kiegészítés és javaslatok. Az asset(', useAssetUrl(', useThemeAsset(', "asset:// vagy url(asset: begépelése kilistázza a téma assetjeit, a "media:// pedig felsorolja a bolt képeit. Egy hivatkozás fölé víve a kurzort megjelenik a fájl, a linkre kattintva pedig megnyílik az előnézete. Az inlay hintek mutatják a képpontméretet, a médiatárban lévő fájl nevét és alt szövegét, vagy jelzik, ha a hivatkozás nem mutat sehova.
• Problémák és quick fixek. Minden mentés után lefut a teljes témateszt, és feltölti a Problems panelt (forrás: poltura-check). Ahol elérhető, quick fixeket is kínál: Használd ezt: asset://… az assets/ mappában egyező fájl elérési útjához, Erre gondoltál: asset://…?, Válassz fájlt a médiatárból, távoli cím esetén Töltsd fel a médiatárba, valamint Adj hozzá egy image_alt beállítást és Remove this value.

Következő lépésekHivatkozás másolása

• Megosztási képek (Open Graph): sablonok a megosztott hivatkozások által megjelenített képhez.
• media referencia: asset, MediaImage, useAssetUrl és useThemeAsset.