Saltar al contingut principal

Capítol 3.16 · Part II · L'ofici

Configuració: fonts, colors i sortida

Com s’escriuen les unitats i els colors, la paleta, les fonts personalitzades, el visor HTML, el PDF i la producció per a impremta, el visor Folio i les ajudes de depuració

Actualitzat 2026-11-1042 minAl capítol 3 Configuracióenescadefritptzhjaar

En poques paraules

Aquesta pàgina reuneix els paràmetres que comparteix tot el llibre i els de cada tipus de sortida. Explica com s'escriu una mida i un color, i com es dona nom als colors d'una paleta. Ensenya a afegir les teves pròpies fonts. Després tracta la vista web, el fitxer PDF, els fitxers que demana una impremta i el llibre en 3D. L'última secció explica com s'activen les guies i els avisos que t'ajuden mentre treballes.

#Unitats i colors

#Dimensions

Totes les mesures físiques de Postext fan servir el tipus Dimension, un valor acompanyat d'una unitat:

interface Dimension {
  value: number;
  unit: DimensionUnit; // 'cm' | 'mm' | 'in' | 'pt' | 'px' | 'em' | 'rem'
}

Unitats absolutes (cm, mm, in, pt, px): es converteixen en píxels segons els dpi configurats. A 300 DPI, 1 cm equival aproximadament a 118 px.

Unitats relatives (em, rem): es calculen a partir de la mida de font actual. Un em és relatiu a la mida de font del mateix element; rem és relatiu a la mida de font del text de cos.

#Colors

Els colors es desen amb una representació hexadecimal i amb el model de color de destinació:

interface ColorValue {
  hex: string;         // '#ff0000', 'transparent', etc.
  model: ColorModel;   // 'hex' | 'rgb' | 'cmyk' | 'hsl' | 'spot'
  cmyk?: CmykPercent;  // Els valors de quatricromia exactes d'un color definit en CMYK.
  spot?: SpotColor;    // La tinta d'un color de tinta plana.
  overprint?: boolean; // Sobreimprimeix en una sortida d'impremta (consulta Colors que sobreimprimeixen).
  paletteId?: string;  // L'entrada de colorPalette que segueix.
  tint?: number;       // La intensitat de l'entrada sobre el color de la pàgina, en percentatge (amb paletteId).
}

El camp model indica l'espai de color previst. Per a la renderització web, 'hex' o 'rgb' són els habituals. Per a fluxos de treball d'impressió, 'cmyk' indica que el color es va especificar en CMYK, i cmyk en guarda els valors: una sortida d'impremta en CMYK els aplica tal com són, i hex n'és la representació en pantalla (vegeu Colors definits en CMYK). 'spot' és una tinta plana, amb la seva tinta a spot (vegeu Tintes planes).

Com que Postext busca una sortida de qualitat editorial, el color per defecte del text de cos és model: 'cmyk' (#000000). Els colors d'encapçalaments, negretes, cursives i llistes prenen per defecte el Color principal enllaçat a la paleta (#295AA3, model: 'hex'). El fons de pàgina i els indicadors d'interfície (retícula de base, marques de tall, indicadors de depuració) fan servir model: 'hex' per defecte. Si necessites un altre comportament en exportar, canvia color.model en qualsevol camp.

#Transparència

Un color pot ser translúcid. hex admet un canal alfa, com #rgba o #rrggbbaa. També admet un color rgb() / rgba(), amb la sintaxi de comes o la d'espais, i l'alfa com a nombre o com a percentatge. transparent és del tot transparent:

const config: PostextConfig = {
  header: {
    elements: [{
      kind: 'box',
      id: 'velo',
      placement: {
        anchor: { to: 'bleed', edge: 'top-left' },
        size: { width: 'fill', height: { value: 40, unit: 'mm' } },
      },
      style: { backgroundColor: { hex: '#ffffffb3', model: 'hex' } }, // blanc al 70 %
    }],
  },
  bodyText: { color: { hex: 'rgba(0, 0, 0, 0.85)', model: 'rgb' } },
};

Els tres backends el pinten igual. El canvas i el visor HTML prenen el valor com un color CSS. El generador de PDF fixa l'opacitat del color com un alfa constant, un ExtGState amb ca per als emplenaments i CA per als traços. Això abasta el text, els filets, les caixes, els emplenaments i vores de les taules, els xips, les mostres de color i les fórmules. Un color translúcid es compon sobre el que s'ha pintat abans. Una caixa de la capçalera o del peu es pinta l'última, així que vela el text que té a sota; una caixa d'una banda d'obertura es pinta la primera, així que tenyeix la pàgina sota el text. Quan el PDF es força a un altre espai de color (pdfGeneration.forceColorSpace amb colorSpace: 'cmyk' o 'grayscale'), el color es converteix i conserva l'alfa. Al Sandbox, el lliscador d'opacitat del selector de color escriu aquests valors com a #rrggbbaa, i el selector també llegeix les altres formes.

#Fonts personalitzades

Postext busca cada fontFamily en tots dos llocs: el catàleg de Google Fonts i la llista customFonts del document. Si un nom coincideix, tenen prioritat les fonts personalitzades: si declares customFonts: [{ name: 'Roboto', … }], Postext farà servir el teu fitxer en lloc de la «Roboto» de Google Fonts. El Sandbox pren de Fontsource les famílies que Google Fonts no té. No consulta mai Fontsource per un nom genèric (serif, system-ui) ni per una font que porta un sistema operatiu (Arial, Segoe UI, PingFang SC…): aquesta família es compon amb el que tingui l'equip del lector, el tauler Fonts la mostra com a No trobada i el PDF i les imatges SVG no en tenen cap fitxer per incrustar. Si el llibre s'hi compon, puja-la com a font personalitzada.

Fes servir fonts personalitzades quan:

  • El document necessita un tipus de lletra de marca o amb llicència que no és a Google Fonts.
  • L'entorn no té accés a les CDN de fonts, a jsDelivr (d'on el Sandbox pren els fitxers de Fontsource) ni a Google Fonts (sense connexió, en una intranet, per motius de privadesa).
  • Has de mantenir privat el fitxer de font i no el pots pujar a cap servei extern.

#Esquema de configuració

type CustomFontFormat = 'woff2' | 'woff' | 'ttf' | 'otf';
type CustomFontStyle = 'normal' | 'italic';
 
interface CustomFontVariant {
  weight: number;           // CSS font-weight, 100..900
  style: CustomFontStyle;
  fileId: string;           // id opac del binari en un emmagatzematge extern
  format: CustomFontFormat;
  fileName?: string;        // nom original del fitxer (es mostra a la UI)
}
 
interface CustomFontFamily {
  name: string;             // s'usa on encaixaria un nom de Google Font
  variants: CustomFontVariant[];
  redistributable?: boolean; // false: s'usa aquí, mai es copia fora del llibre
  fallback?: string;        // família oberta d'amplada semblant per a les cares sense fitxer (des de postext 1.42)
}
 
interface PostextConfig {
  // ...
  customFonts?: CustomFontFamily[];
}

El fitxer de cada variant no s'incrusta a la configuració. La configuració només desa referències fileId; els bytes es desen a part. Al Sandbox, això vol dir IndexedDB (un magatzem de claus i valors del navegador, privat del document). Un integrador que incrusti Postext en un altre entorn pot resoldre fileId com vulgui (un servei del servidor, la memòria cau d'un service worker, el que sigui), sempre que els bytes arribin al fil principal abans de buildDocument.

#Gestionar fonts personalitzades al Sandbox

Obre el tauler Fonts des de la barra d'activitats de l'esquerra (entre Recursos i Disseny). La llista Tipus de lletra d'aquest llibre mostra cada família que fa servir el disseny, amb la funció que té i d'on ve: Google Fonts, Fontsource (si Google Fonts no té la família), un fitxer propi, o d'enlloc (No trobada). A Els teus fitxers de font, per a cada família:

  1. Afegir una família de fonts: crea una família buida; li pots canviar el nom allà mateix.
  2. Pujar fitxer: tria un pes (100–900) i un estil (normal / cursiva), i selecciona un o diversos fitxers .woff2, .woff, .ttf o .otf. Cada fitxer es converteix en una variant pròpia associada a la combinació de pes i estil seleccionada; el nom del fitxer es desa i es mostra a la fila per distingir les variants. En qualsevol moment pots canviar el pes o l'estil d'una variant amb els desplegables.
  3. Es permeten variants duplicades. Si dos fitxers tenen la mateixa combinació de pes i estil, es desen tots dos i apareix un avís Variant de font duplicada perquè corregeixis els que sobren.
  4. Suprimir la variant o Suprimir la família: elimina l'entrada de la configuració i els bytes desats a IndexedDB.

Un cop declarada la família, tots els selectors de font la mostren al grup Personalitzades, per damunt de la llista de Google Fonts. Quan la tries, s'aplica a tots els camps fontFamily on la seleccionis.

#Una família de substitució per a una de llicenciada

Un llibre es pot compondre amb un tipus de lletra que el propietari no pot redistribuir. Marca la família amb redistributable: false, i el fitxer .postext en deixarà fora els fitxers. Si indiques a fallback una família oberta d'amplada semblant, el fitxer que s'obre sense aquests fitxers talla les línies a prop d'on les talla la lletra real, en lloc de desbordar els marcs amb una font de reserva més ampla. Les variants que la família no té en fitxer es componen amb les variants del fallback del mateix pes i inclinació, amb el nom de la família amb llicència, a les previsualitzacions, al worker de maquetació, al PDF i a la línia d'ordres. Una família amb fitxers els conserva i només pren del fallback la inclinació que no té, una cursiva per exemple; els pesos intermedis entre els seus fitxers es trien com en qualsevol família. Al tauler Fonts, el camp Família de substitució (dins de la família, sobre els fitxers) en rep el nom; si el deixes buit, la família queda com estava. El PDF d'un llibre compost així incrusta la font oberta, de manera que el PDF definitiu es fa amb els fitxers amb llicència. Des de postext 1.42. Des de postext 1.43, la família oberta també va allà on no pot anar la família amb llicència: un EPUB o una exportació HTML, des del Sandbox o des de postext, porta les variants de la família de substitució amb el nom de la família amb llicència, i també les imatges SVG amb text en aquella família, de manera que el sistema de lectura compon el llibre amb una font de l'amplada per a la qual es van tallar les línies. Els fitxers propis de la família no surten mai del llibre. Una família sense fallback, o amb una família de substitució que no té fitxer, s'indica sense fitxers, com abans; la pestanya EPUB del Sandbox llista les famílies compostes amb una substituta.

#Comportament de renderització

Per dins:

  • Quan customFonts canvia, cada família declarada es registra automàticament com a FontFace a document.fonts, de manera que el visor HTML, la previsualització Canvas (que mesura amb document.fonts) i qualsevol referència CSS directa fan servir la variant personalitzada sense que calgui obrir abans el selector de fonts.
  • El worker de composició rep els mateixos ArrayBuffer pel mateix canal amb què es transfereixen les fonts, així que la mesura (buildFontString, pretext) funciona igual que amb una família del catàleg.
  • Si canvies o suprimeixes una variant, el worker descarta la variant que tenia a la memòria cau per a aquella família i la torna a registrar en la construcció següent, de manera que les previsualitzacions es mantenen sincronitzades amb el conjunt actual de variants.
  • Exportació a PDF: els fitxers pujats passen pel mateix PdfFontProvider. Els .woff2 es descomprimeixen; els .ttf i .otf es passen tal com són. Els .woff es rebutgen amb un missatge d'error clar (pdf-lib no pot incrustar WOFF sense descomprimir: torna'l a pujar com a .woff2/.ttf/.otf). L'OpenType amb taules CFF (.otf amb la signatura OTTO) s'incrusta sense subconjunt, perquè el generador de subconjunts CFF de pdf-lib recorre tots els glifs en fer save() i es pot quedar encallat durant minuts amb fonts reals; si no es fa el subconjunt, el PDF és una mica més gran, però el temps de renderitzat és constant. La font es declara com a CFF (CIDFontType0, FontFile3 / CIDFontType0C), de manera que el preflight d'impremta en reconeix el format; una font CFF amb claus CID (Source Han, els .otf de Noto CJK) manté la declaració TrueType.

#Avisos de fonts que falten

El tauler Revisió del Sandbox mostra al grup Fonts tres errors propis de les fonts personalitzades (tots controlats pel mateix interruptor debug.warnings.missingFont que ja controla l'avís genèric de font no carregada):

  • Família de fonts desconeguda: un fontFamily fa referència a un nom que no tenen ni Google Fonts ni Fontsource i que no és una família personalitzada declarada en aquell moment. També apareix immediatament quan suprimeixes una família personalitzada a què encara fa referència algun camp fontFamily, sense esperar que se n'adoni el DOM.
  • Falta una variant de font: la família existeix, però el llibre li demana un pes i un estil dels quals no hi ha cap fitxer: encapçalaments en negreta, per exemple, en una família que només té la rodona. L'avís llista les combinacions que falten. Una inclinació que posa el fallback de la família no compta com a falta.
  • Variant de font duplicada: dos o més fitxers tenen la mateixa combinació de pes i estil dins d'una mateixa família. En renderitzar només se'n fa servir un; l'avís et recorda que corregeixis les entrades sobrants.

Si fas clic en qualsevol d'aquests avisos, s'obre el tauler Fonts perquè hi pugis la variant que falta, hi tornis a afegir la família o resolguis els duplicats.

Quan ja hi ha una maquetació, el tauler també mostra l'avís del motor Font substituïda a la composició (fontFallback): una variant que les pàgines no han pogut fer servir en mesurar el text, perquè falta o perquè el navegador la dibuixa a partir d'un altre pes o d'una altra inclinació. Una família que ja surt com a desconeguda o amb una variant que falta no hi apareix dues vegades. Abans de la primera composició, n'ocupa el lloc una comprovació contra document.fonts.

El quadre també mostra Caràcters presos d'una altra font (glyphFallback): caràcters que el text posa en una font que no té glif per a ells, un cop per font, amb la família genèrica que els ha dibuixat (serif, sans-serif, monospace) quan la comprovació ho pot saber.

#Font de símbols

Una font de text poques vegades té les lletres i els operadors matemàtics (∪, ℵ, ∀), el grec o les fletxes que l'autor escriu en un paràgraf. symbolFont anomena una família que els compon: totes les fonts del document la porten darrere de la seva, de manera que el llenç, el PDF, l'HTML i l'EPUB dibuixen aquests caràcters amb ella en lloc d'una caixa buida. 'Noto Sans Math' cobreix gairebé tota la matemàtica. Al Sandbox és a Text de cos → Font de símbols. El fitxer de Word maquetat també posa aquests caràcters en trams d'ella. La seva cara rodona normal els dibuixa en tots els pesos i inclinacions del text.

La maquetació avisa de cada paràgraf que porta aquests caràcters amb glyphFallbackAt, amb la família que els dibuixa, o sense cap: el PDF els imprimeix llavors com a caixes buides. El Sandbox els marca a la pàgina, en violeta els que dibuixa la font de símbols i en vermell els que no dibuixa cap.

#Estils de xifres

figureStyle demana a la font d'un estil de text un joc de xifres concret, amb les funcions OpenType de la font: xifres elzevirianes al text corrent, xifres alineades tabulars a les taules. El camp és a bodyText, paragraphStyles[], headings i headings.levels[], headingStyles[], tableStyle i tableStyles[] (cel·les de capçalera i de cos per igual), captionStyle (etiqueta i descripció, i el captionStyle d'un tipus de recurs) i els elements de text d'un disseny (capçaleres, folis, els textos d'una portadella o d'una pàgina de part). Al Sandbox és el camp Xifres del tauler Disseny, al costat del tipus de lletra de cadascun d'aquests estils (Text de cos → Tipus de lletra per al cos).

ValorFuncions OpenTypeXifres
'default'capLes pròpies de la font. Treu les xifres que un estil hereta.
'oldstyle'onumXifres elzevirianes, amb ascendents i descendents com les minúscules: text corrent.
'lining'lnumXifres alineades, de l'alçada de les majúscules: encapçalaments, text en versals.
'tabular'tnumTotes les xifres amb la mateixa amplada, perquè els dígits d'una columna quedin en filera. La forma continua sent la de la font.
'proportional'pnumCada xifra amb la seva amplada. La forma continua sent la de la font.
'oldstyle-tabular'onum + tnumXifres elzevirianes amb una sola amplada.
'oldstyle-proportional'onum + pnumXifres elzevirianes amb amplades pròpies.
'lining-tabular'lnum + tnumXifres alineades amb una sola amplada: taules, horaris, llistes de preus.
'lining-proportional'lnum + pnumXifres alineades amb amplades pròpies.

Un parell fixa una forma i una amplada. Una font que no té la funció conserva les seves xifres, així que comprova que la font té onum o lnum abans de comptar-hi. Una família de la qual l'amfitrió no té cap fitxer, com una font instal·lada només al sistema del lector (el Sandbox no les descarrega), no pren cap estil de xifres: el text conserva les xifres pròpies d'aquesta font, en la mateixa font. Un llibre que puja fitxers amb aquest nom sí que obté les xifres. Els talls que serveixen Google Fonts i Fontsource sovint deixen fora onum i lnum (el fitxer latin de Source Serif 4 només conserva pnum i tnum); amb un fitxer així, un estil que les demana conserva les xifres pròpies de la font. Els fitxers complets de la foneria les tenen: puja'ls per obtenir xifres elzevirianes o alineades. Una família genèrica (serif, sans-serif) no pren funcions. Un valor que no és a la llista es notifica com a valor de paràmetre desconegut (unknownConfigValue, vegeu Avisos de configuració) i es llegeix com si no hi fos.

const config: PostextConfig = {
  bodyText: { fontFamily: 'EB Garamond', figureStyle: 'oldstyle' },
  tableStyle: { figureStyle: 'lining-tabular' },
  paragraphStyles: [{ id: 'timetable', figureStyle: 'lining-tabular' }],
  headings: { figureStyle: 'lining' },
};

El text compon els anys i els números de pàgina amb xifres elzevirianes, i també els peus i les llistes, que prenen la família del cos. Les cel·les de totes les taules i els paràgrafs de l'estil timetable alineen els dígits amb xifres alineades tabulars. Tots els nivells d'encapçalament posen xifres alineades en la família dels encapçalaments.

#Quines xifres pren cada estil

  • Un estil que pren la família d'un altre també en pren les xifres. Els estils de paràgraf, les taules, els peus, les llistes i el cos dels requadres prenen la família del cos quan no en nomenen cap altra, de manera que bodyText.figureStyle arriba a tots.
  • Un estil que nomena el seu fontFamily posa les xifres per defecte d'aquesta font, tret que també fixi figureStyle.
  • Un nivell d'encapçalament sense figureStyle propi pren headings.figureStyle, també en el seu fontFamily quan en nomena un. El figureStyle d'un estil d'encapçalament s'aplica a la família del nivell on es fa servir l'estil.
  • Un element de text d'un disseny nomena la seva família ('EB Garamond' per defecte), així que les xifres del cos no arriben a un foli: posa-hi figureStyle: 'oldstyle' perquè lligui amb un text en xifres elzevirianes.
  • 'default' posa les xifres pròpies de la font i anul·la les heretades: paragraphStyles: [{ id: 'plain', figureStyle: 'default' }] treu a aquest estil les xifres elzevirianes del cos.

#Les xifres a cada sortida

El text es mesura amb les funcions, de manera que les línies tallen a les mateixes amplades a la previsualització del Canvas, l'HTML, el PDF i l'EPUB, en maquetació fixa i en maquetació fluida.

  • Previsualització del Canvas i worker de maquetació: el navegador declara un altre cop els fitxers de la família base amb un nom de família amb funcions i el descriptor featureSettings de FontFace. El nom és la família seguida de les funcions després de @ (EB Garamond@onum, EB Garamond@lnum+tnum), i apareix a les cadenes de font i en alguns avisos.
  • HTML i EPUB (maquetació fixa i fluida): la família base, amb font-variant-numeric (oldstyle-nums, lining-nums tabular-nums).
  • PDF: incrusta els fitxers de la família base i compon el text amb les funcions.
  • Línia d'ordres: Skia, el canvas amb què dibuixa postext, no aplica funcions. La línia d'ordres registra una còpia de la font el cmap de la qual porta cada caràcter que substitueixen les funcions, els dígits, al glif que trien. Només es prenen les substitucions simples; una font que arriba a les xifres amb substitucions contextuals hi conserva les seves.

#Paleta de colors

La propietat colorPalette de PostextConfig permet definir un conjunt reutilitzable de colors amb nom i fer-hi referència des de qualsevol ColorValue de la configuració. És l'equivalent a Postext de les propietats personalitzades de CSS o del tauler de mostres d'InDesign: canvia l'entrada una sola vegada i tots els colors que hi apuntin s'actualitzen al document.

interface ColorPaletteEntry {
  id: string;       // identificador estable — referenciat per ColorValue.paletteId
  name: string;     // etiqueta llegible que es mostra a les UI del sandbox
  value: ColorValue;
}

#La paleta per defecte

Postext inclou una paleta per defecte amb una única entrada anomenada Color principal (id: 'main-color', hex #295AA3). Diversos valors per defecte (el color dels encapçalaments, de les negretes i cursives del cos, dels :ref, de les vinyetes i dels números de les llistes) fan referència a aquesta entrada amb paletteId: 'main-color', de manera que, si canvies aquesta sola mostra, canvia el color de tots els elements del document que la fan servir.

Pots inspeccionar, clonar o comparar la paleta per defecte amb tres exportacions:

import {
  DEFAULT_COLOR_PALETTE,
  cloneDefaultColorPalette,
  isDefaultColorPalette,
} from 'postext';
 
// Instantània de només lectura de la paleta publicada.
DEFAULT_COLOR_PALETTE;
// => [{ id: 'main-color', name: 'Main Color', value: { hex: '#295AA3', model: 'hex' } }]
 
// Còpia independent — muta aquesta, no DEFAULT_COLOR_PALETTE.
const palette = cloneDefaultColorPalette();
 
// Comprova si l'usuari ha personalitzat la paleta.
isDefaultColorPalette(palette); // true

La paleta viu al nivell superior de la configuració:

const config: PostextConfig = {
  colorPalette: [
    { id: 'tinta',  name: 'Tinta',  value: { hex: '#0a0a0a', model: 'cmyk' } },
    { id: 'acento', name: 'Acento', value: { hex: '#b8860b', model: 'hex' } },
  ],
  bodyText: { color: { hex: '#000000', model: 'cmyk', paletteId: 'tinta' } },
  headings: { color: { hex: '#000000', model: 'hex', paletteId: 'acento' } },
};

#Fer referència a una entrada de la paleta

Qualsevol ColorValue de la configuració pot portar un camp opcional paletteId que apunta a una entrada de colorPalette: fons de pàgina, colors del text de cos (inclòs el dels :ref), colors dels encapçalaments, filets de columna, colors de les llistes, colors de les taules, dels peus, dels xips i dels requadres (caixa, franja, icona, marcador, etiqueta, títol i cos), color de les marques de tall i de la retícula de base, indicadors de depuració, i tots els colors d'un disseny: les capçaleres i els peus, les obertures i els dissenys en columna dels encapçalaments, els dissenys i les capçaleres dels estils d'encapçalament, les pàgines de part i les files de part de l'índex (text, filet, farciment i vora de caixa, contorn, caplletra). Si hi és, el hex / model de l'entrada de la paleta tenen prioritat sobre el hex / model desats com a reserva. El valor de reserva només es fa servir si la paleta no hi és, és buida o no conté aquell id, cosa útil quan distribueixes una configuració que llegirà una eina que no entén les paletes.

Canvi a postext 1.5. Fins a postext 1.4, la paleta només arribava a una llista fixa de paràmetres. Els altres (els colors dels dissenys, com capçaleres, obertures, estils d'encapçalament, parts i files de l'índex; bodyText.referenceColor; els colors de les etiquetes dels requadres, i els de la negreta i la cursiva del cos dels requadres) conservaven el hex desat al costat del paletteId. Un document amb un valor desat que no coincideix amb l'entrada de la paleta (tots els editats al Sandbox després de canviar l'entrada, i tots els :ref quan el color principal no és #295AA3) ara imprimeix el color de la paleta, tal com indica l'enllaç. Per conservar un color tal com era, treu-ne el paletteId.

Un tint d'una entrada de la paleta. Amb paletteId, tint (0–100) pinta l'entrada a aquesta intensitat: { hex: '#eef2f8', model: 'hex', paletteId: 'main-color', tint: 8 } és el color principal al 8 %, un fons de requadre que segueix el color principal quan canvia la paleta. La paleta d'una part o d'una secció manté la intensitat a tot arreu on canvia el color: el text corregut, el color de la pàgina, els números de línia, les cel·les de taula, les zones de disseny i l'exportació a Word. El tint conserva el model de l'entrada: una entrada CMYK dona les seves tintes escalades (el 10 % de 100 60 0 10 imprimeix 10 6 0 1), una entrada de tinta plana dona un tint de la mateixa tinta a la seva pròpia planxa, i un color de pantalla es barreja amb el color de la pàgina (page.backgroundColor, blanc si no es defineix; sota un tint CMYK, un color de pàgina definit en CMYK hi afegeix les seves tintes). hex desa el valor ja tintat, el de reserva sense l'entrada. Un tint de tinta plana porta una sola tinta: sobre una pàgina de color, buida el color de la pàgina tret que sobreimprimeixi. Al Sandbox, el selector d'un color vinculat té un camp Tint.

#Com s'apliquen les paletes

buildDocument aplica la paleta en dos moments perquè els colors enllaçats funcionin tant en els valors que hagis indicat tu com en els valors per defecte que s'afegeixen després:

  1. applyPaletteToConfig(config): resol cada ColorValue amb paletteId de la configuració original. És útil per veure què rebrà realment el motor.
  2. applyPaletteToResolvedConfig(resolved, palette): s'executa després de resoldre els valors per defecte i reescriu els valors per defecte enllaçats a la paleta (color dels encapçalaments, de la negreta/cursiva del cos, dels :ref, de les llistes, els colors dels dissenys per defecte) perquè coincideixin amb la paleta activa.

Totes dues recorren la configuració sencera, així que cap color enllaçat a la paleta no es queda enrere. La majoria dels colors del flux de text (cos, encapçalaments, llistes, taules, peus, xips, la caixa, el títol i el cos dels requadres) surten com a valors sense enllaç. Tots els altres —els colors dels dissenys, el dels :ref, les etiquetes dels requadres— agafen el hex / model de la paleta i conserven el seu paletteId. Aquest enllaç és el que l'atribut palette d'una part i el palette d'un estil d'encapçalament substitueixen a les seves pàgines (vegeu Parts), així que ha de sobreviure. htmlViewer.overrides es deixa tal qual: el visor HTML el fusiona primer, i la paleta que porti s'aplica llavors a tot, dissenys inclosos.

Poques vegades cal cridar-les, però totes dues s'exporten perquè les puguis inspeccionar o reutilitzar:

import {
  applyPaletteToConfig,
  applyPaletteToResolvedConfig,
  resolveColorValue,
} from 'postext';
 
const flat = applyPaletteToConfig(config);
// Cada ColorValue amb paletteId al config original porta ara el
// hex/model de l'entrada de la paleta (un color de disseny conserva el seu paletteId).
 
// `applyPaletteToResolvedConfig` normalment el gestiona buildDocument; fes-lo servir
// directament si construeixes un ResolvedConfig a mà i vols aplicar-hi la paleta.

resolveColorValue(value, palette, fallback) és la variant per a un únic valor, útil quan compons configuracions de manera imperativa i has de resoldre un color solt.

#Editar la paleta

Un color amb un paletteId que no correspon a cap entrada imprimeix el hex / model desat, que pot ser anterior al color que li donava l'entrada. Per això, abans de suprimir una entrada, convé reescriure cada ColorValue enllaçat a ella com un color sense enllaç amb el valor actual de l'entrada. La secció Paleta del Sandbox (Disseny → Colors) ho fa quan esborres una entrada, sigui on sigui el color (dissenys i etiquetes de requadre inclosos), i el diàleg de confirmació llista tots els paràmetres que la fan servir, pel nom o per la ruta a la configuració (header.elements[2].color).

#Visor HTML

La propietat htmlViewer controla com el backend HTML disposa les pàgines a la pantalla. Només s'aplica quan renderitzes amb renderToHtml / renderToHtmlIndexed; el canvas i el PDF la ignoren completament, perquè fan servir directament els valors configurats de page.width, page.height i page.dpi.

interface HtmlViewerConfig {
  maxCharsPerLine?: number;     // Amplada objectiu de columna, en caràcters de la font del cos.
  columnGap?: number;            // Espai horitzontal entre columnes en mode multicolumna (px).
  optimalLineBreaking?: boolean; // Usar Knuth–Plass dins del visor HTML en lloc de greedy.
  overrides?: HtmlViewerOverrides; // Configuració parcial només per a pantalla, fusionada sobre la del document.
}
 
type HtmlViewerOverrides = Omit<PostextConfig, 'htmlViewer'>;
PropietatTipusPer defecteDescripció
maxCharsPerLinenumber70Mesura objectiu de cada columna renderitzada, expressada en caràcters de la font del cos. El visor mesura una cadena representativa de text d'aquesta llargada per obtenir l'amplada real en píxels; així, el resultat s'adapta a qualsevol combinació de font proporcional i mida.
columnGapnumber50Espai horitzontal, en píxels CSS, entre columnes quan el visor és en mode de diverses columnes. S'ignora en mode d'una sola columna.
optimalLineBreakingbooleantrueTalla les línies del visor HTML amb Knuth–Plass, els mateixos talls òptims que fan el canvas i el PDF: l'edició en pantalla no perd qualitat davant de la impresa. Amb true el visor segueix bodyText.optimalLineBreaking, de manera que un document que compon el text línia a línia ho manté en pantalla. Posa'l a false per omplir cada línia abans de passar a la següent, més ràpid en un llibre molt llarg. Una configuració desada amb configVersion 21 o anterior que no l'indica es llegeix com a false, tal com es va maquetar aleshores.
overridesHtmlViewerOverrides—Una configuració parcial del document que només s'aplica a la pantalla. El visor HTML la fusiona sobre la configuració del document abans de compondre (applyHtmlViewerOverrides); canvas i PDF la ignoren. Els objectes es fusionen recursivament; una llista levels (encapçalaments, llistes, índex) es fusiona entrada a entrada per level; qualsevol altra llista (els elements d'una zona de disseny, calloutStyles, colorPalette…) substitueix completament la llista base. Ús típic: un inici de capítol sense les bandes de la versió impresa, o una pàgina de part amb un títol que es parteix en línies al costat del número en lloc d'una amplada fixa de la caixa de tall. El Sandbox l'edita com a JSON.
const config: PostextConfig = {
  headings: { levels: [{ level: 1, span: 'page', breakBefore: { enabled: true } }] },
  htmlViewer: {
    // A la pantalla, els capítols van seguits, sense l'inici a pàgina sencera.
    overrides: { headings: { levels: [{ level: 1, span: 'column', breakBefore: { enabled: false } }] } },
  },
};

El resolver i l'stripper segueixen el mateix patró que les altres seccions:

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 quan tot coincideix amb els valors per defecte

Consulta Integrar el visor HTML més avall per veure'n un exemple complet.

#Visor Canvas

La propietat canvasViewer fixa l'espai entre les pàgines a la pestanya Canvas del Sandbox (des de postext 1.43). Pertany al visor, no al llibre: els valors són píxels de pantalla a qualsevol zoom, i canviar-los mou les pàgines en pantalla sense tornar a compondre el llibre, de manera que la paginació, les composicions desades i el PDF no canvien. El PDF, el visor HTML i les altres sortides l'ignoren. Un llibre amb imatges a doble pàgina fa servir 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).
}
PropietatTipusPer defecteDescripció
pageGapnumber24Espai, en píxels de pantalla, entre la pàgina esquerra i la dreta d'un parell a la vista de doble pàgina. Un enter de 0 a 200. Amb 0 les dues pàgines es toquen i el Canvas no dibuixa ombra ni cantonades arrodonides a la unió, de manera que una imatge o un disseny a doble pàgina es llegeix com un de sol. La vista de pàgina única no té parells.
rowGapnumber24Espai, en píxels de pantalla, entre una fila de pàgines i la següent, a les dues vistes. Un enter de 0 a 200.
const config: PostextConfig = {
  // Una imatge travessa la doble pàgina: es mostren les dues pàgines unides.
  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 defaults

Un valor que no sigui un enter de 0 a 200 es llegeix com l'enter més proper d'aquest rang, o com 24 si no és un número, i s'avisa com a valor d'ajust desconegut (canvasViewer.pageGap). El Sandbox té els dos camps a Disseny › Exportació › Canvas (espai entre pàgines).

#Generació de PDF (configuració)

La propietat pdfGeneration controla com genera el PDF final el generador de PDF. Aquests paràmetres els fa servir el paquet postext-pdf en el moment d'exportar; els visors canvas i HTML els ignoren. forms és l'excepció: el canvas també el llegeix, de manera que els seus camps de formulari coincideixen amb els del PDF.

buildDocument els passa al VDT, com a doc.config.pdfGeneration, i renderToPdf pren cada paràmetre del primer d'aquests llocs que el defineixi:

  1. les seves pròpies opcions (outlines, accessible, colorSpace, baselineGrid, forms);
  2. el pdfGeneration del primer document que rep (en un llibre, els paràmetres del primer capítol valen per a tot el fitxer);
  3. els valors per defecte: marcadors i etiquetatge activats, color RGB.

Així, renderToPdf(doc, { fontProvider }) segueix la configuració, i una opció que es passa a renderToPdf només té prioritat en aquell paràmetre. forceColorSpace i colorSpace equivalen junts a l'opció colorSpace: el colorSpace de la configuració s'aplica mentre forceColorSpace està activat, i amb aquest desactivat el PDF surt en RGB. Les versions anteriors de postext-pdf només llegien les opcions; ara una configuració amb pdfGeneration canvia el PDF encara que es cridi sense opcions.

type PdfColorSpace = 'rgb' | 'cmyk' | 'grayscale';
 
interface PdfGenerationConfig {
  outlines?: boolean;          // Emetre marcadors PDF a partir de l'arbre d'encapçalaments.
  forceColorSpace?: boolean;   // Convertir tots els colors a `colorSpace`.
  colorSpace?: PdfColorSpace;  // Espai de destinació quan `forceColorSpace` és true.
  accessible?: boolean;        // Sortida etiquetada orientada a PDF/UA (arbre d'estructura, text alternatiu, llengua).
  baselineGrid?: boolean;      // Dibuixar també al PDF la retícula de base de `page.baselineGrid`.
  forms?: PdfFormsConfig;      // Camps de formulari: moneda, separadors, lletra.
}
PropietatTipusPer defecteDescripció
outlinesbooleantrueEmet outlines (marcadors) PDF a partir de la jerarquia d'encapçalaments, de manera que els lectors puguin saltar directament a qualsevol encapçalament des de la barra lateral del visor PDF. Desactiva'l per a documents en què l'arbre d'encapçalaments no aporta res (per exemple, pòsters d'una sola pàgina).
forceColorSpacebooleanfalseQuan és true, en exportar es converteixen a colorSpace tots els colors del PDF. Deixa'l desactivat en PDF per a pantalla si els colors d'entrada ja són a l'espai que vols; activa'l per garantir un sol espai de color quan els colors vénen d'orígens diferents.
colorSpace'rgb' | 'cmyk' | 'grayscale''cmyk'Espai de color de destinació que s'usa quan forceColorSpace està activat. Fes servir 'cmyk' per a impremta òfset, 'rgb' per a PDF només de pantalla i 'grayscale' per a proves en blanc i negre. No té cap efecte si forceColorSpace és false. El CMYK se separa amb el perfil de sortida de print (FOGRA39 per defecte) i el seu tractament del negre, i també es converteixen les imatges RGB; una norma PDF/X definida allà escriu CMYK digui el que digui aquest paràmetre.
accessiblebooleantrueGenera un PDF accessible i etiquetat, orientat a PDF/UA-1: un arbre d'estructura lògica en ordre de lectura (encapçalaments que mai no salten cap nivell, paràgrafs, llistes, cites, requadres, taules amb cel·les de capçalera, figures amb el seu text alternatiu i el seu peu, fórmules, referències com a enllaços, l'índex d'un :::toc com un sol TOC amb un TOCI per fila: el número de la fila com a Lbl, el seu títol i la seva pàgina com un Reference que conté l'enllaç), el títol i la llengua del document (el locale de primer nivell), la identificació PDF/UA a les metadades XMP, i tots els elements decoratius (fons de pàgina, filets, retícula de base, capçaleres i peus de pàgina, marques de tall, capçaleres de taula repetides, el títol repetit i la marca de continuació d'un requadre partit) marcats com a artefactes perquè els lectors de pantalla els ometin. Una figura sense altText fa servir el peu i, si no en té, l'etiqueta. Una figura o una taula flotant es llegeix just després del text que la cita per primera vegada, o del text anterior a la seva línia ::resource, i un requadre flotant, després del text anterior a la seva línia d'obertura, encara que el flotant quedi en una pàgina posterior; una llista o un índex que continuen després d'un flotant queden en un sol element, i una llista dins d'un requadre flotant o ancorat a la pàgina (placement: 'fixed') és una sola llista. Desactiva'l només en originals d'impremta on l'estructura addicional no calgui.
baselineGridbooleantrueDibuixa al PDF la retícula de base mentre page.baselineGrid està activada. Activat per defecte, com fins ara; amb false la retícula queda com a guia per comprovar la pàgina a la pantalla, fora del PDF, i el llenç i el visor HTML la continuen mostrant. Al Sandbox és Retícula de base al PDF, a la secció PDF.
formsPdfFormsConfigundefinedCom escriuen els nombres els camps de formulari i en quina lletra mostren els valors: currency (per defecte €), currencyBefore (per defecte true), separatorStyle (de 0 a 3; si no es fixa, segons l'idioma del document) i font ('chip', el valor per defecte, 'helvetica' o { family, weight?, style? }). L'opció forms de renderToPdf i del canvas té prioritat camp a camp. Només afecta la sortida: no canvia la composició. Vegeu Camps de formulari.
pdfGeneration: {
  outlines: true,
  accessible: true,
  forceColorSpace: true,
  colorSpace: 'cmyk',
}

El resolver i l'stripper segueixen el mateix patró que les altres seccions:

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 quan tot coincideix amb els valors per defecte

Consulta Generació de PDF més avall per a la recepta completa d'exportació.

#Producció per a impremta (configuració)

La propietat print indica com es prepara un llibre per a la impremta: la norma PDF/X del fitxer, el perfil de sortida amb què se separa el CMYK, com s'imprimeix el negre i els llindars del preflight. La composició la ignora, així que canviar-la no mou mai cap línia. La fan servir tres components: postext-pdf quan escriu el fitxer, preflightDocument quan revisa un document maquetat, i la simulació d'impressió dels visors canvas i Folio.

type PdfXStandard = 'none' | 'pdfx1a' | 'pdfx4';
 
interface PrintConfig {
  standard?: PdfXStandard;                 // 'none': un PDF normal.
  outputProfile?: string;                  // Un id del catàleg ('fogra39', 'fogra51'…) o 'custom'.
  customProfile?: CustomOutputProfile;     // Un fitxer .icc pujat.
  renderingIntent?: 'relative' | 'perceptual';
  blackPointCompensation?: boolean;
  convertImages?: boolean;                 // Separar les imatges RGB (PDF/X-1a sempre ho fa).
  inkLimit?: number;                       // Cobertura total d'àrea, en percentatge.
  black?: PrintBlackConfig;
  preflight?: PrintPreflightConfig;
  inks?: PrintInk[];                       // La taula de tintes: noms, àlies, quadricromia.
  plates?: PrintPlatesConfig;              // Les planxes del treball: impressió a dues tintes.
  imageColor?: PrintImageColorConfig;      // Com es llegeixen les imatges: perfils, grisos.
}
 
interface CustomOutputProfile {
  name: string;           // La seva descripció, o el nom del fitxer.
  fileId: string;         // El fitxer .icc desat.
  registryName?: string;  // El nom de la condició al registre ICC (FOGRA51…); si no, 'Custom'.
  inkLimit?: number;
}
PropietatTipusPer defecteDescripció
standard'none' | 'pdfx1a' | 'pdfx4''none'La variant PDF/X del fitxer. 'pdfx1a' escriu PDF/X-1a:2003: només CMYK i gris, sense transparències, i l'accepta qualsevol impremta. 'pdfx4' escriu PDF/X-4: conserva les transparències i la gestió de color, per als fluxos actuals. Totes dues separen cada color amb el perfil de sortida, digui el que digui pdfGeneration.colorSpace.
outputProfilestring'fogra39'La condició d'impressió per a la qual se separa el CMYK: un id del catàleg de perfils, o 'custom' per a customProfile. Un id que no és al catàleg, o 'custom' sense fitxer, torna al valor per defecte i rep un avís de configuració.
customProfileCustomOutputProfilecapUn perfil de sortida CMYK que aportes tu, el que et doni la impremta (el PSOcoated_v3.icc de l'ECI, per exemple). Els bytes es desen a part, com els d'una font; renderToPdf els rep a l'opció outputProfile. registryName s'escriu a la condició de sortida (output intent) com a identificador de la condició d'impressió.
renderingIntent'relative' | 'perceptual''relative'El colorimètric relatiu manté exactes els colors que la màquina pot imprimir i porta la resta al color imprimible més proper; el perceptual comprimeix tota la gamma perquè els colors fora de gamma conservin les relacions entre ells.
blackPointCompensationbooleantrueAmb el propòsit colorimètric relatiu, converteix el negre de la pantalla en el negre més fosc que imprimeix la màquina, perquè els tons més foscos conservin el detall en lloc d'empastar-se.
convertImagesbooleantrueSepara en CMYK les imatges RGB amb el perfil. PDF/X-1a ho fa sempre. En PDF/X-4, false les deixa en RGB, etiquetades com a sRGB amb el /DefaultRGB de les pàgines, perquè les converteixi el RIP de la impremta. Els JPEG en CMYK i en gris s'insereixen sempre tal com són.
inkLimitnumberel del perfilEl total més alt de C+M+Y+K, en percentatge, que accepta el preflight. Per defecte és el límit amb què separa el perfil (300 % a la majoria de condicions d'òfset, 230 % al paper de diari IFRA26).
blackPrintBlackConfigvegeu NegreGrisos només en K, sobreimpressió i negre enriquit.
preflightPrintPreflightConfigvegeu PreflightQuè revisa el preflight i amb quins llindars.
print: {
  standard: 'pdfx4',
  outputProfile: 'fogra51',
  black: { richBlackColor: { c: 60, m: 40, y: 40, k: 100 } },
  preflight: { minImageResolution: 300, safeZone: { value: 5, unit: 'mm' } },
}

#Perfils de sortida

postext inclou aquests perfils de sortida CMYK a la carpeta icc/ (postext/icc/<id>.icc a qualsevol CDN de npm, i /icc/<id>.icc a postext.dev). Cap d'ells no té restriccions de drets d'autor conegudes (CC0): els perfils FOGRA, GRACoL, SWOP i de diari de colord, generats a partir de les dades de caracterització de cada condició, i FOGRA51 i FOGRA52, que postext ha construït amb ArgyllCMS a partir de les dades de la mateixa Fogra. Els perfils de l'ECI (ISO Coated v2, PSO Coated v3, PSO Uncoated v3) descriuen les mateixes condicions però no es poden redistribuir; puja'ls com a perfil personalitzat si la teva impremta te'ls demana.

IdCondicióNom al registreLímit de tinta
fogra39Òfset, paper estucat (condició ISO Coated v2)FOGRA39300 %
fogra51Òfset, estucat prèmium (condició PSO Coated v3)FOGRA51300 %
fogra52Òfset, sense estucar i sense fusta (condició PSO Uncoated v3)FOGRA52300 %
fogra47Òfset, sense estucar blanc (PSO Uncoated ISO 12647)FOGRA47300 %
fogra29Òfset, sense estucar blancFOGRA29300 %
fogra30Òfset, sense estucar groguencFOGRA30340 %
fogra27Òfset, estucat (ISO 12647-2:1996)FOGRA27300 %
fogra28Òfset de bobina heatset, LWC brillantFOGRA28300 %
fogra45Òfset de bobina heatset, LWC milloratFOGRA45300 %
fogra40Òfset de bobina heatset, paper SCFOGRA40340 %
gracol2006GRACoL 2006, estucat de grau 1CGATS TR 006300 %
swop3SWOP 2006, estucat de grau 3CGATS TR 003300 %
swop5SWOP 2006, estucat de grau 5CGATS TR 005300 %
ifra26Paper de diari coldset (ISO 12647-3)IFRA26230 %
snap2007Paper de diari SNAP 2007CGATS TR 002320 %

renderToPdf llegeix els bytes del perfil de la seva opció outputProfile; si no els té, baixa el fitxer del catàleg de profileBaseUrl (per defecte https://cdn.jsdelivr.net/npm/postext/icc/). Una sortida PDF/X amb un perfil que no es pot carregar falla; una sortida CMYK normal fa servir la fórmula estàndard, amb un avís outputProfileUnavailable.

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 i PDF/X-4

Totes dues normes escriuen:

  • la condició de sortida (GTS_PDFX), que indica la condició d'impressió i incrusta el perfil de destinació;
  • la identificació al diccionari Info (GTS_PDFXVersion, /Trapped /False, el títol i les dates) i a les metadades XMP (pdfxid:GTSPDFXVersion, els identificadors del document i de la versió), fusionada amb la identificació PDF/UA quan el fitxer és etiquetat;
  • una TrimBox i una BleedBox a cada pàgina (la pàgina sencera quan no hi ha marques de tall);
  • l'/ID del tràiler;
  • cada color en DeviceCMYK (o en gris) a través del perfil, i les marques de tall en color de registre;
  • cap anotació d'enllaç: un fitxer per a impremta no en porta cap dins de la seva caixa de sang, així que els enllaços del PDF de pantalla queden fora (els marcadors es mantenen).

PDF/X-1a:2003 és PDF 1.4 sense fluxos d'objectes i no admet transparències: un color translúcid es compon tal com s'imprimiria sobre el paper, l'alfa d'una imatge s'aplana sobre blanc i el negatiu de pàgina de depuració queda fora (amb un avís pageNegativeIgnored). PDF/X-4 és PDF 1.6: les transparències es mantenen, cada pàgina rep un grup de transparència que es fusiona en CMYK, i les imatges RGB que conserva convertImages: false s'etiqueten com a sRGB amb /DefaultRGB.

Un original d'impremta en PDF (svg.pdfFileId) s'insereix tal com és, així que els colors, les fonts i les transparències són els del fitxer; el preflight informa del que hi aporta.

#Negre

interface PrintBlackConfig {
  kOnlyNeutrals?: boolean;      // Grisos i negre només amb tinta negra.
  overprint?: boolean;          // El 100 % K sobreimprimeix.
  richBlack?: boolean;          // Masses negres grans en negre enriquit.
  richBlackColor?: CmykPercent; // { c, m, y, k } en percentatge.
  richBlackMinSize?: Dimension; // El costat menor que necessita una massa.
}
PropietatTipusPer defecteDescripció
kOnlyNeutralsbooleantrueUn color neutre (#000000, #808080…) s'imprimeix només amb tinta negra, amb la K triada perquè la lluminositat coincideixi, mai com un gris de quatricromia que canvia amb el registre. Les imatges conserven la generació de negre del perfil.
overprintbooleantrueEl que es pinta només amb 100 % K (text negre, filets, traços, formes negres petites) sobreimprimeix (op/OP amb OPM 1), així un error de registre de les planxes no deixa mai una vora blanca al voltant. Tota la resta reserva; les imatges i els degradats no sobreimprimeixen mai.
richBlackbooleantrueUn emplenament negre amb un costat menor que arriba a richBlackMinSize (un fons, una banda, una caixa) s'imprimeix en richBlackColor i reserva, perquè es vegi profund i no gris fosc. El text no passa mai a negre enriquit.
richBlackColorCmykPercent{ c: 60, m: 40, y: 40, k: 100 }La recepta del negre enriquit, en percentatge. Mantén-ne el total per sota del límit de tinta; el preflight ho comprova.
richBlackMinSizeDimension6mmEl costat menor que necessita una massa negra per imprimir-se en negre enriquit.

#Simulació de la impressió

Una pàgina del canvas es pot pintar tal com s'imprimirà. createPrintPreview(transform, print, { paper, dpi, grayscale }) construeix la prova en pantalla d'una configuració: cada píxel se separa amb el perfil (neutres només en K, com al PDF) i es torna a mostrar en pantalla, sobre el blanc del paper quan paper és true; les masses negres prou grans per al negre enriquit es veuen en negre enriquit. Amb grayscale, la prova és la d'una impressió en escala de grisos: un PDF forçat a escala de grisos imprimeix la luminància de cada color només en tinta negra, sense negre enriquit. Passa-la a renderPageToCanvas com a printPreview. Per a una vista de treball, no per a una prova, guides hi afegeix les línies del tall, de la sang i de la zona de seguretat, i marksFor encercla zones d'una pàgina (els rect del preflight); el Sandbox deixa fora totes dues coses, de manera que la seva previsualització mostra només el que s'imprimeix. postext-folio rep el mateix objecte com a printPreview; amb paper: true, dona mentrestant al llibre un to de paper neutre (folio.paper.shade), o el paper es tenyeix dues vegades.

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) },
});

#Motor de color

La gestió de color que fa servir postext s'exporta per a les teves pròpies eines. Llegeix perfils ICC v2 i v4 (matriu/TRC i les taules de consulta mft1, mft2, mAB, mBA) en TypeScript pur, sense WebAssembly.

  • parseIccProfile(bytes) llegeix un perfil; deviceChannels(profile) en dona el nombre de canals.
  • outputTransform(profile, { intent, blackPointCompensation, preserveNeutrals }) retorna fromRgb(r, g, b) (sRGB 0..1 → CMYK 0..1), toLab(cmyk, paper?) i proof(cmyk, paper?) (CMYK → sRGB de pantalla).
  • cmykToLab, labToCmyk, srgbToLab, labToSrgb, deltaE i totalAreaCoverage són les conversions soltes; buildRgbLut / sampleRgbLut creen i llegeixen taules denses per treballar amb píxels.
  • OUTPUT_PROFILES, outputProfileInfo(id) i loadOutputProfile(id, baseUrl?) donen el catàleg; srgbProfileBytes() escriu el perfil sRGB amb què PDF/X-4 etiqueta l'RGB; authoredCmykColors(config) llista els colors que una configuració defineix en CMYK.

Les funcions de resolució i d'eliminació de valors per defecte segueixen el patró de les altres seccions: resolvePrintConfig, stripPrintDefaults i profileInkLimit(config) (el límit del perfil que indica una configuració, abans que cap inkLimit el substitueixi), amb DEFAULT_PRINT_CONFIG, DEFAULT_PRINT_BLACK_CONFIG, DEFAULT_PRINT_PREFLIGHT_CONFIG i DEFAULT_RICH_BLACK.

#Comprovació del contrast (configuració)

La propietat contrast fixa la comprovació que diu si el text d'un llibre es pot llegir: cada color de text davant del fons sobre el qual es compon. La composició la ignora, així que canviar-la no mou mai cap línia. contrastDocument la fa servir quan revisa un document maquetat, el Sandbox llista les incidències a Revisió i mostra la ràtio al costat de cada camp de color, i postext check les imprimeix.

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 }[];
}
PropietatTipusPer defecteDescripció
enabledbooleantrueExecuta la comprovació.
level'AA' | 'AAA''AA'El nivell de WCAG 2 que s'exigeix a les ràtios. Vegeu Llindars.
modestring'auto'El mitjà que es comprova: 'screen', 'print', 'both' o 'auto', que comprova sempre la pantalla i també la impremta en un llibre preparat per a impremta (una norma PDF/X a print.standard, un PDF en CMYK a pdfGeneration o marques de tall a page.cutLines).
reversedText.enabledbooleantrueInforma del text calat a la comprovació per a impremta.
reversedText.minSizeDimension8ptS'avisa del text calat per sota d'aquest cos.
reversedText.minFineSizeDimension12ptEl mateix per a cursives i pesos fins, de traç més prim.
reversedText.lightWeightnumber300Un pes igual o inferior a aquest compta com a fi.
allowContrastAllowEntry[][]Parells de colors que la comprovació accepta, cadascun amb la seva reason: pel color del text (fg) i el del fons (bg), per l'style amb què va el text, o per tots dos. Vegeu Parells acceptats.

Un level o un mode escrit de qualsevol altra manera es llegeix com el valor per defecte i genera un avís de valor de paràmetre desconegut (vegeu Avisos de configuració).

#Parells acceptats

Una adaptació conserva la paleta de l'original, i alguns dels seus parells queden sota el llindar: una tinta clara darrere del text d'un requadre, un color de marca en un titolet. allow els accepta sense apagar la comprovació (des de postext 1.52). Una entrada anomena el color del text fg i el del fons bg (en hexadecimal, tal com els escriu la configuració o com es pinten), o un style: l'id d'un estil de requadre (calloutStyles, o l'style d'un marc de pàgina composta), de paràgraf, de títol, d'etiqueta en línia o de rètol de figura. Tots els camps que dona una entrada han de coincidir, així que { style: 'note', fg: '#7a8a99' } accepta aquest gris només dins dels requadres note. Una entrada que no dona cap dels tres no coincideix amb res.

contrast: {
  allow: [
    { fg: '#b7820f', bg: '#ffffff', reason: "L'ocre de l'editorial per als titolets" },
    { style: 'nota-marge', reason: "L'original compon les notes al marge en un gris clar" },
  ],
}

Un parell acceptat es continua assenyalant: cada troballa que hi coincideix porta accepted (la reason de l'entrada, amb el seu fg, el seu bg i el seu style), i les troballes acceptades van després de les altres. El Sandbox les mostra a Comprovacions, sota Parells de contrast acceptats, amb el motiu, i no les compta; postext check les imprimeix com a notes, que no fan fallar --strict. Els mateixos colors fora del que anomena l'entrada continuen sent un avís.

#Llindars

La ràtio a què ha d'arribar un text depèn del seu cos i del seu pes, com a WCAG 2.

NivellTextText gran
AA4,5:13:1
AAA7:14,5:1

És text gran el de 18 pt o més, o el de 14 pt o més amb un pes de 700 o superior. Els cossos són els impresos, en punts. Un superíndex o un subíndex es jutja amb el cos del text al qual pertany.

#Pantalla i impremta

Postext compon les mateixes pàgines per a una pantalla i per a una màquina d'imprimir, i un color no es llegeix igual en totes dues.

  • Pantalla és la ràtio de contrast de WCAG 2 dels colors sRGB, (L1 + 0.05) / (L2 + 0.05) sobre les seves luminàncies relatives: el que mostren el canvas, el visor HTML, un EPUB i un PDF en RGB.
  • Impremta és la mateixa fórmula sobre la luminància que cada color té sobre el paper. El color se separa amb el perfil de sortida del treball (un de definit en CMYK conserva els seus valors), la separació es torna a llegir a través del perfil i la seva luminància es pren en relació amb el paper sense imprimir, que és el blanc d'una pàgina impresa com el blanc del monitor és el d'una pantalla. La tinta no és mai un negre perfecte: el negre massís sobre blanc dona uns 14:1 en paper estucat (FOGRA39, FOGRA51), 8:1 en paper sense estucar (FOGRA47, FOGRA52) i 5:1 en paper de diari (IFRA26, SNAP), on una pantalla dona 21:1. Un gris que passa en pantalla pot fallar sobre el paper: #767676 sobre blanc fa 4,54:1 en pantalla i uns 3,3:1 en paper estucat.

La ràtio d'impremta necessita la transformació del perfil de sortida (options.transform, construïda amb outputTransform). Sense aquesta transformació, per a impremta només es comprova el text calat.

#Text calat

El text clar calat sobre un fons de tinta s'empasta a màquina quan és petit o de traç fi: la tinta del fons s'escampa cap a dins de les lletres, i un fons fet de diverses tintes depèn també del registre de les planxes. La ràtio no ho mostra, perquè el blanc sobre blau fosc passa de 10:1. La comprovació per a impremta en dona un avís a part (reversedText) quan és per sota de minSize, o per sota de minFineSize si va en cursiva o amb un pes igual o inferior a lightWeight. Cada incidència diu amb quantes de les quatre tintes està fet el fons.

#Què es llegeix

La comprovació llegeix les línies de cada bloc amb els seus colors en línia (negreta, cursiva, referències, xips), els marcadors de llista, les caplletres, els peus, les notes i les cel·les de taula, i el text de les zones de disseny: capçaleres, obertures, dissenys d'encapçalament, títols de requadre. El fons és l'emplenament que hi ha immediatament sota el text: una caixa de disseny, un requadre, una barra de peu, una cel·la de taula, un xip o, si no n'hi ha cap, el color de la pàgina (page.backgroundColor, o el paper que la paleta d'una part dona a les seves pàgines). Un color translúcid es barreja amb el que té a sota. El text sobre una imatge se salta, perquè el seu fons no és un sol color, i també la retolació dels còmics, les lectures ruby i les fórmules. Les paraules dels rètols d'una figura es llegeixen sobre la seva placa o, si no, dins del seu halo; els rètols nus sobre la imatge s'ometen, com tot text sobre una imatge.

En una pàgina composta la comprovació segueix l'ordre en què es pinta la pàgina: els marcs per capa, amb la decoration de la plantilla a la capa 0. El text d'un marc es llegeix sobre la caixa del mateix marc quan el seu estil la pinta; si no, sobre la caixa de la decoració que té a sota (una imatge de la decoració el deixa fora, com qualsevol imatge), i si no, sobre el color de la pàgina. Així, unes lletres blanques sobre una pestanya de color de la decoració es mesuren contra aquella pestanya. Un marc girat o escalat es converteix a coordenades del full abans de llegir-ne el fons, i el text de la decoració mateixa es comprova igual. Des de postext 1.37.

#Executar la comprovació

contrastDocument(doc, options) retorna les incidències d'un document maquetat, de la ràtio més baixa a la més alta. Cadascuna porta el pageIndex absolut dins del llibre, el rect al full (px de pàgina) i l'interval al text font de la primera aparició, els dos colors tal com es pinten (color, background), el sizePt més petit en què es compon amb el seu weight i el seu italic, un role ('body', 'heading', 'caption', 'table', 'runningHead', 'design', 'chip', 'marker' o 'label', les paraules dels rètols d'una figura), el text del primer fragment i el count de fragments compostos així. Cada parell de colors genera un sol avís per llindar, sigui quin sigui el nombre de línies que el fan servir.

  • lowContrast afegeix level, large, required, la ràtio a cada mitjà comprovat (screen, print) i failing, els mitjans que queden per sota de required.
  • reversedText afegeix reasons ('small', 'italic', 'light'), minimumPt i inks.

Les opcions són contrast (els paràmetres resolts, quan no són els del document), media (els mitjans, digui el que digui mode) i 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) retorna tots els parells de text i fons que compon el document, passin o no, amb la seva ràtio screen, la ràtio print quan rep la transformació, la ràtio required i els colors tal com els escriu la configuració (textColor, groundColor): el que una eina de disseny mostra al costat d'un camp de color. S'executa digui el que digui enabled.

Les mesures s'exporten per a les teves pròpies eines:

  • contrastRatio(a, b) i relativeLuminance(color) donen la ràtio i la luminància de WCAG 2 de colors sRGB.
  • isLargeText(sizePt, weight) i contrastThreshold(level, large) donen el llindar d'un cos i un pes.
  • blendColors(top, under) dona un color translúcid sobre un altre, com a #rrggbb.
  • printContrastRatio(a, b, context), printLuminance(color, context) i printSeparation(color, context) donen el mateix sobre el paper. El context porta el transform i, com a authored, el resultat d'authoredCmykColors(config).
  • contrastMedia(doc.config, contrast) dona els mitjans en què es resol mode per a un document.

Les funcions de resolució i d'eliminació de valors per defecte segueixen el patró de les altres seccions: resolveContrastConfig i stripContrastDefaults, amb DEFAULT_CONTRAST_CONFIG, DEFAULT_CONTRAST_REVERSED_TEXT_CONFIG, CONTRAST_LEVELS i CONTRAST_MODES.

#Comprovació del contingut (configuració)

La propietat checks aplega les comprovacions que llegeixen la mateixa configuració. Avui en té una, contentInConfig, que avisa quan un disseny desa el text del llibre. Una capçalera, el disseny d'un encapçalament, una pàgina de part i la fila d'una part a l'índex general són forma: contenen marcadors ({chapterTitle}, {titleText}, {number}) i com a molt una o dues paraules pròpies, com Capítol davant de {chapterNumber}. El text que forma part del llibre va al Markdown, on el veuen l'índex, la cerca, les traduccions, el PDF etiquetat i l'EPUB. La composició no la llegeix, així que canviar-la no mou mai cap línia.

interface ChecksConfig {
  contentInConfig?: {
    enabled?: boolean;
    allow?: string[];
    maxWords?: number;
    maxChars?: number;
  };
}
PropietatTipusPer defecteDescripció
contentInConfig.enabledbooleantrueFa la comprovació.
contentInConfig.allowstring[][]Frases que un disseny pot repetir sense límit de llargada: el títol del llibre, el nom de l'editorial. Es comparen sense majúscules, espais ni la puntuació que envolta les paraules, i una frase que apareix dins d'un text més llarg es treu abans de comptar la resta.
contentInConfig.maxWordsnumber2Paraules que pot dur com a màxim un text de disseny a més dels marcadors.
contentInConfig.maxCharsnumber24Lletres i xifres que pot dur com a màxim un text de disseny a més dels marcadors. Un caràcter xinès, japonès, coreà o tai compta per tres, així que en passen uns vuit.

#Com es llegeix un text de disseny

  • El seu text literal és el content sense cap marcador ({name}, {attr.key}, {firstMark.key}), amb els escapaments {{ i }} llegits com a claus i \n com a salt de línia.
  • Un text sense lletres ni xifres (una filera de punts guia, un ornament, un ·) no és mai contingut.
  • Una paraula és el que queda entre espais i porta una lletra o una xifra: un · o una | solts no són paraules, i una adreça com postext.dev n'és una.
  • Primer es treuen les frases d'allow, i també el title, el subtitle, l'author i el publisher de les metadades del document (el seu front matter), que una capçalera sol repetir.
  • El que queda és contingut quan té més de maxWords paraules o més de maxChars lletres i xifres.

Es llegeixen totes les zones de disseny: header, footer, l'advancedDesign.slot de cada nivell d'encapçalament, l'advancedDesign.slot, el header i el footer de cada estil d'encapçalament, parts.design, parts.versoDesign, toc.parts.design, i el mateix dins d'htmlViewer.overrides. configDesignSlots(config) les enumera amb els seus camins, i designTextLiteral(content) retorna el text literal d'una plantilla.

#L'avís

collectConfigWarnings (i VDTDocument.configWarnings) dona un avís contentInConfig per cada paràmetre que desa contingut: un estil d'encapçalament (amb l'id a ownerId), un nivell d'encapçalament, la capçalera, el disseny de les parts. path indica el paràmetre, count els textos de disseny afectats, chars les seves lletres i xifres, elements el camí de cadascun (els 20 primers) i value el començament del primer (40 caràcters com a molt). Passa les metadades del document com a segon argument per permetre'n el títol i l'autor; una construcció ja ho fa sola.

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]', …] }]

Solució: porta el text al Markdown, com a títol, requadre o paràgraf del capítol a què pertany, i deixa només marcadors al disseny. Un valor que canvia a cada capítol pot anar a la línia del títol i llegir-se amb {attr.key}: # Mapes {kicker="Lliçó 4"} i {attr.kicker} al disseny. Una frase que és forma, com el nom de l'editorial en un títol corrent, va a allow.

El Sandbox mostra l'avís al tauler Revisió i té la comprovació a Disseny → Avançat → Contingut a la configuració; postext check l'imprimeix.

#Visor Folio (configuració)

La propietat folio decideix com presenta el visor Folio (postext-folio) el llibre imprès en 3D: l'angle de la vista, el paper, l'enquadernació, la superfície sobre la qual reposa el llibre i la llum. La composició la ignora, igual que la sortida canvas, HTML i PDF. buildDocument passa els paràmetres resolts al VDT, com a doc.config.folio, quan la configuració en fixa algun, així que un document sense aquests paràmetres conserva el hash de la seva maquetació.

interface FolioConfig {
  tilt?: number;                  // Graus des de la vertical, 0–70.
  yaw?: number;                   // Graus al voltant del llibre, −180–180.
  paper?: {
    type?: 'uncoated' | 'bookWove' | 'coatedMatte' | 'coatedSilk' | 'coatedGloss'
         | 'bible' | 'newsprint' | 'cardStock' | 'board';
    grammage?: number;            // g/m²
    bulk?: number;                // cm³/g; gruix µ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;          // id de recurs
  };
  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;
  };
}
PropietatTipusPer defecteDescripció
tiltnumber22Angle de la vista respecte a la vertical, en graus, limitat a 0–70. Amb 0 el llibre obert es veu pla des de dalt; amb un angle més gran el peu de les pàgines s'acosta i s'aprecia el gruix del bloc de pàgines.
yawnumber0Quant gira la vista al voltant del llibre, en graus, portat a −180–180. Amb 0 el llibre es veu des del peu de les seves pàgines; un angle positiu porta la mirada cap a la seva dreta i un de negatiu cap a la seva esquerra. Juntament amb tilt és la vista amb què s'obre el visor i a la qual torna resetView().
paper.typeFolioPaperType'uncoated'; 'newsprint' en un format de diariEl tipus de paper. Dona els valors per defecte dels cinc camps següents (vegeu la taula de papers). cardStock és cartolina de coberta; board és cartró rígid, com el d'un llibre de cartró, i els seus fulls passen sense doblegar-se.
paper.grammagenumberel del paperGramatge en grams per metre quadrat, 20–2500. Un paper de més gramatge és més gruixut, més rígid i més opac: el full es corba més obert i transparenta menys el revers.
paper.bulknumberel del paperMà: gruix per unitat de pes, en cm³/g, 0,5–3. El gruix d'un full en micres és gramatge × mà, i d'aquest valor i del nombre de pàgines en surt el llom del bloc.
paper.finishFolioPaperFinish'auto'Sense estucar (fibra, sense brillantor) o estucat i calandrat fins a mat, semimat (silk, una brillantor suau) o brillant. A Folio, una pàgina brillant reflecteix el full que hi passa per sobre. 'auto' agafa el del paper.
paper.textureFolioPaperTexture'auto'El relleu de la superfície: smooth (llisa, calandrada), vellum (vitel·la, un gra fi), wove (la textura uniforme de gairebé tots els papers de llibre, formada sobre una tela metàl·lica teixida), laid (verjurat: verjures juntes creuades per corondells més separats), linen (tela, un gofrat de fils creuats), felt (les marques irregulars d'un feltre). 'auto' agafa la del paper.
paper.textureStrengthnumber1Quant es marca la textura amb la llum, 0–2.
paper.shadeColorValueel del paperEl color del paper abans d'imprimir (blanc, natural, color d'os). Les pàgines s'imprimeixen damunt d'aquest color.
paper.showThroughbooleantrueEl revers de la pàgina es veu tènuement a través del paper fi. Després del paper bíblia, el paper de diari és el que més el deixa veure: la tinta penetra en el full.
binding.typeFolioBindingType'hardcover'; 'folded' en un format de diarihardcover: tapa dura (cartoné), tapes una mica més grans que les pàgines. paperback: rústica fresada (llom fresat i encolat), s'obre menys. sewn: rústica cosida. layflat: enquadernació plana, s'obre sense enfonsar-se al llom. saddleStitch: grapat a cavallet, fulls doblegats i grapats pel doblec, com una revista o un fullet; sense llom pla. folded (des de postext 1.18): un diari, fulls doblegats una vegada i posats l'un dins de l'altre sense res que els subjecti; sense grapes, sense llom i sense tapes, i la primera pàgina és la portada. Un tram :::paper amb shade imprimeix una secció, per exemple les pàgines d'economia, en paper de diari salmó.
binding.coverFolioCoverSource'case'Les cobertes. 'case' dibuixa una tapa al voltant de les pàgines. 'pages' agafa la primera pàgina del llibre com a cartró davanter i l'última, si és parella, com a cartró posterior: el llibre està tancat fins que es passa la coberta, els cartrons giren rígids i no es dibuixa cap tapa.
binding.coverMaterialFolioCoverMaterial'auto''auto' és tela en la tapa dura i cartolina ('paper') en les altres enquadernacions.
binding.coverColorColorValueblau fosc (#2c3e57)El color del material de la coberta.
binding.spineImagestringcapL'id d'un recurs de mapa de bits o SVG imprès al llom: el llom tal com es veu amb el llibre dret, el cap a dalt i la coberta a la dreta. S'ajusta fins a cobrir el llom, centrat. El grapat a cavallet i l'enquadernació plegada no el fan servir.
surface.typeFolioSurfaceType'oak'Sobre què reposa el llibre. 'none' deixa el fons de l'amfitrió.
surface.colorColorValuecapTenyeix la superfície; amb 'plain' és el seu color.
lighting.environmentFolioEnvironment'studio'L'entorn que reflecteixen els papers estucats i brillants, juntament amb la llum principal que projecta les ombres.
lighting.intensitynumber1Exposició, 0,25–2.
lighting.shadowsbooleantrueOmbres de la llum principal.

Els papers i els valors que aporten (FOLIO_PAPER_STOCKS), habituals a les fitxes tècniques dels fabricants:

PaperGramatgeMàGruixAcabatTexturaTo
uncoated (òfset sense estucar)90 g/m²1.25113 µmsense estucaruniforme#fcfbf8
bookWove (paper de llibre color d'os, mà alta)80 g/m²1.6128 µmsense estucaruniforme#f6efdc
coatedMatte (estucat mat)115 g/m²1.0115 µmmatllisa#fdfdfc
coatedSilk (estucat semimat)115 g/m²0.9104 µmsemimatllisa#ffffff
coatedGloss (estucat brillant)115 g/m²0.892 µmbrillantllisa#ffffff
bible (paper bíblia)40 g/m²1.144 µmsense estucarvitel·la#f9f6ee
newsprint (paper de diari)48 g/m²1.572 µmsense estucaruniforme#ebe7dc
cardStock (cartolina)250 g/m²1.2300 µmsense estucarvitel·la#fbfaf6
board (cartró)1250 g/m²1.62000 µmsemimatllisa#ffffff

Una novel·la en paper color d'os, en rústica fresada, damunt d'una taula de noguera sota un llum de lectura:

folio: {
  paper: { type: 'bookWove' },
  binding: { type: 'paperback', coverColor: { hex: '#8a2b1f', model: 'hex' } },
  surface: { type: 'walnut' },
  lighting: { environment: 'lamp' },
}

Una pàgina amb format de diari (page.sizePreset 'broadsheet', 'berliner', 'tabloid' o 'compact') es mostra com un diari quan la configuració no anomena paper ni enquadernació: paper newsprint i enquadernació folded (des de postext 1.18). El paper o l'enquadernació que anomeni la configuració es respecten, de manera que paper: { type: 'uncoated' } imprimeix un tabloide en paper òfset. Els camps del paper que es fixen sense anomenar el tipus (un grammage, un shade) s'apliquen al paper de diari. El resolvedor i el netejador reben el format com a segon argument, i folioForTrim(folio, sizePreset) escriu aquests dos valors a la configuració:

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');
// => undefined

Els colors segueixen els enllaços a la paleta com qualsevol altre color de la configuració (paletteId). El resolvedor i el netejador funcionen com a les altres seccions; el netejador treu els valors del paper que coincideixen amb els del tipus triat:

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' } }

Al Sandbox aquests ajustos formen el grup Folio del tauler Disseny (Disseny → Folio → Visor Folio (3D)), i la pestanya Folio els mostra a mesura que els canvies, sense tornar a compondre el llibre. El visor en si es descriu a Un llibre en 3D, i una tanda de pàgines en un altre paper, a Format del document › :::paper.

#Depuració

La propietat debug agrupa dos tipus d'ajudes per a l'autor: capes visuals que mantenen sincronitzats el text font i la composició renderitzada, i un conjunt d'avisos que mostren al tauler Revisió del Sandbox els problemes tipogràfics o estructurals del document. Cap dels dos no afecta la sortida exportada.

PropietatTipusDescripció
cursorSyncSyncIndicatorConfigCursor reflectit a la composició renderitzada; vegeu Superposicions visuals.
selectionSyncSyncIndicatorConfigSelecció del text font ressaltada a la pàgina; vegeu Superposicions visuals.
looseLineHighlightLooseLineHighlightConfigCapa sobre les línies justificades fluixes; vegeu Superposicions visuals.
pageNegative{ enabled: boolean }Negatiu d'alt contrast de la pàgina; vegeu Superposicions visuals.
warningsWarningsToggleConfigUn booleà per a cada tipus d'avís que mostra l'editor; vegeu Avisos.

#Superposicions visuals

PropietatTipusPer defecteDescripció
cursorSync.enabledbooleantrueMostra un cursor en la composició renderitzada que reflecteix la posició del cursor a la font.
cursorSync.colorColorValue#2563ebColor d'aquest cursor.
selectionSync.enabledbooleantrueRessalta l'interval renderitzat que coincideix amb la selecció a la font.
selectionSync.colorColorValue#fde04780Color del ressaltat; per defecte, un groc translúcid.
looseLineHighlight.enabledbooleanfalsePinta una superposició sobre les línies justificades amb un espaiat entre paraules que supera threshold vegades l'amplada de l'espai normal.
looseLineHighlight.colorColorValue#ff000040Color d'aquesta superposició.
looseLineHighlight.thresholdnumber3Multiplicador de l'amplada de l'espai normal a partir del qual una línia justificada compta com a fluixa. L'avís looseLines fa servir el mateix llindar. Una línia justificada amb espais que passarien de 3 vegades la seva amplada es compon en bandera, de manera que amb el valor per defecte la capa i l'avís gairebé no troben res en el text corregut; abaixa'l (1.5 o 2) per veure les línies fluixes que continuen justificades.
pageNegative.enabledbooleanfalseRenderitza un negatiu d'alt contrast sobre la pàgina, útil per revisar d'un cop d'ull la forma general d'una doble pàgina (densitat del text, equilibratge de columnes, espai en blanc) sense que et distregui el detall dels glifs.
fitMarks'all' | 'problems' | 'none''problems'Quines marques d’ajust dibuixa el canvas del Sandbox sobre les pàgines compostes per a qui no hagi triat a la barra del canvas: totes, només els marcs que no hi caben i els aspectes desconeguts, o cap. Mana la tria del lector. Des de postext 1.52.
fitMarksMinScalenumber1Un marc compost a aquesta escala o més gran no porta distintiu d’escala (amb 0.95 només es marquen els que queden per sota del 95 %). El text i les imatges es miren per separat.

Cada SyncIndicatorConfig és { enabled: boolean; color?: ColorValue }. LooseLineHighlightConfig és { enabled: boolean; color?: ColorValue; threshold?: number }. pageNegative és un simple interruptor { 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 },
}

Aquestes capes les dibuixa el Sandbox sobre la previsualització Canvas. No formen part de la pàgina: ni renderPage, ni la sortida HTML, ni el PDF no les pinten mai.

#Línies fluixes al teu propi canvas

El motor exporta el ressaltat de línies fluixes com a dues funcions auxiliars, per a una pàgina que pintes tu:

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 });
 
// Les mateixes línies com a dades: un informe, una capa SVG, un recompte per pàgina.
for (const { ratio, line, block } of findLooseLines(doc, { threshold: 2.5 })) {
  console.log(`pàgina ${block.pageIndex + 1}: ${ratio.toFixed(2)}× — ${line.text}`);
}
  • findLooseLines(doc, { threshold?, pageIndex? }) retorna, en ordre de lectura, cada línia justificada amb un espaiat entre paraules que supera threshold: { block, line, ratio, x, y, width, height }. ratio és lineWordSpacing(line): l'espaiat tal com el fiten minWordSpacing i maxWordSpacing (justifiedSpaceLimitRatio quan la línia conté espais d'un altre estil, i si no justifiedSpaceRatio), de manera que una línia composta al límit amb un espai en negreta no surt amb un llindar igual a maxWordSpacing. El rectangle, en píxels de pàgina, és la franja que cobreix el ressaltat: tota l'amplada del bloc a l'alçada de la línia. Són les línies que el Sandbox ressalta i per a les quals el tauler Revisió dona l'avís looseLine.
  • drawLooseLines(ctx, page, doc, { threshold?, color? }) omple aquestes franges en una pàgina i retorna les línies que ha pintat. Dibuixa en píxels de pàgina amb la transformació actual del context, així que crida-la just després de renderPage o renderPageToCanvas sobre el mateix canvas: totes dues deixen el context escalat a la pàgina. color és qualsevol estil d'emplenament del canvas.
  • Valors per defecte. Les dues funcions fan servir el llindar (3) i el color (#ff000040) per defecte, no el debug.looseLineHighlight del document: aquest paràmetre és del Sandbox. Per seguir una configuració, passa resolveDebugConfig(config.debug).looseLineHighlight.threshold i .color.hex.

#Avisos

debug.warnings controla quins problemes d'autoria apareixen al tauler Revisió del Sandbox (s'edita a Disseny → Avançat → Avisos). Cada clau és un interruptor booleà independent; posa'n una a false per silenciar aquell avís concret sense desactivar els altres.

Aquests interruptors només filtren el tauler del Sandbox. Els avisos que registra el mateix motor (les caixes que desborden la columna, a doc.warnings; els ids de recurs, directives, insercions i ids d'estil desconeguts i les graelles de taula irregulars, a doc.contentWarnings) hi són diguin el que diguin els interruptors, i els renderitzadors comuniquen les imatges que pinten com a requadre buit; vegeu Avisos del document.

interface WarningsToggleConfig {
  missingFont?: boolean;
  looseLines?: boolean;
  headingHierarchy?: boolean;
  consecutiveHeadings?: boolean;
  listAfterHeading?: boolean;
  designIssues?: boolean;
}
PropietatTipusPer defecteDescripció
missingFontbooleantrueAvisa quan una font referenciada per la configuració no s'ha pogut carregar al navegador. Detecta errades a fontFamily i paquets @fontsource/... que falten abans que acabin substituïts sense avís per una font de reserva a la sortida.
looseLinesbooleantrueAvisa de les línies justificades amb un espaiat entre paraules que supera debug.looseLineHighlight.threshold. Complementa la capa de ressaltat: l'avís les llista al tauler, i la capa les mostra al seu lloc.
headingHierarchybooleantrueAvisa de nivells d'encapçalament que se salten un nivell; per exemple, un H1 seguit directament d'un H3. Els salts en la jerarquia solen indicar una errada en el nivell de l'encapçalament o una confusió sobre l'estructura del document.
consecutiveHeadingsbooleanfalseAvisa quan un encapçalament va seguit immediatament d'un altre encapçalament, sense cap paràgraf ni llista entremig. Desactivat per defecte perquè els encapçalaments encadenats són legítims en moltes plantilles (títol + subtítol, capítol + epígraf); activa'l en manuscrits on cada encapçalament ha d'introduir prosa.
listAfterHeadingbooleanfalseAvisa quan una llista comença immediatament després d'un encapçalament, sense paràgraf introductori. Desactivat per defecte perquè el material de referència sol fer-ho; activa'l en escriptura narrativa on cada llista hauria d'estar emmarcada per prosa.
designIssuesbooleantrueAvisa de problemes d'integritat a les zones de disseny: capçaleres, peus de pàgina, l'obertura de part i la pàgina parella en blanc que la segueix, les files de part de l'índex, zones de disseny avançat dels encapçalaments, i el disseny i les capçaleres i peus de secció de cada estil d'encapçalament. Detecta cadenes d'ancoratge circulars i ancoratges trencats (un element ancorat a un #id que ja no existeix), un encapçalament a amplada de pàgina amb el breakBefore desactivat, i un disseny avançat habilitat amb elements que no renderitzen mai {titleText}.
debug: {
  warnings: {
    missingFont: true,
    looseLines: true,
    headingHierarchy: true,
    consecutiveHeadings: true,
    listAfterHeading: false,
    designIssues: true,
  },
}

A més d'aquests, el tauler mostra sempre els avisos que emet la mateixa maquetació (VDTDocument.warnings), com ara un requadre que desborda la columna (calloutOverflow), i els valors de configuració que el motor va substituir (VDTDocument.configWarnings, o collectConfigWarnings(config); vegeu Avisos de configuració més avall).

#Avisos de configuració

Aquests errors de la mateixa configuració no passen mai sense avís, i cap interruptor no els amaga, llevat del que s'indica a l'últim punt. El motor no falla per cap d'ells: substitueix el valor, o prescindeix del paràmetre, i ho indica.

  • Format de numeració desconegut: un numberFormat de llista numerada, un page.pageNumbering.format o el counterFormat d'un tipus de recurs que no és cap de les grafies dels formats de numeració. Numera en decimal.
  • Llista de fonts en una família: un fontFamily (o qualsevol …FontFamily) que conté una llista de fonts CSS. El text es compon en la primera família de la llista (vegeu Una sola família per fontFamily).
  • Columna lateral sense lloc: un sideColumnPercent d'una disposició 'oneAndHalf' (la del document, o el layout propi d'un estil d'encapçalament) que deixaria alguna de les columnes per sota de l'1% de l'amplada de l'àrea de contingut, o que no és un nombre. Les columnes es tallen al valor més proper que admeten totes dues, i used ho indica (sideColumnPercentClamped; vegeu la disposició 'oneAndHalf').
  • Nombre de columnes fora de rang: un columnCount d'una disposició 'multiple' (la del document, o el layout propi d'un estil d'encapçalament) que no és un nombre enter de 3 a 8. La pàgina es divideix en el nombre vàlid més proper (3 si el valor no és un nombre), i used l'indica (columnCountClamped; vegeu la disposició 'multiple').
  • Retícula de caràcters massa gran: un cjk.grid amb més caràcters per línia o més línies per pàgina dels que caben entre els marges. La retícula es compon amb els que hi caben, i used n'indica el nombre (cjkGridClamped; vegeu Retícula de caràcters).
  • Paràmetre d'encapçalament desconegut: una clau que no existeix a headings, headings.balancing, un nivell d'encapçalament, un estil d'encapçalament o un estil de paràgraf: un letterSpacng mal escrit, un tracking pres d'una altra eina, un level en un estil d'encapçalament, un fontStyle: 'italic' en un estil de paràgraf (que porta italic: true). Una tabulació es comprova igual (un leaders per leader), i també una caplletra, lineNumbers, canvasViewer, checks, codeStyle i els paràmetres de còmic. El motor la ignora (fins a postext 1.4 ho feia sense dir res). value és la clau, used és buit i suggestion indica el paràmetre al qual s'assembla més, quan se'n diferencia en una o dues lletres o només en les majúscules (unknownConfigKey).
  • Valor de paràmetre desconegut: un paràmetre que admet unes poques paraules en conté una altra, com ara direction: 'right' (admet auto, ltr o rtl). El motor llegeix en el seu lloc el valor per defecte, i used diu en què ha quedat: per a direction, la direcció de la llengua del document (unknownConfigValue). L'align d'una tabulació que no és cap de les seves quatre paraules es llegeix com a 'start', i una position que no és una longitud, 'end' ni un percentatge deixa fora la tabulació (used és 'none'). També es comproven les paraules dels paràmetres de còmic (Còmics › Avisos de còmic): used és el valor en què s'ha resolt el paràmetre (el valor per defecte propi d'un estil de bafarada, si és un estil integrat), i suggestion indica la paraula a què més s'assembla el valor, quan n'hi ha una de propera. El level i el mode de la comprovació del contrast es comproven igual: used és 'AA' o 'auto'. canvasViewer.pageGap i canvasViewer.rowGap es comproven igual: used és l'enter de 0 a 200 amb què es va llegir el valor (des de postext 1.43). També print.standard, print.outputProfile i print.renderingIntent (used és el que va donar el valor per defecte), i un maxWords o maxChars de checks.contentInConfig que no sigui un enter igual o més gran que 0.
  • Números de línia en text vertical: lineNumbers.enabled: true en un document compost en vertical (layout.writingMode: 'vertical-rl'). Les pàgines verticals no porten números de línia, i used és false (lineNumbersUnsupported; vegeu Numeració de línies).
  • Text al voltant en escriptura vertical: el defaultPlacement.wrap d'un tipus de recurs en un document compost en vertical. Les pàgines verticals no componen text al costat d'una figura, i used és none (wrapUnsupported; vegeu Format del document › Ajust del text). Un wrap que no indica cap costat és un valor de paràmetre desconegut.
  • Estil de requadre basat en un altre: un estil de requadre amb un extends que no correspon a cap estil de calloutStyles (calloutStyleExtendsUnknown, amb l'id més semblant a suggestion), o amb una cadena d'extends que torna a l'estil (calloutStyleExtendsCycle, amb el bucle a → b → a a value). L'estil queda independent, amb els valors per defecte en el que no fixa (vegeu Estils basats en un altre).
  • Plantilles de pàgina i estils de rètol: un problema a pageTemplates o labelStyles: un id o un nom repetit, extends, ancoratges o marcs encadenats que formen un bucle, un estil, marc o plantilla que no existeix, un mínim més gran que el seu màxim, un estil de rètol d'una àncora que labelStyles no té (es comprova quan es passen els recursos: collectConfigWarnings(config, { resources })). El seu path és un punter JSON (/pageTemplates/3/frames/2/style); cada tipus apareix amb la causa i la solució a Avisos de les plantilles de pàgina.
  • Contingut en un disseny: un element de text de disseny amb un text que, sense comptar els marcadors, és més llarg que una etiqueta breu, és a dir, text del llibre desat a la configuració. Un avís per paràmetre (un estil d'encapçalament, la capçalera, el disseny de les parts), amb el camí de cada text (contentInConfig; vegeu Comprovació del contingut). A diferència dels altres, es pot desactivar: checks.contentInConfig.enabled: false.

El Sandbox els mostra al tauler Revisió amb la ruta del paràmetre. En codi, buildDocument els deixa al document com a configWarnings (absent quan la configuració està neta), i collectConfigWarnings(config) els retorna sense maquetar res:

import { buildDocument, collectConfigWarnings } from 'postext';
 
// JavaScript sense tipus: en TypeScript, 'roman' ni tan sols passa la comprovació de tipus.
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); // la mateixa llista

També es revisa cada configuració parcial niada: estils d'encapçalament, les llistes dins de les parts, htmlViewer.overrides, elements de disseny.

formatWarning (vegeu Avisos del document) també els descriu, amb la ruta del paràmetre al davant (bodyText.fontFamily: font stack "EB Garamond, serif" — set in "EB Garamond", headingStyles[0].letterSpacng: unknown setting "letterSpacng" — ignored (did you mean "letterSpacing"?)), de manera que un amfitrió pot registrar en un sol bucle les tres llistes que retorna la composició.