Kapitel 3.16 · Teil II · Das Handwerk
Konfiguration: Schriften, Farben und Ausgabe
Einheiten, Farben und die Palette, eigene Schriften, der HTML-Betrachter, PDF und Druckvorstufe, der Folio-Betrachter und die Debug-Überlagerungen
Kurz gesagt
Diese Seite behandelt die Einstellungen, die für das ganze Buch gelten, und die Einstellungen für jede Art von Ausgabe. Sie erklärt, wie Sie ein Maß und eine Farbe angeben und wie Sie die Farben einer Palette benennen. Sie zeigt, wie Sie eigene Schriften hinzufügen. Danach geht es um die Webansicht, die PDF-Datei, die Dateien, die eine Druckerei verlangt, und das 3D-Buch. Der letzte Abschnitt schaltet die Hilfslinien und Warnungen ein, die Ihnen bei der Arbeit helfen.
#Einheiten und Farben
#Maße
Alle physischen Maße in Postext verwenden den Typ Dimension – einen Wert zusammen mit einer Einheit:
interface Dimension {
value: number;
unit: DimensionUnit; // 'cm' | 'mm' | 'in' | 'pt' | 'px' | 'em' | 'rem'
}Absolute Einheiten – cm, mm, in, pt, px – werden mit der konfigurierten DPI-Zahl in Pixel umgerechnet. Bei 300 DPI entspricht 1 cm etwa 118 px.
Relative Einheiten – em, rem – skalieren mit der aktuellen Schriftgröße. Ein em bezieht sich auf die eigene Schriftgröße des Elements, rem auf die Schriftgröße des Grundtexts.
#Farben
Farben werden mit einer Hex-Darstellung und einem Zielfarbmodell gespeichert:
interface ColorValue {
hex: string; // '#ff0000', 'transparent', etc.
model: ColorModel; // 'hex' | 'rgb' | 'cmyk' | 'hsl' | 'spot'
cmyk?: CmykPercent; // The exact process values of a colour authored in CMYK.
spot?: SpotColor; // Die Druckfarbe einer Sonderfarbe.
overprint?: boolean; // Überdruckt in einer Druckausgabe (siehe Überdruckende Farben).
paletteId?: string; // Der Eintrag von colorPalette, dem sie folgt.
tint?: number; // Die Stärke des Eintrags über der Seitenfarbe in Prozent (mit paletteId).
}Das Feld model gibt den beabsichtigten Farbraum an. Für die Darstellung im Web sind 'hex' oder 'rgb' üblich. Für Druck-Workflows sagt 'cmyk', dass die Farbe in CMYK angegeben wurde, und cmyk bewahrt ihre Werte: Eine CMYK-Druckausgabe setzt sie unverändert, mit hex als ihrer Bildschirmdarstellung (siehe In CMYK angelegte Farben). 'spot' ist eine Sonderfarbe, mit ihrer Druckfarbe in spot (siehe Sonderfarben).
Weil Postext auf Ausgabe in Publikationsqualität zielt, wird die Standardfarbe des Grundtexts mit model: 'cmyk' (#000000) ausgeliefert. Die Farben von Überschriften, Fett, Kursiv und Listen sind standardmäßig an die Palettenfarbe Main Color (#295AA3, model: 'hex') gekoppelt. Seitenhintergrund und Überlagerungen der Oberfläche (Grundlinienraster, Schnittmarken, Debug-Anzeigen) haben standardmäßig model: 'hex'. Überschreiben Sie color.model in einem beliebigen Feld, wenn Sie eine andere Bedeutung für den Export brauchen.
#Transparenz
Eine Farbe kann durchscheinend sein. hex akzeptiert einen Alphakanal als #rgba oder #rrggbbaa. Es akzeptiert auch eine Farbe rgb() / rgba() in der Komma- oder der Leerzeichen-Syntax, mit dem Alphawert als Zahl oder Prozentwert. transparent ist vollständig durchsichtig:
const config: PostextConfig = {
header: {
elements: [{
kind: 'box',
id: 'veil',
placement: {
anchor: { to: 'bleed', edge: 'top-left' },
size: { width: 'fill', height: { value: 40, unit: 'mm' } },
},
style: { backgroundColor: { hex: '#ffffffb3', model: 'hex' } }, // white at 70 %
}],
},
bodyText: { color: { hex: 'rgba(0, 0, 0, 0.85)', model: 'rgb' } },
};Die drei Backends malen sie gleich. Canvas und HTML-Betrachter übernehmen den Wert als CSS-Farbe. Das PDF-Backend setzt die Deckkraft der Farbe als konstantes Alpha, einen ExtGState mit ca für Flächen und CA für Konturen. Das gilt für Text, Linien, Kästen, Tabellenflächen und -rahmen, Chips, Farbfelder und Formeln. Eine durchscheinende Farbe legt sich über alles, was vor ihr gemalt wurde. Ein Kasten in der Kopf- oder Fußzeile wird zuletzt gemalt und verschleiert daher den Text darunter; ein Kasten in einem Auftaktband wird zuerst gemalt und tönt daher die Seite unter dem Text. Wird das PDF in einen anderen Farbraum gezwungen (pdfGeneration.forceColorSpace mit colorSpace: 'cmyk' oder 'grayscale'), wird die Farbe umgerechnet und ihr Alpha bleibt erhalten. In der Sandbox schreibt der Deckkraftregler des Farbwählers diese Werte als #rrggbbaa, und der Farbwähler liest auch die anderen Formen.
#Eigene Schriften
Postext löst jede Zeichenkette fontFamily sowohl gegen den Katalog von Google Fonts als auch gegen die Liste customFonts des Dokuments auf. Bei Namensgleichheit haben eigene Schriften Vorrang – wenn Sie customFonts: [{ name: 'Roboto', … }] deklarieren, verwendet Postext Ihre hochgeladene Datei statt der „Roboto“ von Google Fonts. Eine Familie, die Google Fonts nicht hat, holt die Sandbox von Fontsource. Nach einem generischen Namen (serif, system-ui) oder einer Schrift, die ein Betriebssystem mitbringt (Arial, Segoe UI, PingFang SC …), fragt sie Fontsource nie: Eine solche Familie wird mit dem gesetzt, was der Rechner des Lesers hat, das Bedienfeld Schriften zeigt sie als Nicht gefunden, und PDF und SVG-Bilder haben keine Datei von ihr zum Einbetten. Wird das Buch in ihr gesetzt, laden Sie sie als eigene Schrift hoch.
Verwenden Sie eigene Schriften, wenn:
- das Dokument eine Haus- oder lizenzierte Schrift braucht, die es bei Google Fonts nicht gibt;
- die Umgebung die Schrift-CDNs nicht erreicht, also jsDelivr (woher die Sandbox die Dateien von Fontsource bezieht) oder Google Fonts (offline, Intranet, datenschutzsensibel);
- Sie die Schriftdatei privat halten müssen und sie nicht bei einem Dritten hochladen dürfen.
#Konfigurationsschema
type CustomFontFormat = 'woff2' | 'woff' | 'ttf' | 'otf';
type CustomFontStyle = 'normal' | 'italic';
interface CustomFontVariant {
weight: number; // CSS font-weight, 100..900
style: CustomFontStyle;
fileId: string; // opaque id of the binary in out-of-band storage
format: CustomFontFormat;
fileName?: string; // original upload filename (optional, shown in UI)
}
interface CustomFontFamily {
name: string; // used anywhere a Google Font family name fits
variants: CustomFontVariant[];
redistributable?: boolean; // false: wird hier verwendet, nie aus dem Buch kopiert
fallback?: string; // freie Schrift ähnlicher Breite für Schnitte ohne Datei (seit postext 1.42)
}
interface PostextConfig {
// ...
customFonts?: CustomFontFamily[];
}Die Binärdatei jeder Variante ist nicht in die Konfiguration selbst eingebettet. Die Konfiguration enthält nur Verweise fileId; die Bytes liegen getrennt davon. In der Sandbox heißt das IndexedDB (Schlüssel-Wert-Speicher, nur im Browser, privat für das Dokument). Wer Postext in einen anderen Host einbettet, kann fileId beliebig auflösen – über einen Server-Endpunkt, einen Service-Worker-Cache, was auch immer –, solange die Bytes den Hauptthread erreichen, bevor buildDocument läuft.
#Eigene Schriften in der Sandbox verwalten
Öffnen Sie das Bedienfeld Schriften über die linke Aktivitätsleiste (zwischen Ressourcen und Gestaltung). Seine Liste Schriften in diesem Buch zeigt jede Familie, die die Gestaltung verwendet, mit ihrer Rolle und ihrer Herkunft: Google Fonts, Fontsource (für eine Familie, die Google Fonts nicht hat), Ihre Datei oder nirgends (Nicht gefunden). Unter Ihre Schriftdateien gilt für jede Familie:
- Schriftfamilie hinzufügen – legt eine leere Familie an; benennen Sie sie direkt um.
- Datei hochladen – wählen Sie eine Schriftstärke (100–900) und einen Stil (normal / kursiv) und dann eine oder mehrere Dateien
.woff2,.woff,.ttfoder.otf. Jede Datei wird zu einer eigenen Variante, gebunden an das gerade gewählte Paar (Schriftstärke, Stil); der Name der hochgeladenen Datei wird gespeichert und in der Zeile angezeigt, damit Sie Varianten unterscheiden können. Schriftstärke oder Stil einer Variante lassen sich jederzeit über ihre Auswahllisten nachstellen. - Doppelte Varianten sind erlaubt. Fallen zwei Dateien auf dieselbe Kombination aus Schriftstärke und Stil, werden beide behalten, und die Warnung Doppelte Schriftvariante erscheint, damit Sie die Einstellungen der zusätzlichen Dateien eindeutig machen.
- Variante löschen oder Familie löschen – entfernt den Eintrag aus der Konfiguration und die gespeicherten Bytes aus IndexedDB.
Sobald eine Familie deklariert ist, führt jeder Schriftwähler sie in der Gruppe Eigene über der Liste von Google Fonts. Wenn Sie sie auswählen, wird die Familie in jedes Feld für Schriftfamilien eingetragen, auf das Sie sie anwenden.
#Eine Ersatzschrift für eine lizenzierte Familie
Ein Buch kann in einer Schrift gesetzt sein, die ihr Inhaber nicht weitergeben darf. Markieren Sie die Familie mit redistributable: false, und eine .postext-Datei lässt ihre Dateien weg. Geben Sie in fallback eine freie Familie ähnlicher Breite an, bricht die Datei, die ohne sie geöffnet wird, ihre Zeilen ungefähr dort um, wo es die echte Schrift tut, statt mit einer breiteren Ersatzschrift ihre Rahmen zu überfüllen. Schnitte, von denen die Familie keine Datei hat, werden unter dem Namen der lizenzierten Familie in den Schnitten der fallback-Familie mit gleicher Stärke und Schriftlage gesetzt, in den Vorschauen, im Layout-Worker, im PDF und auf der Kommandozeile. Eine Familie mit Dateien behält sie; von der fallback-Familie nimmt sie nur die Schriftlage, von der sie keine Datei hat, etwa eine Kursive, und die Stärken zwischen ihren eigenen Dateien werden wie bei jeder Familie gewählt. Im Bedienfeld Schriften nimmt Ersatzschrift (in der Familie, über ihren Dateien) den Namen auf; ein leeres Feld lässt die Familie, wie sie war. Das PDF eines so gesetzten Buches bettet die freie Schrift ein, das endgültige PDF entsteht also mit den lizenzierten Dateien. Seit postext 1.42. Seit postext 1.43 geht die freie Schrift auch dorthin, wohin die lizenzierte nicht darf: Ein EPUB oder ein HTML-Export, aus der Sandbox oder mit postext, enthält die Schnitte der Ersatzschrift unter dem Namen der lizenzierten, ebenso die SVG-Bilder, deren Text in dieser Schrift gesetzt ist; das Lesesystem setzt das Buch also in einer Schrift der Breite, für die seine Zeilen umbrochen wurden. Die eigenen Dateien der Schrift verlassen das Buch nie. Eine Schrift ohne fallback oder mit einem Ersatz ohne Datei wird wie bisher ohne Dateien aufgeführt; der EPUB-Tab der Sandbox listet die Schriften, die in einem Ersatz gesetzt sind.
#Verhalten bei der Darstellung
Unter der Haube:
- Ändert sich
customFonts, wird jede deklarierte Familie automatisch als EinträgeFontFaceindocument.fontsregistriert – so übernehmen der HTML-Betrachter, der Canvas-Viewport (der überdocument.fontsmisst) und jeder direkte CSS-Verweis die eigene Schrift, ohne dass der Benutzer zuerst den Schriftwähler öffnen muss. - Der Layout-Worker erhält dieselben ArrayBuffers über den bestehenden Übertragungsweg für Schriftdaten, sodass die Messung (
buildFontString, Pretext) genauso funktioniert wie bei einer Familie aus dem Katalog. - Wird eine Variante geändert oder entfernt, verwirft der Worker die zwischengespeicherte Schrift dieser Familie und registriert sie beim nächsten Build neu, sodass die Vorschauen mit dem aktuellen Variantensatz synchron bleiben.
- PDF-Export: Hochgeladene Binärdateien laufen durch dieselbe Pipeline
PdfFontProvider. Dateien.woff2werden dekomprimiert;.ttfund.otfwerden direkt durchgereicht..woffwird mit einer klaren Fehlermeldung abgewiesen (pdf-lib kann rohes WOFF nicht einbetten – laden Sie die Schrift als.woff2/.ttf/.otferneut hoch). OpenType mit CFF-Konturen (.otfmit der SignaturOTTO) wird ohne Teilmengenbildung eingebettet, weil der CFF-Subsetter von pdf-lib beimsave()jede Glyphe durchläuft und bei echten Schriften minutenlang hängen kann; der Verzicht auf die Teilmenge tauscht ein etwas größeres PDF gegen gleichmäßige Darstellungszeiten. Die Schrift wird als CFF deklariert (CIDFontType0,FontFile3/CIDFontType0C), sodass ein Druck-Preflight ihr Format erkennt; ein CID-basierter CFF-Schnitt (Source Han, die.otf-Dateien von Noto CJK) behält die TrueType-Deklaration.
#Warnungen zu fehlenden Schriften
Das Bedienfeld Prüfungen der Sandbox listet in seiner Gruppe Schriften drei Fehlerarten, die eigene Schriften betreffen (alle über denselben Schalter debug.warnings.missingFont eingeschaltet, der schon die allgemeine Warnung „nicht geladen“ steuert):
- Unbekannte Schriftfamilie – ein
fontFamilyverweist auf einen Namen, den weder Google Fonts noch Fontsource haben und der keine aktuell deklarierte eigene Familie ist. Die Warnung erscheint auch sofort, wenn Sie eine eigene Familie löschen, auf die noch ein FeldfontFamilyverweist, statt zu warten, bis das DOM es bemerkt. - Schriftvariante fehlt – die Familie existiert, aber das Buch verlangt von ihr eine Schriftstärke und einen Stil, für die es keine hochgeladene Datei gibt: fette Überschriften etwa in einer Familie, die nur den normalen Schnitt hat. Die Warnung nennt die fehlenden Kombinationen. Eine Schräglage, die der
fallbackder Familie liefert, gilt nicht als fehlend. - Doppelte Schriftvariante – zwei oder mehr hochgeladene Dateien teilen sich innerhalb einer Familie dieselbe Kombination aus Schriftstärke und Stil. Bei der Darstellung wird nur eine Datei verwendet; die Warnung erinnert Sie daran, die übrigen Einträge nachzustellen.
Ein Klick auf eine dieser Warnungen öffnet das Bedienfeld Schriften, damit Sie die fehlende Variante hochladen, die Familie wieder hinzufügen oder die Duplikate eindeutig machen können.
Sobald ein Layout existiert, listet das Bedienfeld auch die Warnung Ersatzschrift im Layout der Engine (fontFallback): eine Schrift, ohne die die Seiten gemessen wurden, weil sie fehlt oder weil der Browser sie aus einer anderen Schriftstärke oder Neigung gezeichnet hat. Eine Familie, die bereits als unbekannt oder als unvollständig gemeldet ist, wird nicht doppelt aufgeführt. Vor dem ersten Layout vertritt eine Prüfung gegen document.fonts diese Meldung.
Das Panel listet außerdem Zeichen aus einer anderen Schrift (glyphFallback): Zeichen, die der Text in einer Schrift ohne passende Glyphe setzt, einmal je Schrift, mit der generischen Familie, aus der sie stammen (serif, sans-serif, monospace), sofern die Prüfung das feststellen kann.
#Symbolschrift
Eine Textschrift hat selten die mathematischen Buchstaben und Operatoren (∪, ℵ, ∀), das Griechische oder die Pfeile, die ein Autor in einen Absatz tippt. symbolFont nennt eine Familie, die sie setzt: Jede Schrift des Dokuments führt sie nach ihrer eigenen, sodass Canvas, PDF, HTML und EPUB diese Zeichen mit ihr zeichnen statt als leeres Kästchen. 'Noto Sans Math' deckt fast die ganze Mathematik ab. Im Sandbox steht sie unter Grundtext → Symbolschrift. Die formatierte Word-Datei setzt diese Zeichen ebenfalls in Läufen dieser Schrift. Ihr normaler aufrechter Schnitt zeichnet sie für jede Strichstärke und Neigung des Textes.
Der Umbruch meldet jeden Absatz mit solchen Zeichen als glyphFallbackAt, mit der Familie, die sie zeichnet, oder keiner: Das PDF druckt sie dann als leere Kästchen. Der Sandbox markiert diese Zeichen auf der Seite, violett die von der Symbolschrift gezeichneten und rot die, die keine zeichnet.
#Ziffernarten
figureStyle wählt für die Schrift eines Textstils eine bestimmte Ziffernart, über die OpenType-Features der Schrift: Mediävalziffern im Fließtext, Versalziffern als Tabellenziffern in den Tabellen. Das Feld gibt es in bodyText, paragraphStyles[], headings und headings.levels[], headingStyles[], tableStyle und tableStyles[] (Kopf- und Körperzellen gleichermaßen), captionStyle (Bezeichnung und Beschreibung, auch im captionStyle eines Ressourcentyps) und in den Textelementen eines Designs (Kolumnentitel, Seitenzahlen, die Texte einer Kapitelauftaktseite oder einer Teilseite). In der Sandbox ist es das Feld Ziffern im Bedienfeld Gestaltung, neben der Schrift jedes dieser Stile (Grundtext → Schrift für den Grundtext).
| Wert | OpenType-Features | Ziffern |
|---|---|---|
'default' | keine | Die eigenen der Schrift. Hebt die Ziffern auf, die ein Stil erbt. |
'oldstyle' | onum | Mediävalziffern, mit Ober- und Unterlängen wie Kleinbuchstaben: Fließtext. |
'lining' | lnum | Versalziffern, in Versalhöhe: Überschriften, Text in Versalien. |
'tabular' | tnum | Tabellenziffern: alle Ziffern gleich breit, damit die Stellen einer Spalte untereinanderstehen. Die Form bleibt die der Schrift. |
'proportional' | pnum | Proportionalziffern: jede Ziffer in ihrer eigenen Breite. Die Form bleibt die der Schrift. |
'oldstyle-tabular' | onum + tnum | Mediävalziffern in einer Breite. |
'oldstyle-proportional' | onum + pnum | Mediävalziffern in eigenen Breiten. |
'lining-tabular' | lnum + tnum | Versalziffern in einer Breite: Tabellen, Fahrpläne, Preislisten. |
'lining-proportional' | lnum + pnum | Versalziffern in eigenen Breiten. |
Ein Paar legt eine Form und eine Breite fest. Eine Schrift ohne das Feature behält ihre eigenen Ziffern; prüfen Sie also, ob die Schrift onum oder lnum hat, bevor Sie sich darauf verlassen. Eine Familie, von der der Host keine Datei hat, etwa eine nur auf dem System des Lesers installierte Schrift (die Sandbox lädt solche nicht), nimmt keine Ziffernart an: Ihr Text behält die eigenen Ziffern dieser Schrift, in der Schrift selbst. Ein Buch, das Dateien unter diesem Namen hochlädt, bekommt die Ziffern. Die Schnitte, die Google Fonts und Fontsource ausliefern, lassen onum und lnum oft weg (die latin-Datei von Source Serif 4 behält nur pnum und tnum); mit einer solchen Datei behält ein Stil, der sie verlangt, die eigenen Ziffern der Schrift. Die vollständigen Dateien der Schriftgießerei haben sie: Laden Sie diese hoch, um Mediäval- oder Versalziffern zu bekommen. Eine generische Familie (serif, sans-serif) nimmt keine Features an. Ein Wert, der nicht in der Liste steht, wird als unbekannter Einstellungswert gemeldet (unknownConfigValue, siehe Konfigurationswarnungen) und wie nicht gesetzt gelesen.
const config: PostextConfig = {
bodyText: { fontFamily: 'EB Garamond', figureStyle: 'oldstyle' },
tableStyle: { figureStyle: 'lining-tabular' },
paragraphStyles: [{ id: 'timetable', figureStyle: 'lining-tabular' }],
headings: { figureStyle: 'lining' },
};Der Fließtext setzt Jahreszahlen und Seitenzahlen in Mediävalziffern, ebenso die Legenden und die Listen, die die Familie des Grundtexts übernehmen. Die Zellen aller Tabellen und die Absätze im Format timetable stellen ihre Stellen in Versalziffern als Tabellenziffern untereinander. Alle Überschriftenebenen setzen Versalziffern in der Familie der Überschriften.
#Welche Ziffern ein Stil bekommt
- Ein Stil, der seine Familie von einem anderen übernimmt, übernimmt auch dessen Ziffern. Absatzformate, Tabellen, Legenden, Listen und der Inhalt von Kästen übernehmen die Familie des Grundtexts, wenn sie keine eigene nennen;
bodyText.figureStylereicht also bis zu ihnen allen. - Ein Stil, der eine eigene
fontFamilynennt, setzt die Standardziffern dieser Schrift, sofern er nicht auchfigureStylesetzt. - Eine Überschriftenebene ohne eigenes
figureStyleübernimmtheadings.figureStyle, auch in ihrer eigenenfontFamily, wenn sie eine nennt. DasfigureStyleeines Überschriftenstils gilt für die Familie der Ebene, auf der der Stil verwendet wird. - Ein Textelement eines Designs nennt eine eigene Familie (
'EB Garamond'als Standard), daher erreichen die Ziffern des Grundtexts eine Seitenzahl nicht: setzen Sie dortfigureStyle: 'oldstyle', damit sie zu einem Text in Mediävalziffern passt. 'default'setzt die eigenen Ziffern der Schrift und hebt geerbte auf:paragraphStyles: [{ id: 'plain', figureStyle: 'default' }]nimmt diesem Format die Mediävalziffern des Grundtexts.
#Ziffern in jeder Ausgabe
Der Text wird mit den Features gemessen, sodass seine Zeilen in der Canvas-Vorschau, im HTML, im PDF und im EPUB, mit festem Layout wie umfließend, an denselben Breiten umbrechen.
- Canvas-Vorschau und Layout-Worker: Der Browser deklariert die Dateien der Basisfamilie ein zweites Mal, unter dem Namen einer Feature-Familie, mit dem Deskriptor
featureSettingsvonFontFace. Der Name besteht aus der Familie und ihren Features nach@(EB Garamond@onum,EB Garamond@lnum+tnum) und erscheint in Font-Strings und in manchen Warnungen. - HTML und EPUB (festes Layout und umfließend): die Basisfamilie, mit
font-variant-numeric(oldstyle-nums,lining-nums tabular-nums). - PDF: bettet die Dateien der Basisfamilie ein und setzt den Text mit den Features.
- Kommandozeile: Skia, die Canvas, mit der
postextzeichnet, wendet keine Features an. Die Kommandozeile registriert eine Kopie der Schrift, derencmapjedes Zeichen, das die Features ersetzen (die Ziffern), auf die Glyphe abbildet, die sie wählen. Übernommen werden nur einfache Ersetzungen; eine Schrift, die ihre Ziffern über kontextabhängige Ersetzungen erreicht, behält dort ihre eigenen.
#Farbpalette
Mit der Eigenschaft colorPalette von PostextConfig legen Sie einen wiederverwendbaren Satz benannter Farben an und verweisen von jedem ColorValue der Konfiguration darauf. Sie ist die Postext-Entsprechung von CSS Custom Properties oder dem Farbfelder-Bedienfeld von InDesign: Ändern Sie den Paletteneintrag einmal, und jede Farbe, die auf ihn zeigt, ändert sich im ganzen Dokument.
interface ColorPaletteEntry {
id: string; // stable identifier — referenced by ColorValue.paletteId
name: string; // human label shown in sandbox UIs
value: ColorValue;
}#Die Standardpalette
Postext wird mit einer Standardpalette aus einem einzigen Eintrag namens Main Color (id: 'main-color', Hex #295AA3) ausgeliefert. Mehrere Voreinstellungen – Überschriftenfarbe, Farbe für Fett und Kursiv im Grundtext, Farbe von :ref, Farben von Aufzählungszeichen und Nummern – verweisen über paletteId: 'main-color' auf diesen Eintrag; ändern Sie dieses eine Farbfeld, färben sich alle Teile des Dokuments um, die es verwenden.
Über drei Exporte können Sie die Standardpalette ansehen, klonen oder mit ihr vergleichen:
import {
DEFAULT_COLOR_PALETTE,
cloneDefaultColorPalette,
isDefaultColorPalette,
} from 'postext';
// Read-only snapshot of the shipped palette.
DEFAULT_COLOR_PALETTE;
// => [{ id: 'main-color', name: 'Main Color', value: { hex: '#295AA3', model: 'hex' } }]
// Independent copy — mutate this, not DEFAULT_COLOR_PALETTE.
const palette = cloneDefaultColorPalette();
// Detect whether a user has customised the palette at all.
isDefaultColorPalette(palette); // trueEine Palette steht auf der obersten Ebene der Konfiguration:
const config: PostextConfig = {
colorPalette: [
{ id: 'ink', name: 'Ink', value: { hex: '#0a0a0a', model: 'cmyk' } },
{ id: 'accent', name: 'Accent', value: { hex: '#b8860b', model: 'hex' } },
],
bodyText: { color: { hex: '#000000', model: 'cmyk', paletteId: 'ink' } },
headings: { color: { hex: '#000000', model: 'hex', paletteId: 'accent' } },
};#Auf einen Paletteneintrag verweisen
Jeder ColorValue der Konfiguration kann ein optionales Feld paletteId haben, das auf einen Eintrag in colorPalette zeigt: Seitenhintergrund, Farben des Grundtexts (einschließlich der Farbe von :ref), Überschriftenfarben, Spaltenlinien, Listenfarben, die Farben von Tabellen, Legenden, Chips und Kästen (Kasten, Streifen, Symbol, Markierung, Etikett, Titel, Text), Farben von Schnittmarken und Grundlinienraster, Debug-Anzeigen und jede Farbe einer Gestaltung – die Kolumnentitel, die Überschriftenauftakte und Gestaltungen in der Spalte, Gestaltungen und Kolumnentitel der Überschriftenstile, die Teiltitelseiten und die Teilzeilen des Inhaltsverzeichnisses (Text, Linie, Kastenfläche und -kontur, Buchstabenkontur, Initiale). Ist es vorhanden, haben hex / model des Paletteneintrags Vorrang vor dem daneben gespeicherten Ersatzwert hex / model. Der eingebettete Ersatzwert wird nur verwendet, wenn die Palette fehlt, leer ist oder diese ID nicht enthält – nützlich, wenn Sie eine Konfiguration ausliefern, die ein Werkzeug ohne Palettenunterstützung lesen wird.
Geändert in postext 1.5. Bis postext 1.4 erreichte die Palette nur eine feste Liste von Einstellungen: Die Farben der Gestaltungen (Kolumnentitel, Auftakte, Überschriftenstile, Teile, Zeilen des Inhaltsverzeichnisses), bodyText.referenceColor, die Etikettfarben der Kästen und die Farben für Fett und Kursiv im Kastentext behielten den hex, der neben ihrer paletteId gespeichert war. Ein Dokument, dessen gespeicherter Wert vom Paletteneintrag abweicht – jedes, das nach der Änderung des Eintrags in der Sandbox bearbeitet wurde, und jedes :ref, wenn die Main Color nicht #295AA3 ist –, zeigt jetzt die Palettenfarbe, wie es die Verknüpfung verlangt. Um eine Farbe so zu behalten, wie sie war, entfernen Sie ihre paletteId.
Ein Tonwert eines Paletteneintrags. Mit paletteId malt tint (0–100) den Eintrag in dieser Stärke: { hex: '#eef2f8', model: 'hex', paletteId: 'main-color', tint: 8 } ist die Hauptfarbe zu 8 %, ein Kastengrund, der der Hauptfarbe folgt, wenn sich die Palette ändert. Die Palette eines Teils oder Abschnitts behält die Stärke überall, wo sie umfärbt: im Fließtext, in der Seitenfarbe, in den Zeilennummern, in Tabellenzellen, in den Gestaltungsfeldern und im Word-Export. Der Tonwert behält das Modell des Eintrags: Ein CMYK-Eintrag gibt seine Druckfarben skaliert aus (10 % von 100 60 0 10 druckt 10 6 0 1), ein Sonderfarben-Eintrag gibt einen Tonwert derselben Druckfarbe auf ihrer eigenen Platte, und eine Bildschirmfarbe mischt sich mit der Seitenfarbe (page.backgroundColor, ohne Angabe Weiß; unter einem CMYK-Tonwert fügt eine in CMYK angelegte Seitenfarbe ihre eigenen Druckfarben hinzu). hex hält den getönten Wert, den Ersatzwert ohne den Eintrag. Ein Sonderfarben-Tonwert trägt nur eine Druckfarbe: Auf einer farbigen Seite spart er die Seitenfarbe aus, es sei denn, er überdruckt. In der Sandbox hat die Farbauswahl einer verknüpften Farbe ein Feld Tonwert.
#Wie Paletten angewendet werden
buildDocument wendet die Palette an zwei Stellen an, damit verknüpfte Farben sowohl für ausdrücklich angegebene Werte als auch für später ergänzte Voreinstellungen funktionieren:
applyPaletteToConfig(config)– löst jedenColorValueder rohen Benutzerkonfiguration auf, der einepaletteIdhat. Nützlich, wenn Sie sehen wollen, was die Engine tatsächlich erhält.applyPaletteToResolvedConfig(resolved, palette)– läuft, nachdem die Voreinstellungen aufgelöst sind, und schreibt die an die Palette gekoppelten Voreinstellungen (Überschriftenfarbe, Farbe für Fett und Kursiv im Grundtext, Farbe von:ref, Listenfarben, die Farben der Standardgestaltungen) passend zur aktiven Palette um.
Beide durchlaufen die gesamte Konfiguration, sodass keine an die Palette gekoppelte Farbe zurückbleibt. Die meisten Farben des Textflusses (Grundtext, Überschriften, Listen, Tabellen, Legenden, Chips, Kasten, Titel und Text des Kastens) kommen als einfache Werte heraus. Jede andere – die Farben der Gestaltungen, die Farbe von :ref, die Etiketten der Kästen – übernimmt hex / model der Palette und behält ihre paletteId. Über diese Verknüpfung überschreiben das Attribut palette eines Teils und das palette eines Überschriftenstils die Farben auf ihren Seiten (siehe Teile); sie muss daher erhalten bleiben. htmlViewer.overrides bleibt, wie es geschrieben ist: Der HTML-Betrachter führt es zuerst zusammen, und eine Palette darin gilt dann für alles, auch für die Gestaltungen.
Sie müssen diese Funktionen selten selbst aufrufen, aber beide werden exportiert, damit Sie sie untersuchen oder wiederverwenden können:
import {
applyPaletteToConfig,
applyPaletteToResolvedConfig,
resolveColorValue,
} from 'postext';
const flat = applyPaletteToConfig(config);
// Every ColorValue with a paletteId in the raw config now carries the
// palette entry's hex/model (a design colour keeps its paletteId).
// `applyPaletteToResolvedConfig` is typically handled by buildDocument; use it
// directly if you build a ResolvedConfig yourself and want the palette applied.resolveColorValue(value, palette, fallback) ist die Variante für einen einzelnen Wert, praktisch, wenn Sie Konfigurationen imperativ zusammensetzen und jeweils eine Farbe auflösen müssen.
#Die Palette bearbeiten
Eine Farbe, deren paletteId auf keinen Eintrag verweist, erscheint mit ihrem gespeicherten hex / model, der älter sein kann als die Farbe, die der Eintrag ihr gab. Schreiben Sie daher vor dem Entfernen eines Eintrags jeden damit verknüpften ColorValue als einfache Farbe mit dem aktuellen Wert des Eintrags um. Der Abschnitt Palette der Sandbox (Gestaltung → Farben) tut das, wenn Sie einen Eintrag löschen, wo immer die Farbe steht (Gestaltungen und Etiketten der Kästen eingeschlossen), und seine Bestätigung listet jede Einstellung auf, die den Eintrag verwendet: mit Namen oder mit ihrem Pfad in der Konfiguration (header.elements[2].color).
#HTML-Betrachter
Die Eigenschaft htmlViewer steuert, wie das HTML-Backend die Seiten am Bildschirm anordnet. Sie wirkt nur, wenn Sie mit renderToHtml / renderToHtmlIndexed rendern; Canvas- und PDF-Pfad ignorieren sie vollständig – sie verwenden direkt die konfigurierten page.width, page.height und page.dpi.
interface HtmlViewerConfig {
maxCharsPerLine?: number; // Target column width, in characters of the body font.
columnGap?: number; // Horizontal gap between columns in multi-column mode (px).
optimalLineBreaking?: boolean; // Use Knuth–Plass inside the HTML viewer instead of greedy.
overrides?: HtmlViewerOverrides; // Screen-only partial config merged over the document config.
}
type HtmlViewerOverrides = Omit<PostextConfig, 'htmlViewer'>;| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
maxCharsPerLine | number | 70 | Zielzeilenlänge jeder dargestellten Spalte, angegeben in Zeichen der Grundschrift. Der Viewport misst eine repräsentative Textprobe dieser Länge, um daraus die tatsächliche Breite in Pixeln abzuleiten – so passt sich das Ergebnis an jede Kombination aus Proportionalschrift und Schriftgröße an. |
columnGap | number | 50 | Horizontaler Abstand in CSS-Pixeln zwischen den Spalten, wenn der Betrachter mehrspaltig darstellt. Im einspaltigen Modus ohne Wirkung. |
optimalLineBreaking | boolean | true | Bricht die Zeilen des HTML-Betrachters nach Knuth-Plass um, mit denselben optimalen Umbrüchen wie Canvas und PDF: Die Bildschirmausgabe gibt gegenüber der gedruckten nichts an Qualität auf. Mit true folgt der Betrachter bodyText.: Ein Dokument, das seinen Text Zeile für Zeile setzt, behält das auf dem Bildschirm. Mit false wird jede Zeile gefüllt, bevor die nächste beginnt, was bei einem sehr langen Buch schneller ist. Eine unter configVersion 21 oder älter gespeicherte Konfiguration, die den Wert nicht setzt, wird als false gelesen, so wie sie damals gesetzt wurde. |
overrides | HtmlViewerOverrides | — | Eine Teilkonfiguration des Dokuments, die nur am Bildschirm gilt. Der HTML-Betrachter führt sie vor dem Setzen über die Dokumentkonfiguration zusammen (applyHtmlViewerOverrides); Canvas und PDF ignorieren sie. Objekte werden rekursiv zusammengeführt; ein Array levels (Überschriften, Listen, Inhaltsverzeichnis) wird Eintrag für Eintrag über level zusammengeführt; jedes andere Array – die elements eines Gestaltungsfelds, calloutStyles, colorPalette … – ersetzt das Basis-Array vollständig. Typischer Einsatz: ein Kapitelauftakt ohne die Druckbänder oder eine Teilseite, deren Titel sich am Nummernzeichen statt an einer festen Breite des Endformats umbricht. Die Sandbox bearbeitet sie als JSON. |
const config: PostextConfig = {
headings: { levels: [{ level: 1, span: 'page', breakBefore: { enabled: true } }] },
htmlViewer: {
// On screen, chapters flow on without the page-span opener.
overrides: { headings: { levels: [{ level: 1, span: 'column', breakBefore: { enabled: false } }] } },
},
};Resolver und Stripper folgen demselben Muster wie in den anderen Abschnitten:
import {
DEFAULT_HTML_VIEWER_CONFIG,
resolveHtmlViewerConfig,
stripHtmlViewerDefaults,
} from 'postext';
const resolved = resolveHtmlViewerConfig(config.htmlViewer);
// => { maxCharsPerLine: 70, columnGap: 50, optimalLineBreaking: true }
const minimal = stripHtmlViewerDefaults(config.htmlViewer);
// => undefined when everything matches the defaultsEin vollständiges Beispiel finden Sie unter Den HTML-Betrachter einbinden.
#Canvas-Ansicht
Die Eigenschaft canvasViewer legt den Abstand zwischen den Seiten im Canvas-Tab der Sandbox fest (seit postext 1.43). Sie gehört zur Ansicht, nicht zum Buch: Die Werte sind Bildschirmpixel bei jedem Zoom, und eine Änderung verschiebt die Seiten auf dem Bildschirm, ohne das Buch neu zu setzen. Seitenzahl, gespeicherte Umbrüche und PDF bleiben, wie sie waren. PDF, HTML-Betrachter und die anderen Ausgaben ignorieren sie. Ein Buch, dessen Bilder über die Doppelseite laufen, setzt pageGap: 0.
interface CanvasViewerConfig {
pageGap?: number; // Space between the two pages of a pair (px).
rowGap?: number; // Space between one row of pages and the next (px).
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
pageGap | number | 24 | Abstand in Bildschirmpixeln zwischen linker und rechter Seite eines Paars in der Doppelseitenansicht. Eine ganze Zahl von 0 bis 200. Bei 0 berühren sich die beiden Seiten, und das Canvas zeichnet an der Naht weder Schatten noch abgerundete Ecken; ein Bild oder eine Gestaltung über die Doppelseite wirkt als Einheit. Die Einzelseitenansicht kennt keine Paare. |
rowGap | number | 24 | Abstand in Bildschirmpixeln zwischen einer Seitenreihe und der nächsten, in beiden Ansichten. Eine ganze Zahl von 0 bis 200. |
const config: PostextConfig = {
// Ein Bild läuft über die Doppelseite: Die beiden Seiten werden aneinandergesetzt gezeigt.
canvasViewer: { pageGap: 0 },
};import {
DEFAULT_CANVAS_VIEWER_CONFIG,
resolveCanvasViewerConfig,
stripCanvasViewerDefaults,
} from 'postext';
resolveCanvasViewerConfig(config.canvasViewer);
// => { pageGap: 0, rowGap: 24 }
stripCanvasViewerDefaults({ pageGap: 24, rowGap: 24 });
// => undefined when everything matches the defaultsEin Wert, der keine ganze Zahl von 0 bis 200 ist, wird als nächstgelegene Zahl dieses Bereichs gelesen, ein Wert, der keine Zahl ist, als 24, und als unbekannter Einstellungswert gemeldet (canvasViewer.pageGap). Die Sandbox hat beide Felder unter Gestaltung › Export › Canvas (Seitenabstand).
#PDF-Erzeugung (Konfiguration)
Die Eigenschaft pdfGeneration steuert, wie das PDF-Backend das fertige Dokument ausgibt. Diese Einstellungen liest das Paket postext-pdf beim Export; Canvas- und HTML-Betrachter ignorieren sie. forms ist die Ausnahme: Das Canvas liest es auch, sodass seine Formularfelder denen des PDF entsprechen.
buildDocument übernimmt sie in den VDT als doc.config.pdfGeneration, und renderToPdf nimmt jede Einstellung von der ersten Stelle, die sie angibt:
- aus seinen eigenen Optionen (
outlines,accessible,colorSpace,baselineGrid,forms); - aus
pdfGenerationdes ersten Dokuments, das es rendert (in einem Buch gelten die Einstellungen des ersten Kapitels für die ganze Datei); - aus den Voreinstellungen: Lesezeichen und Tagging an, RGB-Farbe.
renderToPdf(doc, { fontProvider }) folgt also der Konfiguration, und eine an renderToPdf übergebene Option gewinnt nur für diese eine Einstellung. forceColorSpace und colorSpace stehen zusammen für die Option colorSpace: Das colorSpace der Konfiguration gilt, solange forceColorSpace an ist, und das PDF ist RGB, solange es aus ist. Frühere Versionen von postext-pdf lasen nur die Optionen; eine Konfiguration, die pdfGeneration setzt, ändert jetzt das PDF eines Aufrufers, der keine Optionen übergibt.
type PdfColorSpace = 'rgb' | 'cmyk' | 'grayscale';
interface PdfGenerationConfig {
outlines?: boolean; // Emit PDF bookmarks from the heading tree.
forceColorSpace?: boolean; // Convert every colour to `colorSpace`.
colorSpace?: PdfColorSpace; // Target space used when `forceColorSpace` is true.
accessible?: boolean; // Tagged, PDF/UA-oriented output (structure tree, alt text, language).
baselineGrid?: boolean; // Draw the `page.baselineGrid` grid in the PDF as well.
forms?: PdfFormsConfig; // Formularfelder: Währung, Trennzeichen, Schrift.
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
outlines | boolean | true | Gibt aus der Überschriftenhierarchie PDF-Lesezeichen (Outlines) aus, damit Leser in der Seitenleiste eines PDF-Betrachters direkt zu jeder Überschrift springen können. Schalten Sie sie bei Dokumenten ab, in denen der Überschriftenbaum keinen Sinn ergibt (z. B. einseitige Plakate). |
forceColorSpace | boolean | false | Ist der Wert true, wird jede Farbe des gerenderten PDFs beim Export in colorSpace umgerechnet. Lassen Sie ihn bei PDFs für den Bildschirm aus, deren Eingangsfarben schon im gewünschten Farbraum liegen; schalten Sie ihn ein, um bei gemischten Quellen einen einzigen Farbraum sicherzustellen. |
colorSpace | 'rgb' | 'cmyk' | 'grayscale' | 'cmyk' | Zielfarbraum, wenn forceColorSpace an ist. Verwenden Sie 'cmyk' für den Offsetdruck, 'rgb' für reine Bildschirm-PDFs und 'grayscale' für Schwarz-Weiß-Andrucke. Ohne Wirkung, wenn forceColorSpace false ist. CMYK wird über das Ausgabeprofil von print (standardmäßig FOGRA39) mit dessen Schwarzbehandlung separiert, und RGB-Bilder werden ebenfalls umgerechnet; ein dort gewählter PDF/X-Standard schreibt CMYK, unabhängig von diesem Wert. |
accessible | boolean | true | Gibt ein barrierefreies, getaggtes PDF nach PDF/UA-1 aus: einen logischen Strukturbaum in Lesereihenfolge (Überschriften, die nie eine Ebene überspringen, Absätze, Listen, Blockzitate, Kästen, Tabellen mit Kopfzellen, Abbildungen mit Alternativtext und Legende, Formeln, anklickbare Verweise als Links, der Inhalt eines :::toc als ein TOC mit einem TOCI je Zeile: die Nummer der Zeile ein Lbl, Titel und Seite eine Reference, die den Link enthält), Titel und Sprache des Dokuments (das oberste locale), die PDF/UA-Kennung in den XMP-Metadaten und jedes schmückende Element (Seitenhintergrund, Linien, Grundlinienraster, Kopf- und Fußzeilen, Schnittmarken, wiederholte Tabellenköpfe, der wiederholte Titel und der Fortsetzungshinweis eines geteilten Kastens) als Artefakt markiert, damit Screenreader es überspringen. Eine Abbildung ohne altText greift auf ihre Legende zurück, dann auf ihre Bezeichnung. Eine gleitende Abbildung oder Tabelle wird direkt nach dem Text gelesen, der sie zuerst zitiert, oder nach dem Text vor ihrer Zeile ::resource, und ein gleitender Kasten nach dem Text vor seiner öffnenden Zeile, auch wenn das Gleitobjekt auf einer späteren Seite steht; eine Liste oder das Inhaltsverzeichnis, die hinter einem Gleitobjekt weiterlaufen, bleiben ein Element, und eine Liste in einem gleitenden oder an der Seite verankerten Kasten (placement: 'fixed') ist eine einzige Liste. Schalten Sie es nur für Druckvorlagen ab, bei denen die zusätzliche Struktur unerwünscht ist. |
baselineGrid | boolean | true | Zeichnet das Grundlinienraster auch ins PDF, solange page.baselineGrid eingeschaltet ist. Standardmäßig an, wie bisher; false lässt das Raster eine Hilfe zum Prüfen der Seite am Bildschirm sein, außerhalb des PDF, während Canvas und HTML-Viewer es weiter zeigen. Im Sandbox: Grundlinienraster im PDF, im Abschnitt PDF. |
forms | PdfFormsConfig | undefined | Wie Formularfelder Zahlen schreiben und in welcher Schrift sie Werte zeigen: currency (Standard €), currencyBefore (Standard true), separatorStyle (0 bis 3; ohne Angabe nach der Sprache des Dokuments) und font ('chip', der Standard, 'helvetica' oder { family, weight?, style? }). Die Option forms von renderToPdf und des Canvas hat Feld für Feld Vorrang. Nur für die Ausgabe: Der Satz ändert sich nicht. Siehe Formularfelder. |
pdfGeneration: {
outlines: true,
accessible: true,
forceColorSpace: true,
colorSpace: 'cmyk',
}Resolver und Stripper entsprechen den anderen Abschnitten:
import {
DEFAULT_PDF_GENERATION_CONFIG,
resolvePdfGenerationConfig,
stripPdfGenerationDefaults,
} from 'postext';
const resolved = resolvePdfGenerationConfig(config.pdfGeneration);
// => { outlines: true, forceColorSpace: false, colorSpace: 'cmyk', accessible: true }
const minimal = stripPdfGenerationDefaults(config.pdfGeneration);
// => undefined when everything matches the defaultsDas vollständige Exportrezept finden Sie unter PDFs erzeugen.
#Druckvorstufe (Konfiguration)
Die Eigenschaft print legt fest, wie ein Buch in den Druck geht: den PDF/X-Standard der Datei, das Ausgabeprofil, mit dem ihr CMYK separiert wird, wie Schwarz druckt und die Schwellenwerte des Preflights. Das Layout ignoriert sie, ihre Änderung verschiebt also nie eine Zeile. Drei Stellen lesen sie: postext-pdf beim Schreiben der Datei, preflightDocument beim Prüfen eines gesetzten Dokuments und die Druckvorschau des Canvas- und des Folio-Betrachters.
type PdfXStandard = 'none' | 'pdfx1a' | 'pdfx4';
interface PrintConfig {
standard?: PdfXStandard; // 'none': an ordinary PDF.
outputProfile?: string; // A catalogue id ('fogra39', 'fogra51'…) or 'custom'.
customProfile?: CustomOutputProfile; // An uploaded .icc file.
renderingIntent?: 'relative' | 'perceptual';
blackPointCompensation?: boolean;
convertImages?: boolean; // Separate RGB pictures (PDF/X-1a always does).
inkLimit?: number; // Total area coverage, percent.
black?: PrintBlackConfig;
preflight?: PrintPreflightConfig;
inks?: PrintInk[]; // The ink table: renames, aliases, process.
plates?: PrintPlatesConfig; // The plates the job prints on: two-ink printing.
imageColor?: PrintImageColorConfig; // How pictures are read: profiles, greyscale.
}
interface CustomOutputProfile {
name: string; // Its description, or the file name.
fileId: string; // The stored .icc file.
registryName?: string; // The condition's ICC registry name (FOGRA51…), else 'Custom'.
inkLimit?: number;
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
standard | 'none' | 'pdfx1a' | 'pdfx4' | 'none' | Die PDF/X-Variante der Datei. 'pdfx1a' schreibt PDF/X-1a:2003: nur CMYK und Grau, keine Transparenz, von jeder Druckerei angenommen. 'pdfx4' schreibt PDF/X-4: Transparenz und Farbmanagement bleiben erhalten, für aktuelle Workflows. Beide separieren jede Farbe über das Ausgabeprofil, unabhängig von pdfGeneration.colorSpace. |
outputProfile | string | 'fogra39' | Die Druckbedingung, für die CMYK separiert wird: eine ID aus dem Profilkatalog oder 'custom' für customProfile. Eine ID, die der Katalog nicht kennt, oder 'custom' ohne Datei fällt auf den Standardwert zurück und erzeugt eine Konfigurationswarnung. |
customProfile | CustomOutputProfile | keiner | Ein CMYK-Ausgabeprofil, das Sie selbst liefern, nämlich das, das Ihnen Ihre Druckerei gibt (etwa PSOcoated_v3.icc der ECI). Seine Bytes werden wie eine Schrift getrennt gespeichert; renderToPdf nimmt sie als Option outputProfile. registryName wird als Kennung der Bedingung des Output Intents geschrieben. |
renderingIntent | 'relative' | 'perceptual' | 'relative' | Relativ farbmetrisch hält die Farben, die die Druckmaschine drucken kann, exakt und beschneidet die übrigen auf die nächstgelegene druckbare; wahrnehmungsorientiert staucht den ganzen Bereich, sodass Farben außerhalb des Farbumfangs ihre Verhältnisse zueinander behalten. |
blackPointCompensation | boolean | true | Bildet beim relativen Intent das Schwarz des Bildschirms auf das tiefste Schwarz ab, das die Druckmaschine druckt, sodass die dunkelsten Töne ihre Zeichnung behalten, statt zuzulaufen. |
convertImages | boolean | true | Separiert RGB-Bilder mit dem Profil nach CMYK. PDF/X-1a tut das immer. In PDF/X-4 behält false sie in RGB, über /DefaultRGB der Seiten als sRGB gekennzeichnet, damit das RIP der Druckerei sie umrechnet. CMYK- und Graustufen-JPEGs werden immer unverändert eingebettet. |
inkLimit | number | der des Profils | Die höchste Summe aus C+M+Y+K in Prozent, die der Preflight akzeptiert. Standardmäßig der Grenzwert, auf den das Profil separiert (300 % für die meisten Offsetbedingungen, 230 % für Zeitungspapier IFRA26). |
black | PrintBlackConfig | siehe Schwarz | Grautöne nur in K, Überdrucken und Tiefschwarz. |
preflight | PrintPreflightConfig | siehe Preflight | Was der Preflight prüft und seine Schwellenwerte. |
print: {
standard: 'pdfx4',
outputProfile: 'fogra51',
black: { richBlackColor: { c: 60, m: 40, y: 40, k: 100 } },
preflight: { minImageResolution: 300, safeZone: { value: 5, unit: 'mm' } },
}#Ausgabeprofile
postext liefert diese CMYK-Ausgabeprofile in seinem Ordner icc/ aus (postext/icc/<id>.icc auf jedem npm-CDN und /icc/<id>.icc auf postext.dev). Für keines sind urheberrechtliche Einschränkungen bekannt (CC0): die FOGRA-, GRACoL-, SWOP- und Zeitungsprofile von colord, erzeugt aus den Charakterisierungsdaten der jeweiligen Bedingung, sowie FOGRA51 und FOGRA52, von postext mit ArgyllCMS aus den Daten der Fogra selbst gebaut. Die Profile der ECI (ISO Coated v2, PSO Coated v3, PSO Uncoated v3) beschreiben dieselben Bedingungen, dürfen aber nicht weitergegeben werden; laden Sie sie als eigenes Profil hoch, wenn Ihre Druckerei danach fragt.
| ID | Bedingung | Registry-Name | Farbauftrag max. |
|---|---|---|---|
fogra39 | Offset, gestrichenes Papier (Bedingung ISO Coated v2) | FOGRA39 | 300 % |
fogra51 | Offset, Premium gestrichen (Bedingung PSO Coated v3) | FOGRA51 | 300 % |
fogra52 | Offset, holzfrei ungestrichen (Bedingung PSO Uncoated v3) | FOGRA52 | 300 % |
fogra47 | Offset, ungestrichen weiß (PSO Uncoated ISO 12647) | FOGRA47 | 300 % |
fogra29 | Offset, ungestrichen weiß | FOGRA29 | 300 % |
fogra30 | Offset, ungestrichen gelblich | FOGRA30 | 340 % |
fogra27 | Offset, gestrichen (ISO 12647-2:1996) | FOGRA27 | 300 % |
fogra28 | Heatset-Rollenoffset, LWC glänzend | FOGRA28 | 300 % |
fogra45 | Heatset-Rollenoffset, LWC verbessert | FOGRA45 | 300 % |
fogra40 | Heatset-Rollenoffset, SC-Papier | FOGRA40 | 340 % |
gracol2006 | GRACoL 2006, Grad 1 gestrichen | CGATS TR 006 | 300 % |
swop3 | SWOP 2006, Grad 3 gestrichen | CGATS TR 003 | 300 % |
swop5 | SWOP 2006, Grad 5 gestrichen | CGATS TR 005 | 300 % |
ifra26 | Coldset-Zeitungspapier (ISO 12647-3) | IFRA26 | 230 % |
snap2007 | Zeitungspapier SNAP 2007 | CGATS TR 002 | 320 % |
renderToPdf liest die Bytes des Profils aus seiner Option outputProfile; ohne sie lädt es die Katalogdatei von profileBaseUrl (standardmäßig https://cdn.jsdelivr.net/npm/postext/icc/). Eine PDF/X-Ausgabe, deren Profil sich nicht laden lässt, scheitert; eine einfache CMYK-Ausgabe greift mit der Warnung outputProfileUnavailable auf die Lehrbuchformel zurück.
import { readFile } from 'node:fs/promises';
import { renderToPdf } from 'postext-pdf';
const pdf = await renderToPdf(doc, {
fontProvider,
print: { standard: 'pdfx1a', outputProfile: 'fogra39' },
outputProfile: await readFile('node_modules/postext/icc/fogra39.icc'),
});#PDF/X-1a und PDF/X-4
Beide Standards schreiben:
- den Output Intent (
GTS_PDFX), der die Druckbedingung nennt und das Zielprofil einbettet; - die Kennung im Info-Dictionary (
GTS_PDFXVersion,/Trapped /False, Titel und Datumsangaben) und in den XMP-Metadaten (pdfxid:GTSPDFXVersion, die Dokument- und Versions-IDs), zusammengeführt mit der PDF/UA-Kennung, wenn die Datei getaggt ist; - auf jeder Seite eine TrimBox und eine BleedBox (die ganze Seite, wenn es keine Schnittlinien gibt);
- die
/IDim Trailer; - jede Farbe in DeviceCMYK (oder Grau) über das Profil und die Schnittmarken in Passerfarbe;
- keine Link-Annotationen: Eine Datei für die Druckmaschine enthält keine innerhalb ihrer BleedBox, daher entfallen die Links des Bildschirm-PDFs (die Lesezeichen bleiben).
PDF/X-1a:2003 ist PDF 1.4 ohne Objektströme und kennt keine Transparenz: Eine durchscheinende Farbe wird so gesetzt, wie sie auf dem Papier drucken würde, das Alpha eines Bildes wird auf Weiß verrechnet, und das Debug-Seitennegativ entfällt (mit der Warnung pageNegativeIgnored). PDF/X-4 ist PDF 1.6: Die Transparenz bleibt, jede Seite erhält eine Transparenzgruppe, die in CMYK verrechnet, und RGB-Bilder, die convertImages: false beibehält, werden über /DefaultRGB als sRGB gekennzeichnet.
Eine PDF-Druckvorlage (svg.pdfFileId) wird unverändert eingebettet, ihre Farben, Schriften und Transparenz sind also ihre eigenen; der Preflight meldet, was sie mitbringt.
#Schwarz
interface PrintBlackConfig {
kOnlyNeutrals?: boolean; // Greys and black in black ink only.
overprint?: boolean; // 100 % K overprints.
richBlack?: boolean; // Large black areas in rich black.
richBlackColor?: CmykPercent; // { c, m, y, k } in percent.
richBlackMinSize?: Dimension; // The smaller side an area needs.
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
kOnlyNeutrals | boolean | true | Eine neutrale Farbe (#000000, #808080 …) druckt allein mit schwarzer Farbe, ihr K so gewählt, dass die Helligkeit stimmt, nie als vierfarbiges Grau, das sich mit dem Passer verschiebt. Bilder behalten den Schwarzaufbau des Profils. |
overprint | boolean | true | Alles, was allein in 100 % K malt (schwarzer Text, Linien, Konturen, kleine schwarze Formen), überdruckt (op/OP mit OPM 1), sodass eine Druckplatte, die sich in der Maschine verschiebt, nie einen weißen Rand darum aufreißt. Alles andere spart aus; Bilder und Verläufe überdrucken nie. |
richBlack | boolean | true | Eine schwarze Fläche, deren kleinere Seite richBlackMinSize erreicht (ein Hintergrund, ein Band, ein Kasten), druckt in richBlackColor und spart aus, sodass sie tief statt dunkelgrau wirkt. Text wird nie zu Tiefschwarz. |
richBlackColor | CmykPercent | { c: 60, m: 40, y: 40, k: 100 } | Der Aufbau des Tiefschwarz in Prozent. Halten Sie seine Summe unter dem maximalen Farbauftrag; der Preflight prüft das. |
richBlackMinSize | Dimension | 6mm | Die kleinere Seite, die eine schwarze Fläche braucht, um in Tiefschwarz zu drucken. |
#Druckvorschau
Eine Canvas-Seite lässt sich so malen, wie sie drucken wird. createPrintPreview(transform, print, { paper, dpi, grayscale }) baut den Softproof einer Einrichtung: Jedes Pixel wird über das Profil separiert (neutrale Farben nur in K, wie im PDF) und auf dem Bildschirm zurückgezeigt, auf dem eigenen Weiß des Papiers, wenn paper true ist; schwarze Flächen, die groß genug für Tiefschwarz sind, erscheinen als Tiefschwarz. Mit grayscale ist der Proof ein Graustufendruck – ein in Graustufen gezwungenes PDF druckt die Luminanz jeder Farbe allein in Schwarz, ohne Tiefschwarz. Übergeben Sie ihn renderPageToCanvas als printPreview. Für eine Arbeitsansicht statt eines Proofs fügt guides die Linien für Endformat, Anschnitt und Sicherheitsabstand hinzu, und marksFor umrandet Bereiche einer Seite (die rects des Preflights); die Sandbox lässt beides weg, ihre Vorschau zeigt also nur den Druck. postext-folio nimmt dasselbe Objekt als printPreview; geben Sie dem Buch bei paper: true währenddessen einen neutralen Papierton (folio.paper.shade), sonst wird das Papier doppelt getönt.
import { createPrintPreview, renderPageToCanvas } from 'postext';
const preview = createPrintPreview(transform, print, { paper: true, dpi: doc.config.page.dpi });
renderPageToCanvas(page, doc, canvas, {
printPreview: { ...preview, guides: { safeZonePx: 59 }, marksFor: () => issues.map((i) => i.rect!).filter(Boolean) },
});#Farb-Engine
Das Farbmanagement, das postext verwendet, wird für Ihre eigenen Werkzeuge exportiert. Es liest ICC-Profile der Versionen 2 und 4 (Matrix/TRC und die Lookup-Tabellen mft1, mft2, mAB, mBA) in reinem TypeScript, ohne WebAssembly.
parseIccProfile(bytes)liest ein Profil;deviceChannels(profile)gibt seine Kanalzahl an.outputTransform(profile, { intent, blackPointCompensation, preserveNeutrals })gibtfromRgb(r, g, b)(sRGB 0..1 → CMYK 0..1),toLab(cmyk, paper?)undproof(cmyk, paper?)(CMYK → Bildschirm-sRGB) zurück.cmykToLab,labToCmyk,srgbToLab,labToSrgb,deltaEundtotalAreaCoveragesind die einzelnen Umrechnungen;buildRgbLut/sampleRgbLuterzeugen und lesen dichte Lookup-Tabellen für die Arbeit an Pixeln.OUTPUT_PROFILES,outputProfileInfo(id)undloadOutputProfile(id, baseUrl?)liefern den Katalog;srgbProfileBytes()schreibt das sRGB-Profil, mit dem PDF/X-4 RGB kennzeichnet;authoredCmykColors(config)listet die Farben auf, die eine Konfiguration in CMYK angelegt hat.
Resolver und Stripper entsprechen den anderen Abschnitten: resolvePrintConfig, stripPrintDefaults und profileInkLimit(config) (der Grenzwert des Profils, das eine Konfiguration nennt, vor jeder Überschreibung durch inkLimit), mit DEFAULT_PRINT_CONFIG, DEFAULT_PRINT_BLACK_CONFIG, DEFAULT_PRINT_PREFLIGHT_CONFIG und DEFAULT_RICH_BLACK.
#Kontrastprüfung (Konfiguration)
Die Eigenschaft contrast stellt die Prüfung ein, die feststellt, ob sich der Text eines Buches lesen lässt: jede Textfarbe gegen den Untergrund, auf dem sie steht. Das Layout ignoriert sie, ihre Änderung verschiebt also nie eine Zeile. contrastDocument liest sie beim Prüfen eines gesetzten Dokuments, die Sandbox listet die Befunde unter Prüfungen auf und zeigt das Verhältnis neben jedem Farbfeld, und postext check gibt sie aus.
interface ContrastConfig {
enabled?: boolean;
level?: 'AA' | 'AAA';
mode?: 'auto' | 'screen' | 'print' | 'both';
reversedText?: {
enabled?: boolean;
minSize?: Dimension;
minFineSize?: Dimension;
lightWeight?: number;
};
allow?: { fg?: string; bg?: string; style?: string; reason: string }[];
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
enabled | boolean | true | Führt die Prüfung aus. |
level | 'AA' | 'AAA' | 'AA' | Die WCAG-2-Stufe, an der die Verhältnisse gemessen werden. Siehe Schwellenwerte. |
mode | string | 'auto' | Die geprüfte Wiedergabe: 'screen', 'print', 'both' oder 'auto', das immer den Bildschirm prüft und zusätzlich den Druck bei einem Buch, das für den Druck eingerichtet ist (ein PDF/X-Standard in print.standard, ein CMYK-PDF in pdfGeneration oder Schnittmarken in page.cutLines). |
reversedText.enabled | boolean | true | Meldet negativen Text in der Druckprüfung. |
reversedText.minSize | Dimension | 8pt | Negativer Text unter dieser Größe wird gemeldet. |
reversedText.minFineSize | Dimension | 12pt | Dasselbe für Kursive und leichte Schnitte, deren Striche dünner sind. |
reversedText.lightWeight | number | 300 | Eine Schriftstärke bis einschließlich dieser gilt als leicht. |
allow | ContrastAllowEntry[] | [] | Farbpaare, die die Prüfung akzeptiert, jedes mit seinem reason: nach Textfarbe (fg) und Grund (bg), nach dem style, in dem der Text gesetzt ist, oder nach beidem. Siehe Akzeptierte Paare. |
Ein level oder ein mode, das anders geschrieben ist, wird als Standardwert gelesen und als unbekannter Einstellungswert gemeldet (siehe Konfigurationswarnungen).
#Akzeptierte Paare
Eine Portierung behält die Palette der Vorlage, und manche ihrer Paare liegen unter der Schwelle: ein heller Ton hinter dem Text eines Kastens, eine Markenfarbe im Kolumnentitel. allow akzeptiert sie, ohne die Prüfung abzuschalten (seit postext 1.52). Ein Eintrag nennt die Textfarbe fg und den Grund bg (hexadezimal, wie die Konfiguration sie schreibt oder wie sie gemalt werden) oder einen style: die Id eines Kastenstils (calloutStyles oder der style eines Rahmens einer komponierten Seite), eines Absatz-, Überschriften-, Chip- oder Bildbeschriftungsstils. Jedes Feld, das ein Eintrag angibt, muss passen, also akzeptiert { style: 'note', fg: '#7a8a99' } dieses Grau nur in note-Kästen. Ein Eintrag ohne eines der drei Felder passt auf nichts.
contrast: {
allow: [
{ fg: '#b7820f', bg: '#ffffff', reason: 'Der Ocker des Verlags für die Kolumnentitel' },
{ style: 'randnotiz', reason: 'Die Vorlage setzt ihre Randnotizen in hellem Grau' },
],
}Ein akzeptiertes Paar wird weiter gemeldet: Jeder Befund, auf den es passt, trägt accepted (den reason des Eintrags mit seinem fg, bg und style), und die akzeptierten Befunde stehen hinter den anderen. Der Sandbox führt sie in den Prüfungen unter Akzeptierte Kontrastpaare mit dem Grund auf und zählt sie nicht mit; postext check gibt sie als Hinweise aus, an denen --strict nicht scheitert. Dieselben Farben außerhalb dessen, was der Eintrag nennt, bleiben eine Warnung.
#Schwellenwerte
Das Verhältnis, das ein Text erreichen muss, richtet sich wie in WCAG 2 nach Größe und Schriftstärke.
| Stufe | Text | Großer Text |
|---|---|---|
AA | 4,5:1 | 3:1 |
AAA | 7:1 | 4,5:1 |
Großer Text hat 18 pt und mehr oder 14 pt und mehr bei einer Schriftstärke ab 700. Die Größen sind die gedruckten, in Punkt. Ein hoch- oder tiefgestelltes Zeichen wird in der Größe des Texts beurteilt, zu dem es gehört.
#Bildschirm und Druck
Postext setzt dieselben Seiten für einen Bildschirm und für eine Druckmaschine, und eine Farbe wirkt auf beiden nicht gleich.
- Bildschirm ist das WCAG-2-Kontrastverhältnis der sRGB-Farben,
(L1 + 0.05) / (L2 + 0.05)über ihre relativen Luminanzen: das, was Canvas, HTML-Betrachter, ein EPUB und ein RGB-PDF zeigen. - Druck ist dieselbe Formel über die Luminanz, die jede Farbe auf Papier hat. Die Farbe wird über das Ausgabeprofil des Auftrags separiert (eine in CMYK angelegte behält ihre Werte), die Separation wird über das Profil zurückgelesen, und ihre Luminanz wird relativ zum unbedruckten Papier genommen, das das Weiß einer gedruckten Seite ist, so wie das Weiß des Displays das Weiß eines Bildschirms ist. Druckfarbe ist nie ein vollkommenes Schwarz: Volles Schwarz auf Weiß erreicht etwa 14:1 auf gestrichenem Papier (FOGRA39, FOGRA51), 8:1 auf ungestrichenem Papier (FOGRA47, FOGRA52) und 5:1 auf Zeitungspapier (IFRA26, SNAP), wo ein Bildschirm 21:1 liefert. Ein Grau, das am Bildschirm besteht, kann auf Papier durchfallen:
#767676auf Weiß hat am Bildschirm 4,54:1 und auf gestrichenem Papier etwa 3,3:1.
Das Druckverhältnis braucht die Transformation des Ausgabeprofils (options.transform, gebaut mit outputTransform). Ohne sie wird für den Druck nur der negative Text geprüft.
#Negativer Text
Heller Text, der aus einem bedruckten Untergrund ausgespart ist, läuft im Druck zu, wenn er klein ist oder seine Striche dünn sind: Die Farbe des Untergrunds breitet sich in die Buchstaben aus, und ein Untergrund aus mehreren Druckfarben hängt zudem davon ab, dass die Platten im Passer bleiben. Das Verhältnis zeigt das nicht, denn Weiß auf Dunkelblau liegt über 10:1. Die Druckprüfung meldet solchen Text eigens (reversedText), wenn er unter minSize liegt oder unter minFineSize, während er kursiv ist oder eine Schriftstärke von lightWeight oder weniger hat. Jeder Befund nennt, aus wie vielen der vier Druckfarben der Untergrund aufgebaut ist.
#Was geprüft wird
Die Prüfung liest die Zeilen jedes Blocks mit ihren Inline-Farben (fett, kursiv, Verweise, Chips), Listenzeichen, Initialen, Legenden, Anmerkungen und Tabellenzellen sowie den Text der Gestaltungsfelder: Kolumnentitel, Auftakte, Überschriftengestaltungen, Kastentitel. Der Untergrund ist die oberste Fläche unter dem Text: ein Gestaltungskasten, ein Kasten, ein Legendenbalken, eine Tabellenzelle, ein Chip, sonst die Seitenfarbe (page.backgroundColor oder das Papier, das die Palette eines Teils seinen Seiten gibt). Eine durchscheinende Farbe wird mit dem verrechnet, was unter ihr liegt. Text über einem Bild wird übersprungen, weil sein Untergrund nicht einfarbig ist, ebenso Comic-Lettering, Ruby-Lesungen und Formeln. Die Wörter der Beschriftungen einer Abbildung werden auf ihrer Unterlage gelesen, sonst innerhalb ihres Lichthofs; Beschriftungen direkt auf dem Bild werden übergangen wie jeder Text über einem Bild.
Auf einer zusammengesetzten Seite folgt die Prüfung der Reihenfolge, in der die Seite gemalt wird: die Rahmen nach Ebene, die decoration der Vorlage auf Ebene 0. Rahmentext steht auf dem eigenen Kasten des Rahmens, wenn dessen Stil einen malt, sonst auf dem Dekorationskasten darunter (ein Bild der Dekoration nimmt ihn aus der Prüfung, wie jedes Bild), sonst auf der Seitenfarbe. Weiße Schrift auf einem farbigen Etikett der Dekoration wird also an diesem Etikett gemessen. Ein gedrehter oder skalierter Rahmen wird erst auf das Blatt gebracht, dann wird sein Grund gelesen; der Text der Dekoration selbst wird ebenso geprüft. Seit postext 1.37.
#Die Prüfung ausführen
contrastDocument(doc, options) gibt die Befunde eines gesetzten Dokuments zurück, das niedrigste Verhältnis zuerst. Jeder hat den buchweiten pageIndex, das rect auf dem Blatt (Seitenpixel) und den Quellbereich seines ersten Vorkommens, die beiden Farben, wie sie gemalt sind (color, background), die kleinste sizePt, in der er gesetzt ist, mit weight und italic, eine role ('body', 'heading', 'caption', 'table', 'runningHead', 'design', 'chip', 'marker' oder 'label', die Wörter der Beschriftungen einer Abbildung), den text des ersten Abschnitts und die Anzahl count der so gesetzten Abschnitte. Ein Paar wird je Schwellenwert einmal gemeldet, wie viele Zeilen es auch verwenden.
lowContrastergänztlevel,large,required, das Verhältnis in jeder geprüften Wiedergabe (screen,print) undfailing, die Wiedergaben unterrequired.reversedTextergänztreasons('small','italic','light'),minimumPtundinks.
Die Optionen sind contrast (die aufgelösten Einstellungen, wenn es nicht die des Dokuments sind), media (die Wiedergaben, unabhängig von mode) und transform.
import { contrastDocument, outputTransform, parseIccProfile } from 'postext';
const transform = outputTransform(parseIccProfile(fogra51Bytes));
for (const issue of contrastDocument(doc, { transform })) {
if (issue.kind === 'lowContrast') {
console.log(`${issue.color} on ${issue.background}: ${issue.screen}:1, ${issue.level} asks for ${issue.required}:1`);
}
}contrastPairs(doc, options) gibt jedes Paar aus Text und Untergrund zurück, das das Dokument setzt, ob es besteht oder nicht, mit seinem Verhältnis screen, seinem Verhältnis print, wenn die Transformation übergeben wird, dem geforderten Verhältnis required und den Farben, wie die Konfiguration sie schreibt (textColor, groundColor): das, was ein Gestaltungswerkzeug neben einem Farbfeld anzeigt. Sie läuft unabhängig von enabled.
Die Maße werden für Ihre eigenen Werkzeuge exportiert:
contrastRatio(a, b)undrelativeLuminance(color)liefern das WCAG-2-Verhältnis und die Luminanz von sRGB-Farben.isLargeText(sizePt, weight)undcontrastThreshold(level, large)liefern den Schwellenwert einer Größe und Schriftstärke.blendColors(top, under)liefert eine durchscheinende Farbe über einer anderen als#rrggbb.printContrastRatio(a, b, context),printLuminance(color, context)undprintSeparation(color, context)liefern dasselbe auf Papier. Der Kontext enthält dietransformund alsauthoreddas Ergebnis vonauthoredCmykColors(config).contrastMedia(doc.config, contrast)liefert die Wiedergaben, zu denenmodefür ein Dokument aufgelöst wird.
Resolver und Stripper entsprechen den anderen Abschnitten: resolveContrastConfig und stripContrastDefaults, mit DEFAULT_CONTRAST_CONFIG, DEFAULT_CONTRAST_REVERSED_TEXT_CONFIG, CONTRAST_LEVELS und CONTRAST_MODES.
#Inhaltsprüfung (Konfiguration)
Die Eigenschaft checks fasst die Prüfungen zusammen, die die Konfiguration selbst lesen. Bisher ist es eine, contentInConfig: Sie warnt, wenn eine Gestaltung den Text des Buches enthält. Ein Kolumnentitel, die Gestaltung einer Überschrift, eine Teiltitelseite und die Zeile eines Teils im Inhaltsverzeichnis sind Form: Sie enthalten Platzhalter ({chapterTitle}, {titleText}, {number}) und höchstens ein oder zwei eigene Wörter, etwa Kapitel vor {chapterNumber}. Text, der zum Buch gehört, steht im Markdown, wo ihn das Inhaltsverzeichnis, die Suche, Übersetzungen, das getaggte PDF und das EPUB sehen. Der Satz liest die Prüfung nicht, eine Änderung verschiebt also keine Zeile.
interface ChecksConfig {
contentInConfig?: {
enabled?: boolean;
allow?: string[];
maxWords?: number;
maxChars?: number;
};
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
contentInConfig.enabled | boolean | true | Führt die Prüfung aus. |
contentInConfig.allow | string[] | [] | Wendungen, die eine Gestaltung in jeder Länge wiederholen darf: der Buchtitel, der Name des Verlags. Verglichen wird ohne Groß- und Kleinschreibung, Leerraum und die Satzzeichen um die Wörter; eine Wendung in einem längeren Text wird herausgenommen, bevor der Rest gezählt wird. |
contentInConfig.maxWords | number | 2 | So viele Wörter darf ein Gestaltungstext neben seinen Platzhaltern höchstens enthalten. |
contentInConfig.maxChars | number | 24 | So viele Buchstaben und Ziffern darf ein Gestaltungstext neben seinen Platzhaltern höchstens enthalten. Ein chinesisches, japanisches, koreanisches oder thailändisches Zeichen zählt dreifach, es gehen also etwa acht durch. |
#Wie ein Gestaltungstext ausgewertet wird
- Sein wörtlicher Text ist sein
contentohne jeden Platzhalter ({name},{attr.key},{firstMark.key}), die Maskierungen{{und}}als Klammern und\nals Zeilenumbruch gelesen. - Ein Text ohne Buchstaben oder Ziffern (eine Reihe Füllpunkte, ein Ornament, ein
·) ist nie Inhalt. - Ein Wort ist, was zwischen Leerzeichen steht und einen Buchstaben oder eine Ziffer enthält: Ein einzelnes
·oder|ist kein Wort, eine Adresse wiepostext.devist eines. - Zuerst werden die Wendungen aus
allowherausgenommen, ebensotitle,subtitle,authorundpublisheraus den Metadaten des Dokuments (seinem Frontmatter), die ein Kolumnentitel oft wiederholt. - Was übrig bleibt, ist Inhalt, wenn es mehr als
maxWordsWörter oder mehr alsmaxCharsBuchstaben und Ziffern hat.
Gelesen werden alle Gestaltungsfelder: header, footer, das advancedDesign.slot jeder Überschriftenebene, advancedDesign.slot, header und footer jedes Überschriftenstils, parts.design, parts.versoDesign, toc.parts.design und dasselbe in htmlViewer.overrides. configDesignSlots(config) zählt sie mit ihren Pfaden auf, designTextLiteral(content) gibt den wörtlichen Text einer Vorlage zurück.
#Die Warnung
collectConfigWarnings (und VDTDocument.configWarnings) gibt eine contentInConfig-Warnung je Einstellung mit Inhalt: ein Überschriftenstil (seine id in ownerId), eine Überschriftenebene, die Kopfzeile, die Gestaltung der Teile. path nennt die Einstellung, count die betroffenen Gestaltungstexte, chars ihre Buchstaben und Ziffern, elements den Pfad jedes Textes (die ersten 20) und value den Anfang des ersten (höchstens 40 Zeichen). Übergeben Sie die Metadaten des Dokuments als zweites Argument, um seinen Titel und Autor zu erlauben; ein Satzlauf tut das selbst.
import { collectConfigWarnings } from 'postext';
collectConfigWarnings(config, { metadata: { title: 'A Year of Weather' } });
// [{ kind: 'contentInConfig', path: 'headingStyles[3]', ownerId: 'lesson-4',
// value: 'Look at the picture and answer the questi…', used: '',
// count: 30, chars: 1017, elements: ['headingStyles[3].header.elements[2]', …] }]Abhilfe: Verschieben Sie den Text ins Markdown, als Überschrift, Kasten oder Absatz des Kapitels, zu dem er gehört, und lassen Sie in der Gestaltung nur Platzhalter. Ein Wert, der sich je Kapitel ändert, kann in der Überschriftenzeile stehen und mit {attr.key} gelesen werden: # Karten {kicker="Lektion 4"} und {attr.kicker} in der Gestaltung. Eine Wendung, die Form ist, etwa der Verlagsname in einem Kolumnentitel, gehört in allow.
Die Sandbox zeigt die Warnung im Bedienfeld Prüfungen und führt die Prüfung unter Gestaltung → Erweitert → Inhalt in der Konfiguration; postext check gibt sie aus.
#Folio-Betrachter (Konfiguration)
Die Eigenschaft folio legt fest, wie der Folio-Betrachter (postext-folio) das gedruckte Buch in 3D zeigt: den Blickwinkel, das Papier, die Bindung, die Unterlage, auf der das Buch liegt, und das Licht. Das Layout ignoriert sie, ebenso die Ausgaben Canvas, HTML und PDF. buildDocument übernimmt die aufgelösten Einstellungen in den VDT als doc.config.folio, wenn die Konfiguration welche setzt; ein Dokument ohne sie behält also seinen Layout-Hash.
interface FolioConfig {
tilt?: number; // Degrees from straight above, 0–70.
yaw?: number; // Degrees round the book, −180–180.
paper?: {
type?: 'uncoated' | 'bookWove' | 'coatedMatte' | 'coatedSilk' | 'coatedGloss'
| 'bible' | 'newsprint' | 'cardStock' | 'board';
grammage?: number; // g/m²
bulk?: number; // cm³/g; caliper µm = grammage × bulk
finish?: 'auto' | 'uncoated' | 'matte' | 'silk' | 'gloss';
texture?: 'auto' | 'smooth' | 'vellum' | 'wove' | 'laid' | 'linen' | 'felt';
textureStrength?: number; // 0–2
shade?: ColorValue;
showThrough?: boolean;
};
binding?: {
type?: 'hardcover' | 'paperback' | 'sewn' | 'layflat' | 'saddleStitch' | 'folded';
cover?: 'case' | 'pages';
coverMaterial?: 'auto' | 'cloth' | 'paper' | 'leather';
coverColor?: ColorValue;
spineImage?: string; // resource id
};
surface?: {
type?: 'oak' | 'walnut' | 'linen' | 'felt' | 'leather' | 'marble' | 'plain' | 'none';
color?: ColorValue;
};
lighting?: {
environment?: 'studio' | 'daylight' | 'lamp' | 'overcast' | 'night';
intensity?: number; // 0.25–2
shadows?: boolean;
};
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
tilt | number | 22 | Neigung des Blicks gegenüber der Senkrechten von oben, in Grad, begrenzt auf 0–70. Bei 0 sieht man das aufgeschlagene Buch flach von oben; ein größerer Winkel rückt den Fuß der Seiten näher und zeigt die Tiefe des Buchblocks. |
yaw | number | 0 | Wie weit der Blick um das Buch gedreht ist, in Grad, auf −180–180 gebracht. Bei 0 sieht man das Buch vom Fuß seiner Seiten her; ein positiver Winkel führt das Auge nach rechts herum, ein negativer nach links. Zusammen mit tilt ist es die Ansicht, mit der der Betrachter öffnet und zu der resetView() sanft zurückkehrt. |
paper.type | FolioPaperType | 'uncoated'; 'newsprint' bei einem Zeitungsformat | Die Papiersorte. Sie liefert die Standardwerte der fünf Felder darunter (siehe die Tabelle der Sorten). cardStock ist Umschlagkarton; board ist starre Pappe wie in einem Pappbilderbuch, und ihre Blätter wenden sich, ohne sich zu biegen. |
paper.grammage | number | der der Sorte | Flächengewicht in Gramm pro Quadratmeter, 20–2500. Schwereres Papier ist dicker, steifer und undurchsichtiger: Ein Blatt biegt sich in einem weiteren Bogen und zeigt weniger von der Rückseite. |
paper.bulk | number | der der Sorte | Dicke je Gewichtseinheit (Volumen) in cm³/g, 0,5–3. Die Dicke eines Blattes in Mikrometern ist Flächengewicht × Volumen, und die Dicke des Buchblocks ergibt sich daraus und aus der Seitenzahl. |
paper.finish | FolioPaperFinish | 'auto' | Ungestrichen (Faser, kein Glanz) oder gestrichen und satiniert zu matt, seidenmatt (ein sanfter Glanz) oder glänzend. Eine glänzende Seite spiegelt in Folio das Blatt, das sich über ihr wendet. 'auto' übernimmt den Wert der Sorte. |
paper.texture | FolioPaperTexture | 'auto' | Das Relief der Oberfläche: smooth (satiniert), vellum (eine feine Körnung), wove (die gleichmäßige Struktur der meisten Buchpapiere, auf einem gewebten Sieb gebildet), laid (dichte Rippen, gekreuzt von weiter auseinanderliegenden Stegen, vom Egoutteur hinterlassen), linen (eine geprägte Leinenstruktur), felt (unregelmäßige Filzmarkierungen). 'auto' übernimmt den Wert der Sorte. |
paper.textureStrength | number | 1 | Wie stark die Struktur im Licht hervortritt, 0–2. |
paper.shade | ColorValue | der der Sorte | Die Farbe des Papiers vor dem Druck (weiß, naturweiß, chamois). Die Seiten werden darauf gedruckt. |
paper.showThrough | boolean | true | Die Rückseite einer Seite scheint durch dünnes Papier schwach durch. Nach Dünndruckpapier zeigt Zeitungspapier sie am stärksten: Seine Druckfarbe zieht ins Blatt ein. |
binding.type | FolioBindingType | 'hardcover'; 'folded' bei einem Zeitungsformat | hardcover: Hardcover mit Buchdecke, die Deckel etwas größer als die Seiten. paperback: Klebebindung (gefräst und geleimt), öffnet sich weniger flach. sewn: ein Softcover mit fadengehefteten Lagen. layflat: öffnet sich flach, ohne Senke am Bund. saddleStitch: gefalzte Bogen, durch den Falz geheftet, wie bei einer Zeitschrift oder Broschüre; kein flacher Rücken. folded (seit postext 1.18): eine Zeitung, einmal gefalzte Bogen, ineinandergelegt, ohne dass etwas sie hält; keine Heftklammern, kein Rücken und kein Deckel, und die erste Seite ist die Titelseite. Ein Abschnitt :::paper mit einem shade druckt einen Zeitungsteil, etwa den Wirtschaftsteil, auf lachsfarbenem Zeitungspapier. |
binding.cover | FolioCoverSource | 'case' | Die Umschläge. 'case' zeichnet eine Buchdecke um die Seiten. 'pages' nimmt die erste Seite des Buches als Vorderdeckel und seine letzte Seite, wenn sie eine linke Seite ist, als Rückdeckel: Das Buch liegt geschlossen, bis der Umschlag umgeschlagen wird, die Deckel wenden sich steif (bei einer Rückstichheftung ist der Umschlag ein Bogen, etwas schwerer als die Seiten, und wendet sich wie sie), und es wird keine Buchdecke gezeichnet. |
binding.coverMaterial | FolioCoverMaterial | 'auto' | 'auto' ist Leinen bei einem Hardcover und Karton ('paper') bei den anderen Bindungen. |
binding.coverColor | ColorValue | Dunkelblau (#2c3e57) | Die Farbe des Bezugsmaterials. |
binding.spineImage | string | keiner | Die ID einer Bitmap- oder SVG-Ressource, die auf den Rücken gedruckt wird: der Rücken, wie man ihn beim stehenden Buch sieht, Kopf oben und der Vorderdeckel rechts. Sie wird zentriert so eingepasst, dass sie den Rücken bedeckt. Bei Rückstichheftung und bei gefalzter Bindung ohne Wirkung. |
surface.type | FolioSurfaceType | 'oak' | Worauf das Buch liegt. 'none' lässt den Hintergrund des Hosts stehen. |
surface.color | ColorValue | keiner | Tönt die Unterlage; bei 'plain' ist es die Farbe der Unterlage. |
lighting.environment | FolioEnvironment | 'studio' | Die Umgebung, die gestrichenes und glänzendes Papier spiegeln, zusammen mit dem Hauptlicht, das die Schatten wirft. |
lighting.intensity | number | 1 | Belichtung, 0,25–2. |
lighting.shadows | boolean | true | Vom Hauptlicht geworfene Schatten. |
Die Sorten und die Werte, die sie liefern (FOLIO_PAPER_STOCKS), typisch für die Datenblätter der Papierfabriken:
| Sorte | Flächengewicht | Volumen | Dicke | Oberfläche | Struktur | Papierton |
|---|---|---|---|---|---|---|
uncoated (holzfreies Offsetpapier) | 90 g/m² | 1,25 | 113 µm | ungestrichen | Velin | #fcfbf8 |
bookWove (chamois, hohes Volumen) | 80 g/m² | 1,6 | 128 µm | ungestrichen | Velin | #f6efdc |
coatedMatte | 115 g/m² | 1,0 | 115 µm | matt | glatt | #fdfdfc |
coatedSilk | 115 g/m² | 0,9 | 104 µm | seidenmatt | glatt | #ffffff |
coatedGloss | 115 g/m² | 0,8 | 92 µm | glänzend | glatt | #ffffff |
bible | 40 g/m² | 1,1 | 44 µm | ungestrichen | Vellum | #f9f6ee |
newsprint | 48 g/m² | 1,5 | 72 µm | ungestrichen | Velin | #ebe7dc |
cardStock | 250 g/m² | 1,2 | 300 µm | ungestrichen | Vellum | #fbfaf6 |
board | 1250 g/m² | 1,6 | 2000 µm | seidenmatt | glatt | #ffffff |
Ein Roman auf chamoisfarbenem Werkdruckpapier, als Paperback gebunden, auf einem Nussbaumschreibtisch unter einer Leselampe:
folio: {
paper: { type: 'bookWove' },
binding: { type: 'paperback', coverColor: { hex: '#8a2b1f', model: 'hex' } },
surface: { type: 'walnut' },
lighting: { environment: 'lamp' },
}Eine Seite in einem Zeitungsformat (page.sizePreset 'broadsheet', 'berliner', 'tabloid' oder 'compact') wird als Zeitung gezeigt, wenn die Konfiguration weder Sorte noch Bindung angibt: Papier newsprint und Bindung folded (seit postext 1.18). Eine Sorte oder Bindung, die die Konfiguration angibt, bleibt erhalten; paper: { type: 'uncoated' } druckt ein Tabloid also auf Offsetpapier. Papierfelder, die ohne Sorte gesetzt sind (ein grammage, ein shade), gelten für das Zeitungspapier. Resolver und Stripper nehmen das Format als zweites Argument, und folioForTrim(folio, sizePreset) schreibt die beiden Standardwerte in die Konfiguration:
resolveFolioConfig({ tilt: 30 }, 'tabloid');
// => { tilt: 30, paper: { type: 'newsprint', grammage: 48, bulk: 1.5, … }, binding: { type: 'folded', coverMaterial: 'paper', … }, … }
stripFolioDefaults({ paper: { type: 'newsprint' }, binding: { type: 'folded' } }, 'tabloid');
// => undefinedDie Farben folgen Palettenverknüpfungen wie jede andere Farbe der Konfiguration (paletteId). Resolver und Stripper entsprechen den anderen Abschnitten; der Stripper entfernt Papierwerte, die denen der gewählten Sorte gleichen:
import { FOLIO_PAPER_STOCKS, DEFAULT_FOLIO_CONFIG, resolveFolioConfig, stripFolioDefaults } from 'postext';
resolveFolioConfig({ paper: { type: 'bible' } }).paper;
// => { type: 'bible', grammage: 40, bulk: 1.1, finish: 'uncoated', texture: 'vellum', textureStrength: 1, shade: { hex: '#f9f6ee', … }, showThrough: true }
stripFolioDefaults({ paper: { type: 'bible', grammage: 40 } });
// => { paper: { type: 'bible' } }In der Sandbox bilden diese Einstellungen die Gruppe Folio des Bedienfelds Gestaltung (Gestaltung → Folio → Folio-Betrachter (3D)), und der Tab Folio zeigt Änderungen sofort, ohne das Buch neu zu setzen. Zum Betrachter selbst siehe Ein 3D-Buch, und zu einer Seitenfolge auf einer anderen Papiersorte Dokumentformat › :::paper.
#Debug
Die Eigenschaft debug fasst zwei Arten von Hilfen beim Schreiben zusammen: visuelle Überlagerungen, die den Quelltext und das gesetzte Layout synchron halten, und eine Reihe von Warnungen, die typografische oder strukturelle Probleme im Bedienfeld Prüfungen der Sandbox anzeigen. Keine von beiden wirkt sich auf die exportierte Ausgabe aus.
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
cursorSync | SyncIndicatorConfig | In das gesetzte Layout gespiegelte Einfügemarke – siehe Visuelle Überlagerungen. |
selectionSync | SyncIndicatorConfig | Auf der Seite hervorgehobene Auswahl im Quelltext – siehe Visuelle Überlagerungen. |
looseLineHighlight | LooseLineHighlightConfig | Überlagerung auf zu lockeren Zeilen im Blocksatz – siehe Visuelle Überlagerungen. |
pageNegative | { enabled: boolean } | Kontrastreiches Negativ der Seite – siehe Visuelle Überlagerungen. |
warnings | WarningsToggleConfig | Ein boolescher Wert je Art von Warnung, die der Editor beim Schreiben anzeigt – siehe Warnungen. |
#Visuelle Überlagerungen
| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
cursorSync.enabled | boolean | true | Zeigt im gesetzten Layout eine Einfügemarke, die die Cursorposition im Quelltext spiegelt. |
cursorSync.color | ColorValue | #2563eb | Farbe dieser Einfügemarke. |
selectionSync.enabled | boolean | true | Hebt den gesetzten Bereich hervor, der der Auswahl im Quelltext entspricht. |
selectionSync.color | ColorValue | #fde04780 | Farbe der Hervorhebung – standardmäßig ein durchscheinendes Gelb. |
looseLineHighlight. | boolean | false | Legt eine Überlagerung auf Zeilen im Blocksatz, deren Wortabstand das threshold-Fache der normalen Wortzwischenraumbreite übersteigt. |
looseLineHighlight.color | ColorValue | #ff000040 | Farbe dieser Überlagerung. |
looseLineHighlight. | number | 3 | Vielfaches der normalen Wortzwischenraumbreite, ab dem eine Zeile im Blocksatz als zu locker gilt. Die Warnung looseLines verwendet denselben Schwellenwert. Eine Zeile im Blocksatz, deren Zwischenräume über das Dreifache hinaus gedehnt würden, wird im Flattersatz gesetzt; beim Standardwert finden Überlagerung und Warnung im laufenden Text daher fast nichts. Senken Sie den Wert (1,5 oder 2), um Zeilen zu sehen, die locker, aber noch im Blocksatz sind. |
pageNegative.enabled | boolean | false | Legt ein kontrastreiches Negativ über die Seite – nützlich, um die Gesamtform einer Doppelseite (Textdichte, Spaltenausgleich, Weißraum) auf einen Blick zu prüfen, ohne von den Einzelheiten der Glyphen abgelenkt zu werden. |
fitMarks | 'all' | 'problems' | 'none' | 'problems' | Welche Passmarken die Leinwand der Sandbox über zusammengesetzte Seiten legt, solange der Leser in der Werkzeugleiste nichts gewählt hat: alle, nur Rahmen, die nicht passen, und unbekannte Aussehen, oder keine. Die Wahl des Lesers geht vor. Seit postext 1.52. |
fitMarksMinScale | number | 1 | Ein Rahmen, der in diesem Maßstab oder größer gesetzt ist, bekommt keine Skalierungsplakette (mit 0.95 nur Rahmen unter 95 %). Text und Bilder werden getrennt beurteilt. |
Jede SyncIndicatorConfig ist { enabled: boolean; color?: ColorValue }. LooseLineHighlightConfig ist { enabled: boolean; color?: ColorValue; threshold?: number }. pageNegative ist ein minimaler Schalter { enabled: boolean }.
debug: {
cursorSync: { enabled: true, color: { hex: '#ff0066', model: 'hex' } },
selectionSync: { enabled: false, color: { hex: '#fde04780', model: 'hex' } },
looseLineHighlight: { enabled: true, color: { hex: '#ff000040', model: 'hex' }, threshold: 3 },
pageNegative: { enabled: true },
}Diese Überlagerungen zeichnet die Sandbox über ihre Canvas-Vorschau. Sie gehören nicht zur Seite: renderPage, die HTML-Ausgabe und das PDF malen sie nie.
#Zu lockere Zeilen im eigenen Canvas
Die Engine exportiert die Hervorhebung zu lockerer Zeilen als zwei Hilfsfunktionen für eine Seite, die Sie selbst malen:
import { buildDocument, renderPageToCanvas, drawLooseLines, findLooseLines } from 'postext';
const doc = buildDocument(content, config);
const canvas = document.querySelector('canvas')!;
renderPageToCanvas(doc.pages[0], doc, canvas, { scale: 0.5 });
drawLooseLines(canvas.getContext('2d')!, doc.pages[0], doc, { threshold: 2.5 });
// The same lines as data: a report, an SVG overlay, a count per page.
for (const { ratio, line, block } of findLooseLines(doc, { threshold: 2.5 })) {
console.log(`page ${block.pageIndex + 1}: ${ratio.toFixed(2)}× — ${line.text}`);
}findLooseLines(doc, { threshold?, pageIndex? })gibt in Lesereihenfolge jede Zeile im Blocksatz zurück, deren Wortabstandthresholdübersteigt:{ block, line, ratio, x, y, width, height }.ratioistlineWordSpacing(line): der Abstand so, wieminWordSpacingundmaxWordSpacingihn begrenzen (justifiedSpaceLimitRatio, wenn die Zeile Zwischenräume eines anderen Schnitts enthält, sonstjustifiedSpaceRatio); eine Zeile, die an der Grenze gesetzt ist und einen fetten Zwischenraum enthält, wird bei einem Schwellenwert gleichmaxWordSpacingalso nicht gemeldet. Das Rechteck in Seitenpixeln ist der Streifen, den die Hervorhebung abdeckt: die volle Breite des Blocks über die Zeile hinweg. Es sind die Zeilen, die die Sandbox hervorhebt und in ihrem Bedienfeld Prüfungen alslooseLinemeldet.drawLooseLines(ctx, page, doc, { threshold?, color? })füllt diese Streifen für eine Seite und gibt die gemalten Zeilen zurück. Sie zeichnet in Seitenpixeln unter der aktuellen Transformation des Kontexts; rufen Sie sie also direkt nachrenderPageoderrenderPageToCanvasauf demselben Canvas auf: Beide hinterlassen den Kontext auf die Seite skaliert.colorist ein beliebiger Füllstil des Canvas.- Standardwerte. Beide Hilfsfunktionen verwenden den Standardschwellenwert (3) und die Standardfarbe (
#ff000040), nichtdebug.looseLineHighlightdes Dokuments: Diese Einstellung gehört der Sandbox. Um einer Konfiguration zu folgen, übergeben SieresolveDebugConfig(config.debug).looseLineHighlight.thresholdund.color.hex.
#Warnungen
debug.warnings legt fest, welche Probleme beim Schreiben im Bedienfeld Prüfungen der Sandbox erscheinen (bearbeitet unter Gestaltung → Erweitert → Warnungen). Jeder Schlüssel ist ein unabhängiger boolescher Schalter; setzen Sie einen auf false, um genau diese Warnung stummzuschalten, ohne die anderen abzuschalten.
Diese Schalter filtern nur das Bedienfeld der Sandbox. Die Warnungen, die die Engine selbst festhält – Kästen, die ihre Spalte überlaufen, in doc.warnings; unbekannte Ressourcen-IDs, Direktiven, Einbettungen und Formatkennungen sowie unregelmäßige Tabellenraster in doc.contentWarnings –, sind unabhängig von den Schaltern vorhanden, und die Renderer melden Bilder, die sie als Platzhalter malen; siehe Warnungen im Dokument.
interface WarningsToggleConfig {
missingFont?: boolean;
looseLines?: boolean;
headingHierarchy?: boolean;
consecutiveHeadings?: boolean;
listAfterHeading?: boolean;
designIssues?: boolean;
}| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
missingFont | boolean | true | Meldet, wenn eine von der Konfiguration angeforderte Schrift im Browser nicht geladen werden konnte. Fängt Tippfehler in fontFamily und fehlende Pakete @fontsource/... früh ab, bevor sie in der gesetzten Ausgabe als stille Ersetzung durch eine Ersatzschrift auftauchen. |
looseLines | boolean | true | Meldet Zeilen im Blocksatz, deren Wortabstand debug. übersteigt. Ergänzt die Überlagerung: Die Warnung zählt sie im Bedienfeld auf, die Überlagerung zeigt sie an Ort und Stelle. |
headingHierarchy | boolean | true | Meldet Überschriftenebenen, die eine Stufe überspringen – z. B. eine H1, auf die direkt eine H3 folgt. Solche Lücken in der Gliederung deuten meist auf einen Tippfehler in der Überschriftentiefe oder auf ein Missverständnis der Gliederung des Dokuments hin. |
consecutiveHeadings | boolean | false | Meldet, wenn auf eine Überschrift unmittelbar eine weitere folgt, ohne Absatz oder Liste dazwischen. Standardmäßig aus, weil gestapelte Überschriften in vielen Vorlagen berechtigt sind (Titel + Untertitel, Kapitel + Motto); schalten Sie sie für Manuskripte ein, in denen jede Überschrift Fließtext einleiten soll. |
listAfterHeading | boolean | false | Meldet, wenn eine Liste unmittelbar nach einer Überschrift beginnt, ohne einleitenden Absatz. Standardmäßig aus, weil Nachschlagewerke das ständig tun; schalten Sie sie für erzählende Texte ein, in denen jede Liste von Fließtext eingerahmt sein soll. |
designIssues | boolean | true | Meldet Integritätsprobleme in Gestaltungsfeldern – Kopfzeilen, Fußzeilen, der Teilauftakt und die leere linke Seite danach, die Zeilen der Teile im Inhaltsverzeichnis, die Felder für erweiterte Überschriftengestaltung sowie Gestaltung und Abschnitts-Kolumnentitel jedes Überschriftenstils. Erfasst zyklische Ankerketten und ins Leere zeigende Ankerverweise (ein Element, das an einer #id verankert ist, die es nicht mehr gibt), eine Überschrift über die ganze Seitenbreite, deren breakBefore abgeschaltet ist, und eine eingeschaltete erweiterte Gestaltung, deren Elemente nie {titleText} ausgeben. |
debug: {
warnings: {
missingFont: true,
looseLines: true,
headingHierarchy: true,
consecutiveHeadings: true,
listAfterHeading: false,
designIssues: true,
},
}Daneben listet das Bedienfeld immer die Warnungen auf, die das Layout selbst auslöst (VDTDocument.warnings), etwa einen Kasten, der seine Spalte überläuft (calloutOverflow), und die Konfigurationswerte, die die Engine ersetzt hat (VDTDocument.configWarnings oder collectConfigWarnings(config); siehe Konfigurationswarnungen unten).
#Konfigurationswarnungen
Diese Fehler in der Konfiguration selbst bleiben nie stumm, und kein Schalter blendet sie aus, außer dem im letzten Punkt. Die Engine scheitert an keinem davon; sie setzt einen Wert ein oder lässt die Einstellung weg und meldet das:
- Unbekanntes Zahlenformat – ein
numberFormateiner geordneten Liste, einpage.pageNumbering.formatoder eincounterFormateines Ressourcentyps, das keiner der Schreibweisen der Nummernformate entspricht. Es wird dezimal nummeriert. - Schriftliste in einer Schriftfamilie – ein
fontFamily(oder ein beliebiges…FontFamily), das eine CSS-Schriftliste enthält. Der Text wird in der ersten Familie der Liste gesetzt (siehe Eine Familie profontFamily). - Seitenspalte ohne Platz – ein
sideColumnPercenteines Layouts'oneAndHalf'(des Dokuments oder im eigenenlayouteines Überschriftenstils), das einer der Spalten weniger als 1 % der Satzspiegelbreite ließe oder keine Zahl ist. Die Spalten werden beim nächstgelegenen Wert geteilt, den beide annehmen können, undusednennt ihn (sideColumnPercentClamped; siehe das Layout'oneAndHalf'). - Spaltenzahl außerhalb des Bereichs – ein
columnCounteines Layouts'multiple'(des Dokuments oder im eigenenlayouteines Überschriftenstils), das keine ganze Zahl von 3 bis 8 ist. Die Seite wird in die nächstgelegene gültige Anzahl geteilt (3 für einen Wert, der keine Zahl ist), undusednennt sie (columnCountClamped; siehe das Layout'multiple'). - Zeichenraster zu groß – ein
cjk.gridmit mehr Zeichen pro Zeile oder Zeilen pro Seite, als die Ränder Platz lassen. Das Raster wird mit dem Höchstwert gesetzt, der passt, undusednennt die Zahl (cjkGridClamped; siehe Zeichenraster). - Unbekannte Überschrifteneinstellung – ein Schlüssel, den
headings,headings.balancing, eine Überschriftenebene, ein Überschriftenstil oder ein Absatzformat nicht kennt: ein falsch geschriebenesletterSpacng, ein aus einem anderen Werkzeug entlehntestracking, einlevelin einem Überschriftenstil, einfontStyle: 'italic'in einem Absatzformat (dasitalic: trueerwartet). Ein Tabulator wird genauso geprüft (einleadersstattleader), ebenso eine Initiale,lineNumbers,canvasViewer,checks,codeStyleund die Comic-Einstellungen. Die Engine ignoriert ihn (bis postext 1.4 tat sie das wortlos).valueist der Schlüssel,usedist leer, undsuggestionnennt die Einstellung, der er am nächsten kommt, wenn eine nur ein oder zwei Buchstaben entfernt ist oder sich nur in Groß- und Kleinschreibung unterscheidet (unknownConfigKey). - Unbekannter Einstellungswert – eine Einstellung, die eines von wenigen Wörtern annimmt, aber ein anderes enthält, etwa
direction: 'right'(sie nimmtauto,ltroderrtl). Die Engine liest stattdessen den Standardwert, undusednennt, was daraus wurde: beidirectiondie Schreibrichtung der Dokumentsprache (unknownConfigValue). Einaligneines Tabulators, das keines seiner vier Wörter ist, wird als'start'gelesen, und eineposition, die weder Länge noch'end'noch Prozentwert ist, lässt den Tabulator weg (usedist'none'). Auch die Wörter der Comic-Einstellungen werden geprüft (Comics › Comic-Warnungen):usedist der Wert, zu dem die Einstellung aufgelöst wurde (bei einem eingebauten Stil der eigene Standardwert des Sprechblasenstils), undsuggestionnennt das Wort, dem der Wert am nächsten kommt, wenn eines nahe liegt.levelundmodeder Kontrastprüfung werden genauso geprüft:usedist'AA'oder'auto'.canvasViewer.pageGapundcanvasViewer.rowGapwerden ebenso geprüft:usedist die ganze Zahl von 0 bis 200, als die der Wert gelesen wurde (seit postext 1.43). Ebensoprint.standard,print.outputProfileundprint.renderingIntent(usedist, was der Standard ergab), und einmaxWordsodermaxCharsvonchecks.contentInConfig, das keine ganze Zahl ab 0 ist. - Zeilennummern im vertikalen Text –
lineNumbers.enabled: truein einem vertikal gesetzten Dokument (layout.writingMode: 'vertical-rl'). Vertikale Seiten erhalten keine Zeilennummern, undusedistfalse(lineNumbersUnsupported; siehe Zeilennummern). - Textumfluss in vertikalem Text – ein
defaultPlacement.wrapeines Ressourcentyps in einem vertikal gesetzten Dokument. Vertikale Seiten setzen keinen Text neben eine Abbildung, undusedistnone(wrapUnsupported; siehe Dokumentformat › Textumfluss). Einwrap, das keine Seite angibt, ist ein unbekannter Einstellungswert. - Kastenstil auf Basis eines anderen – ein Kastenstil, dessen
extendsauf keinen Stil auscalloutStylesverweist (calloutStyleExtendsUnknown, mit der nächstliegenden ID alssuggestion), oder dessenextends-Kette zu ihm zurückkehrt (calloutStyleExtendsCycle,valueder Kreisa → b → a). Der Stil steht für sich, mit den eingebauten Werten für alles, was er offenlässt (siehe Stile, die auf einem anderen basieren). - Seitenvorlagen und Beschriftungsstile – ein Problem in
pageTemplatesoderlabelStyles: eine doppelte ID oder ein doppelter Name,extends, Anker oder verkettete Rahmen im Kreis, ein Stil, Rahmen oder eine Vorlage, die es nicht gibt, ein Minimum über seinem Maximum, ein Beschriftungsstil eines Ankers, denlabelStylesnicht hat (geprüft, wenn die Ressourcen übergeben werden:collectConfigWarnings(config, { resources })). Ihrpathist ein JSON-Pointer (/pageTemplates/3/frames/2/style); jede Art steht mit Ursache und Abhilfe unter Warnungen zu Seitenvorlagen. - Inhalt in einer Gestaltung – ein Gestaltungstext, dessen Text neben den Platzhaltern länger ist als eine kurze Beschriftung: der Text des Buches in der Konfiguration. Eine Warnung je Einstellung (ein Überschriftenstil, die Kopfzeile, die Gestaltung der Teile) mit dem Pfad jedes Textes (
contentInConfig; siehe Inhaltsprüfung). Anders als die übrigen lässt sie sich abschalten:checks.contentInConfig.enabled: false.
Die Sandbox listet sie im Bedienfeld Prüfungen mit dem Pfad der Einstellung auf. Im Code legt buildDocument sie als configWarnings am Dokument ab (das fehlt, wenn die Konfiguration fehlerfrei ist), und collectConfigWarnings(config) gibt sie zurück, ohne etwas zu setzen:
import { buildDocument, collectConfigWarnings } from 'postext';
// Plain JavaScript: in TypeScript, 'roman' does not type-check to begin with.
const config = { bodyText: { fontFamily: 'EB Garamond, serif' }, orderedLists: { numberFormat: 'roman' } };
const doc = buildDocument({ markdown }, config);
doc.configWarnings;
// [{ kind: 'fontFamilyStack', path: 'bodyText.fontFamily', value: 'EB Garamond, serif', used: 'EB Garamond' },
// { kind: 'unknownNumberFormat', path: 'orderedLists.numberFormat', value: 'roman', used: 'arabic' }]
collectConfigWarnings(config); // the same listAuch jede verschachtelte Teilkonfiguration wird geprüft: Überschriftenstile, die Listen innerhalb von Teilen, htmlViewer.overrides, Gestaltungselemente.
formatWarning (siehe Warnungen im Dokument) beschreibt sie ebenfalls, mit dem Pfad der Einstellung voran – bodyText.fontFamily: font stack "EB Garamond, serif" — set in "EB Garamond", headingStyles[0].letterSpacng: unknown setting "letterSpacng" — ignored (did you mean "letterSpacing"?) –, sodass ein Host alle drei Listen, die ein Build zurückgibt, in einer einzigen Schleife protokollieren kann.