Das Bildmaterial rendern
Silhouetten, Patronenzeichnungen, Fotos und 3D-Modelle, und die eine wichtige Entscheidung: URL, Rohbytes oder Data-URI.
URL, Bytes oder Data-URI
Jedes Asset gibt es in drei Formen, und die falsche macht eine Seite schwer oder einen Feed unlesbar. Die Medienseite listet die Arten; hier steht, welche Form Sie anfordern.
| Wohin es geht | Anfordern | Warum |
|---|---|---|
| Ein <img> auf einer Webseite | url oder sizes.display | Der Browser cacht es, das CDN liefert es, und Ihr HTML bleibt klein. |
| Markup, das Sie stylen wollen | format=json | Der SVG-Quelltext, in Ihr eigenes DOM eingefügt, damit CSS ihn füllen und färben kann. |
| Eine E-Mail, ein PDF, eine Feed-Zeile | format=datauri | Dort ist keine zweite Anfrage möglich. Die Bytes reisen mit dem Dokument. |
| Eine Datei auf Platte oder im eigenen Bucket | die Raw-Helfer des SDK | Bytes plus Content-Type, die CDN-Weiterleitung bereits gefolgt. |
| Ein 3D-Viewer | /model | Eine GLB als model/gltf-binary. Einmal laden und hart cachen; das Größte, was wir ausliefern. |
Strichzeichnungen
Für den größten Teil des Katalogs gibt es eine Zeichnung, weshalb die Silhouette der richtige Ersatz ist, wenn kein Foto existiert. format entscheidet, was zurückkommt, und stroke_width mit stroke_color setzt eine Kontur, damit die Form auf jedem Hintergrund lesbar bleibt.
TypeScript
Inline the source when the drawing has to inherit your theme:
import { GunSpec } from '@buun_group/gunspec-sdk' const gunspec = new GunSpec({ apiKey: process.env.GUNSPEC_API_KEY }) // an inlined SVG can be filled by CSS, an <img> cannot.const { data } = await gunspec.firearms.getSilhouette('glock-g17', { format: 'json' })const markup = data.svg- Die Zeichnungen sind gefüllte Flächen und verschwinden deshalb auf dunklem Untergrund. Setzen Sie eine Kontur oder invertieren Sie sie in CSS, wenn Sie den Quelltext einbetten.
- Betten Sie das SVG ein, wenn die Zeichnung zu Ihrem Theme passen muss. Ein
<img>lässt sich nicht umfärben, eingebettetes Markup schon. - Sie skalieren ohne Derivate auf jede Größe, was sie zur günstigen Wahl für Listenzeilen und Vergleichstabellen macht.
Wann eine Data-URI richtig ist
Eine Data-URI ist Base64, also rund ein Drittel größer als die Datei, und sie lässt sich nicht getrennt vom tragenden Dokument cachen. Das lohnt sich an genau drei Stellen.
| Situation | Urteil |
|---|---|
| HTML-E-Mail oder ein generiertes PDF | Ja. Der Client lädt kein entferntes Bild und ist oft gar nicht online. |
| Ein Produktfeed oder Export, den ein Partner einliest | Ja, für kleine Zeichnungen. Es spart dem Importer einen Abrufschritt. |
| Eine Listenseite im Browser | Nein. Vierzig Zeilen Base64 sind ein Megabyte HTML, das mit der Seite gecacht wird und mit ihr stirbt. |
| Ein Icon, das überall auf der Seite wiederkehrt | Nein. Eine gecachte Datei schlägt dieselben Bytes auf jeder Seite. |
| Ein Canvas- oder PDF-Renderer ohne asynchrone Abrufe | Ja. Genau dafür gibt es das Format. |
Patronenzeichnungen
Jede katalogisierte Laborierung zeichnet ihre eigene Patrone unter /bullet.svg, und die Zeichnungen stehen maßstäblich zueinander: eine Reihe davon ist ein Größenvergleich und keine Dekoration. Kombinieren Sie sie mit den Zahlen aus Patronen und Ballistik.
TypeScript
Returns the SVG as a string.
const svg = await gunspec.ammunition.getBulletSvg('9x19mm-124gr-fmj')Fotos, Renderings und ihre Derivate
Ein gehostetes Asset trägt sizes mit Thumb, Display und Vollversion, dazu width, height, alt wo vorhanden und credit, wo der Katalog ihn führt. Liefern Sie das Derivat aus, das Sie anzeigen, und rendern Sie den Credit, der laut der Lizenzseite eine Bedingung und keine Höflichkeit ist.
// Photographs and renders come with their derivatives, so the// browser downloads the size it is going to display.const { data: media } = await gunspec.firearms.listMedia('glock-g17', { kind: 'photo' }) const hero = media[0]const img = { src: hero.sizes?.display ?? hero.url, srcSet: hero.sizes ? `${hero.sizes.thumb} 320w, ${hero.sizes.display} 1024w, ${hero.sizes.full} 2048w` : undefined, // Null, not an empty string, where nobody has written alt text. alt: hero.alt ?? `${firearm.name}`, width: hero.width, height: hero.height,} // The credit is a condition of use, not a caption you may drop.if (hero.credit) caption.textContent = hero.credit3D-Modelle und Dateien herunterladen
Datensätze mit Modell liefern unter /model eine GLB als model/gltf-binary. Es ist das Größte, was diese API zurückgibt: einmal holen, speichern und von der eigenen Origin ausliefern. Die Raw-Helfer des SDK geben Ihnen die Bytes samt aufgelöstem Content-Type.
- Filtern Sie eine Liste mit
has_3d_model=true, wenn eine Funktion nur für Datensätze mit Modell funktioniert. - Laden Sie es verzögert. Ein Viewer, der das Modell lädt, bevor jemand danach fragt, ist die schwerste Seite Ihrer Site.
- Dasselbe gilt für Schnittzeichnungen und große Fotos: einmal in den eigenen Speicher holen, statt jede Ansicht zu proxen.
Sauber ausliefern
Vier Gewohnheiten, die eine bildlastige Seite schnell halten und Ihr Kontingent für Daten statt für Bilder aufheben.
- Assets kommen vom CDN und dürfen hart gecacht werden. Eine Lebensdauer hat der Metadaten-Aufruf, siehe Caching.
- Kopieren Sie Genutztes in Ihren eigenen Bucket, wenn Sie garantierte Verfügbarkeit und eigene Cache-Header brauchen. Die Lizenz erlaubt die Auslieferung im Produkt.
- Setzen Sie
widthundheightaus den Metadaten, damit die Seite beim Laden nicht springt. - Alt-Text ist
null, wo niemand einen geschrieben hat. Weichen Sie auf den Datensatznamen aus und rendern Sie nie eine leere Zeichenkette.