Pretext klingt komplex, ist aber schnell aufgesetzt. Dieser Guide führt von der Installation bis zur ersten funktionierenden Layout-Berechnung. Du brauchst Node.js und ein Canvas-fähiges Umfeld (Browser oder Node mit node-canvas).
Pretext sounds complex but is quick to set up. This guide takes you from installation to your first working layout calculation. You'll need Node.js and a Canvas-capable environment (browser or Node with node-canvas).
1. Installation1. Installation
npm install pretext
Oder direkt über den GitHub-Link als ESM-Modul einbinden. Pretext hat keine weiteren Abhängigkeiten. Or include it directly from the GitHub repo as an ESM module. Pretext has no additional dependencies.
2. Die zwei Phasen verstehen2. Understanding the Two Phases
Pretexts API besteht aus zwei klar getrennten Schritten: Pretext's API consists of two clearly separated steps:
prepare(texts, options)— Misst Font-Metriken via Canvas. Einmalig ausführen, Ergebnis cachen.Measures font metrics via Canvas. Run once, cache the result.layout(prepared, width)— Berechnet Zeilenumbrüche und Höhen. Reines Arithmetik, beliebig oft aufrufbar.Calculates line breaks and heights. Pure arithmetic, call as often as needed.
3. Einfaches Beispiel3. Simple Example
import { prepare, layout } from 'pretext';
// Die Texte die du messen willst
const texts = [
"Hello, this is some text that needs layout.",
"Another paragraph with different content.",
"Short line."
];
// Phase 1: Font-Metriken sammeln (einmalig)
const prepared = await prepare(texts, {
font: '16px Georgia',
lineHeight: 1.5
});
// Phase 2: Layout berechnen (beliebig oft, kein DOM!)
const result = layout(prepared, 400); // 400px Breite
// result enthält für jeden Text:
// - lines: Array von Zeilenobjekten
// - height: Gesamthöhe in Pixel
console.log(result[0].height); // z.B. 72
console.log(result[0].lines.length); // z.B. 3
4. Canvas-Rendering4. Canvas Rendering
Mit den berechneten Positionen kannst du auf einem Canvas rendern, ohne weiteren DOM-Zugriff: With the calculated positions you can render on a Canvas without further DOM access:
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
ctx.font = '16px Georgia';
result.forEach((textResult, i) => {
const yOffset = i * 100; // Dein Layout-Grid
textResult.lines.forEach((line, lineIndex) => {
ctx.fillText(
line.text,
0, // x
yOffset + lineIndex * 24 // y (lineHeight * index)
);
});
});
5. Unterschiedliche Zeilenbreiten5. Variable Line Widths
Das ist Pretexts Killerfeature: Text kann pro Zeile unterschiedlich breit sein, für Layouts die um Bilder oder Formen fliessen: This is Pretext's killer feature: text can have different widths per line, for layouts that flow around images or shapes:
// Zeilenbreiten als Array statt einzelnem Wert const lineWidths = [ 400, 400, 400, // erste 3 Zeilen: volle Breite 200, 200, // nächste 2: halbe Breite (Bild rechts) 400, 400 // wieder voll ]; const result = layout(prepared, lineWidths);
6. Performance Best Practices6. Performance Best Practices
- prepare() einmal aufrufen und das Ergebnis cachen. Bei Font-Wechsel nochmals aufrufen.Call prepare() once and cache the result. Re-call when the font changes.
- layout() ist frei — beliebig oft in Animationsloops, Event-Handlern, Worker-Threads.layout() is free — call freely in animation loops, event handlers, worker threads.
- Batch prepare() — alle Texte auf einmal statt einzeln übergeben.Batch prepare() — pass all texts at once rather than individually.
- Kein DOM nötig — Pretext läuft auch in Web Workers.No DOM needed — Pretext runs in Web Workers too.