Bilder

Image platziert ein Rasterbild, PNG oder JPEG. Geben Sie ihm eine Quelle und auf Wunsch eine Größe.

import { Image } from "@jasy/pdf";

Image("logo.png", { width: 120 });

Bekommt es ein SVG, bleibt das ein Vektor, statt zur Bitmap zu werden - derselbe Aufruf, keine Option:

Image("logo.svg", { width: 120 });

Was dieser Weg abdeckt, steht unter SVG und Canvas.

Quellen

Was ein Bild ist, ergibt sich aus seinen Bytes, nie aus seinem Namen, also funktioniert auch .../photo?id=7. Eine Datei wird gelesen, wenn Sie Image aufrufen, ein falscher Pfad scheitert also in dieser Zeile und nicht erst später beim Rendern.

• PNG behält seine Transparenz.
• JPEG behält den Farbraum, in dem es gespeichert wurde: Graustufen, RGB oder CMYK. Die EXIF-Ausrichtung eines Fotos wird angewendet, ein Handybild steht also aufrecht, wie im Browser.

Von einer URL seit beta.4

Eine http(s):- oder data:-Adresse funktioniert überall, wo ein Dateipfad funktioniert - für PNG, JPEG und SVG gleichermaßen:

Image("https://example.com/logo.png", { width: 120 });
Image("https://example.com/logo.svg", { width: 120 }); // still a vector

Das Bild wird einmal pro Rendervorgang geladen, vor dem Layout, ein Bild mit nur einer Breite bekommt seine Höhe also trotzdem aus der echten Aspect Ratio. Ein toter Link scheitert mit einem ImageUrlError, der die Adresse nennt - er wird nie stillschweigend weggelassen. Jeder Abruf hat 15 s Timeout und eine Obergrenze von 32 MB, geprüft, während die Bytes ankommen.

Ein URL-Bild, das erst in einem PageBuilder entsteht, lässt sich nicht vor dem Layout laden. Geben Sie ihm eine width und eine height; ohne sie füllt es den angebotenen Platz und meldet image-unsized (siehe Ausgabe).

Größe geändert in beta.5

Ohne Größe ist ein Bild so groß, wie seine Datei sagt: seine Pixel in der Auflösung, die die Datei angibt (pHYs bei PNG, JFIF oder EXIF bei JPEG), sonst bei 96 dpi - ein CSS-Pixel. Ein Logo mit 240 px ohne Angabe ist 180 pt breit; ein Screenshot mit 144 dpi kommt in der Hälfte seiner Pixelzahl heraus. Ist es breiter als der angebotene Platz, wird es passend verkleinert, in der eigenen Aspect Ratio. Vergrößert wird es nie.

Vor beta.5 war ein Pixel ein Punkt, und die Auflösung in der Datei wurde ignoriert.

Image("logo.png"); // its own size, scaled down to fit
Image("logo.png", { width: 120 }); // the height follows the ratio
Image("banner.png", { width: "100%" }); // the full width it is offered
Image("photo.jpg", { width: 160, height: 100, fit: "cover" }); // a box of its own

Geben Sie eine Seite an, folgt die andere der Aspect Ratio des Bildes. Eine Größe ist in Punkt oder in Prozent des angebotenen Platzes. aspectRatio ersetzt die eigene Aspect Ratio des Bildes, und minWidth / maxWidth / minHeight / maxHeight begrenzen das Ergebnis, wie bei jedem Element (siehe Layout).

Die Box füllen

fit steuert, wie das Bild seine Box füllt. Es entspricht CSS object-fit.

Ohne Größe ergibt sich die Box aus dem Bild, das Standard-"fill" zeichnet es also unverzerrt. Mit width und height wählen Sie das fit, das Sie wollen.

Wo es in seiner Box sitzt seit beta.5

Lässt fit Platz frei oder beschneidet das Bild, sagt align, wo es sitzt. Der Standard ist "center".

Image("portrait.jpg", { width: 120, height: 120, fit: "cover", align: "top" }); // keeps the face

align ist "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left" oder "bottom right".

Wo die Box des Bildes in ihrer Column oder Row sitzt, bestimmt das align des Elternelements oder das eigene alignSelf des Bildes - wie bei jedem Element.

Abgerundet und rund

radius rundet die Box des Bildes ab (das Bild wird auf das abgerundete Rechteck zugeschnitten). Ein quadratisches Bild mit einem Radius der halben Seitenlänge wird zum Kreis, ideal für einen Avatar.

Image("avatar.jpg", { width: 96, height: 96, fit: "cover", radius: 48 });
Image("photo.jpg", { width: 160, height: 100, fit: "cover", radius: [12, 12, 0, 0] }); // top only

Eine Zahl rundet alle vier Ecken. Ein Objekt nennt sie einzeln ({ topLeft, topRight, bottomRight, bottomLeft }); ein Array folgt der Reihenfolge von CSS, im Uhrzeigersinn von oben links.

Optionen

Ein SVG über Image nimmt die Größen- und Layout-Optionen und alt. Ein anderes fit als "contain", align und radius sind dort ein benannter Fehler: Eine Zeichnung wird immer passend skaliert und zentriert, das ist der eigene Standard von SVG.

Was abgelehnt wird

Nichts wird stillschweigend weggelassen oder falsch gezeichnet. Jeder dieser Fälle stoppt das Rendern mit einem Fehler, der sagt, was zu tun ist:

• eine Datei, die sich nicht lesen lässt, eine URL, die sich nicht laden lässt (ImageUrlError), oder ein anderes Format als PNG, JPEG und SVG;
• ein JPEG, das PDF-Viewer nicht dekodieren können - verlustfrei, hierarchisch oder arithmetisch kodiert (JpegFormatError);
• ein CMYK-JPEG in einem PDF/A-Dokument, dessen sRGB-Output-Intent CMYK verbietet (JpegFormatError) - wandeln Sie das Bild vorher nach RGB um.

Alles in einer Datei

Kopieren Sie das neben ein Bild namens photo.png und führen Sie es mit npx tsx images.ts aus.

import { writeFileSync } from "node:fs";
import { Document, Page, Row, Column, Text, Image, renderToBytes } from "@jasy/pdf";

async function build() {
  const doc = Document([
    Page({ size: "A4", margin: 56 }, [
      Column({ gap: 16 }, [
        Text("Images", { size: 22, bold: true, color: "#1450aa" }),
        Image("photo.png", { width: 200 }),
        Row({ gap: 16 }, [
          Image("photo.png", { width: 120, height: 90, fit: "contain" }),
          Image("photo.png", { width: 120, height: 90, fit: "cover", align: "top" }),
          Image("photo.png", { width: 90, height: 90, fit: "cover", radius: 45 }),
        ]),
      ]),
    ]),
  ]);

  writeFileSync("images.pdf", await renderToBytes(doc));
}

build();