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ó
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:
- Afegir una família de fonts: crea una família buida; li pots canviar el nom allà mateix.
- Pujar fitxer: tria un pes (100–900) i un estil (normal / cursiva), i selecciona un o diversos fitxers
.woff2,.woff,.ttfo.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. - 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.
- 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
customFontscanvia, cada família declarada es registra automàticament com aFontFaceadocument.fonts, de manera que el visor HTML, la previsualització Canvas (que mesura ambdocument.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
ArrayBufferpel 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.woff2es descomprimeixen; els.ttfi.otfes passen tal com són. Els.woffes 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 (.otfamb la signaturaOTTO) s'incrusta sense subconjunt, perquè el generador de subconjunts CFF de pdf-lib recorre tots els glifs en fersave()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.otfde 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
fontFamilyfa 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 campfontFamily, 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
fallbackde 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).
| Valor | Funcions OpenType | Xifres |
|---|---|---|
'default' | cap | Les pròpies de la font. Treu les xifres que un estil hereta. |
'oldstyle' | onum | Xifres elzevirianes, amb ascendents i descendents com les minúscules: text corrent. |
'lining' | lnum | Xifres alineades, de l'alçada de les majúscules: encapçalaments, text en versals. |
'tabular' | tnum | Totes 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' | pnum | Cada xifra amb la seva amplada. La forma continua sent la de la font. |
'oldstyle-tabular' | onum + tnum | Xifres elzevirianes amb una sola amplada. |
'oldstyle-proportional' | onum + pnum | Xifres elzevirianes amb amplades pròpies. |
'lining-tabular' | lnum + tnum | Xifres alineades amb una sola amplada: taules, horaris, llistes de preus. |
'lining-proportional' | lnum + pnum | Xifres 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.figureStylearriba a tots. - Un estil que nomena el seu
fontFamilyposa les xifres per defecte d'aquesta font, tret que també fixifigureStyle. - Un nivell d'encapçalament sense
figureStylepropi prenheadings.figureStyle, també en el seufontFamilyquan en nomena un. ElfigureStyled'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-hifigureStyle: '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
featureSettingsdeFontFace. 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 elcmapde 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); // trueLa 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:
applyPaletteToConfig(config): resol cadaColorValueambpaletteIdde la configuració original. És útil per veure què rebrà realment el motor.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'>;| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
maxCharsPerLine | number | 70 | Mesura 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. |
columnGap | number | 50 | Espai horitzontal, en píxels CSS, entre columnes quan el visor és en mode de diverses columnes. S'ignora en mode d'una sola columna. |
optimalLineBreaking | boolean | true | Talla 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., 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. |
overrides | HtmlViewerOverrides | — | 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 defecteConsulta 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).
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
pageGap | number | 24 | Espai, 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. |
rowGap | number | 24 | Espai, 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 defaultsUn 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:
- les seves pròpies opcions (
outlines,accessible,colorSpace,baselineGrid,forms); - el
pdfGenerationdel primer document que rep (en un llibre, els paràmetres del primer capítol valen per a tot el fitxer); - 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.
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
outlines | boolean | true | Emet 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). |
forceColorSpace | boolean | false | Quan é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. |
accessible | boolean | true | Genera 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. |
baselineGrid | boolean | true | Dibuixa 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. |
forms | PdfFormsConfig | undefined | Com 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 defecteConsulta 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;
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
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. |
outputProfile | string | '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ó. |
customProfile | CustomOutputProfile | cap | Un 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. |
blackPointCompensation | boolean | true | Amb 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. |
convertImages | boolean | true | Separa 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. |
inkLimit | number | el del perfil | El 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). |
black | PrintBlackConfig | vegeu Negre | Grisos només en K, sobreimpressió i negre enriquit. |
preflight | PrintPreflightConfig | vegeu Preflight | Què 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.
| Id | Condició | Nom al registre | Límit de tinta |
|---|---|---|---|
fogra39 | Òfset, paper estucat (condició ISO Coated v2) | FOGRA39 | 300 % |
fogra51 | Òfset, estucat prèmium (condició PSO Coated v3) | FOGRA51 | 300 % |
fogra52 | Òfset, sense estucar i sense fusta (condició PSO Uncoated v3) | FOGRA52 | 300 % |
fogra47 | Òfset, sense estucar blanc (PSO Uncoated ISO 12647) | FOGRA47 | 300 % |
fogra29 | Òfset, sense estucar blanc | FOGRA29 | 300 % |
fogra30 | Òfset, sense estucar groguenc | FOGRA30 | 340 % |
fogra27 | Òfset, estucat (ISO 12647-2:1996) | FOGRA27 | 300 % |
fogra28 | Òfset de bobina heatset, LWC brillant | FOGRA28 | 300 % |
fogra45 | Òfset de bobina heatset, LWC millorat | FOGRA45 | 300 % |
fogra40 | Òfset de bobina heatset, paper SC | FOGRA40 | 340 % |
gracol2006 | GRACoL 2006, estucat de grau 1 | CGATS TR 006 | 300 % |
swop3 | SWOP 2006, estucat de grau 3 | CGATS TR 003 | 300 % |
swop5 | SWOP 2006, estucat de grau 5 | CGATS TR 005 | 300 % |
ifra26 | Paper de diari coldset (ISO 12647-3) | IFRA26 | 230 % |
snap2007 | Paper de diari SNAP 2007 | CGATS TR 002 | 320 % |
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'
/IDdel 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.
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
kOnlyNeutrals | boolean | true | Un 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. |
overprint | boolean | true | El 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. |
richBlack | boolean | true | Un 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. |
richBlackColor | CmykPercent | { 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. |
richBlackMinSize | Dimension | 6mm | El 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 })retornafromRgb(r, g, b)(sRGB 0..1 → CMYK 0..1),toLab(cmyk, paper?)iproof(cmyk, paper?)(CMYK → sRGB de pantalla).cmykToLab,labToCmyk,srgbToLab,labToSrgb,deltaEitotalAreaCoveragesón les conversions soltes;buildRgbLut/sampleRgbLutcreen i llegeixen taules denses per treballar amb píxels.OUTPUT_PROFILES,outputProfileInfo(id)iloadOutputProfile(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 }[];
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
enabled | boolean | true | Executa la comprovació. |
level | 'AA' | 'AAA' | 'AA' | El nivell de WCAG 2 que s'exigeix a les ràtios. Vegeu Llindars. |
mode | string | '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.enabled | boolean | true | Informa del text calat a la comprovació per a impremta. |
reversedText.minSize | Dimension | 8pt | S'avisa del text calat per sota d'aquest cos. |
reversedText.minFineSize | Dimension | 12pt | El mateix per a cursives i pesos fins, de traç més prim. |
reversedText.lightWeight | number | 300 | Un pes igual o inferior a aquest compta com a fi. |
allow | ContrastAllowEntry[] | [] | 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.
| Nivell | Text | Text gran |
|---|---|---|
AA | 4,5:1 | 3:1 |
AAA | 7:1 | 4,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:
#767676sobre 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.
lowContrastafegeixlevel,large,required, la ràtio a cada mitjà comprovat (screen,print) ifailing, els mitjans que queden per sota derequired.reversedTextafegeixreasons('small','italic','light'),minimumPtiinks.
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)irelativeLuminance(color)donen la ràtio i la luminància de WCAG 2 de colors sRGB.isLargeText(sizePt, weight)icontrastThreshold(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)iprintSeparation(color, context)donen el mateix sobre el paper. El context porta eltransformi, com aauthored, el resultat d'authoredCmykColors(config).contrastMedia(doc.config, contrast)dona els mitjans en què es resolmodeper 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;
};
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
contentInConfig.enabled | boolean | true | Fa la comprovació. |
contentInConfig.allow | string[] | [] | 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.maxWords | number | 2 | Paraules que pot dur com a màxim un text de disseny a més dels marcadors. |
contentInConfig.maxChars | number | 24 | Lletres 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
contentsense cap marcador ({name},{attr.key},{firstMark.key}), amb els escapaments{{i}}llegits com a claus i\ncom 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 compostext.devn'és una. - Primer es treuen les frases d'
allow, i també eltitle, elsubtitle, l'authori elpublisherde les metadades del document (el seu front matter), que una capçalera sol repetir. - El que queda és contingut quan té més de
maxWordsparaules o més demaxCharslletres 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;
};
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
tilt | number | 22 | Angle 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. |
yaw | number | 0 | Quant 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.type | FolioPaperType | 'uncoated'; 'newsprint' en un format de diari | El 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.grammage | number | el del paper | Gramatge 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.bulk | number | el del paper | Mà: 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.finish | FolioPaperFinish | '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.texture | FolioPaperTexture | '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.textureStrength | number | 1 | Quant es marca la textura amb la llum, 0–2. |
paper.shade | ColorValue | el del paper | El color del paper abans d'imprimir (blanc, natural, color d'os). Les pàgines s'imprimeixen damunt d'aquest color. |
paper.showThrough | boolean | true | El 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.type | FolioBindingType | 'hardcover'; 'folded' en un format de diari | hardcover: 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.cover | FolioCoverSource | '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.coverMaterial | FolioCoverMaterial | 'auto' | 'auto' és tela en la tapa dura i cartolina ('paper') en les altres enquadernacions. |
binding.coverColor | ColorValue | blau fosc (#2c3e57) | El color del material de la coberta. |
binding.spineImage | string | cap | L'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.type | FolioSurfaceType | 'oak' | Sobre què reposa el llibre. 'none' deixa el fons de l'amfitrió. |
surface.color | ColorValue | cap | Tenyeix la superfície; amb 'plain' és el seu color. |
lighting.environment | FolioEnvironment | 'studio' | L'entorn que reflecteixen els papers estucats i brillants, juntament amb la llum principal que projecta les ombres. |
lighting.intensity | number | 1 | Exposició, 0,25–2. |
lighting.shadows | boolean | true | Ombres de la llum principal. |
Els papers i els valors que aporten (FOLIO_PAPER_STOCKS), habituals a les fitxes tècniques dels fabricants:
| Paper | Gramatge | Mà | Gruix | Acabat | Textura | To |
|---|---|---|---|---|---|---|
uncoated (òfset sense estucar) | 90 g/m² | 1.25 | 113 µm | sense estucar | uniforme | #fcfbf8 |
bookWove (paper de llibre color d'os, mà alta) | 80 g/m² | 1.6 | 128 µm | sense estucar | uniforme | #f6efdc |
coatedMatte (estucat mat) | 115 g/m² | 1.0 | 115 µm | mat | llisa | #fdfdfc |
coatedSilk (estucat semimat) | 115 g/m² | 0.9 | 104 µm | semimat | llisa | #ffffff |
coatedGloss (estucat brillant) | 115 g/m² | 0.8 | 92 µm | brillant | llisa | #ffffff |
bible (paper bíblia) | 40 g/m² | 1.1 | 44 µm | sense estucar | vitel·la | #f9f6ee |
newsprint (paper de diari) | 48 g/m² | 1.5 | 72 µm | sense estucar | uniforme | #ebe7dc |
cardStock (cartolina) | 250 g/m² | 1.2 | 300 µm | sense estucar | vitel·la | #fbfaf6 |
board (cartró) | 1250 g/m² | 1.6 | 2000 µm | semimat | llisa | #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');
// => undefinedEls 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.
| Propietat | Tipus | Descripció |
|---|---|---|
cursorSync | SyncIndicatorConfig | Cursor reflectit a la composició renderitzada; vegeu Superposicions visuals. |
selectionSync | SyncIndicatorConfig | Selecció del text font ressaltada a la pàgina; vegeu Superposicions visuals. |
looseLineHighlight | LooseLineHighlightConfig | Capa sobre les línies justificades fluixes; vegeu Superposicions visuals. |
pageNegative | { enabled: boolean } | Negatiu d'alt contrast de la pàgina; vegeu Superposicions visuals. |
warnings | WarningsToggleConfig | Un booleà per a cada tipus d'avís que mostra l'editor; vegeu Avisos. |
#Superposicions visuals
| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
cursorSync.enabled | boolean | true | Mostra un cursor en la composició renderitzada que reflecteix la posició del cursor a la font. |
cursorSync.color | ColorValue | #2563eb | Color d'aquest cursor. |
selectionSync.enabled | boolean | true | Ressalta l'interval renderitzat que coincideix amb la selecció a la font. |
selectionSync.color | ColorValue | #fde04780 | Color del ressaltat; per defecte, un groc translúcid. |
looseLineHighlight. | boolean | false | Pinta una superposició sobre les línies justificades amb un espaiat entre paraules que supera threshold vegades l'amplada de l'espai normal. |
looseLineHighlight.color | ColorValue | #ff000040 | Color d'aquesta superposició. |
looseLineHighlight. | number | 3 | Multiplicador 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.enabled | boolean | false | Renderitza 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. |
fitMarksMinScale | number | 1 | Un 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 superathreshold:{ block, line, ratio, x, y, width, height }.ratioéslineWordSpacing(line): l'espaiat tal com el fitenminWordSpacingimaxWordSpacing(justifiedSpaceLimitRatioquan la línia conté espais d'un altre estil, i si nojustifiedSpaceRatio), de manera que una línia composta al límit amb un espai en negreta no surt amb un llindar igual amaxWordSpacing. 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íslooseLine.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 derenderPageorenderPageToCanvassobre 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 eldebug.looseLineHighlightdel document: aquest paràmetre és del Sandbox. Per seguir una configuració, passaresolveDebugConfig(config.debug).looseLineHighlight.thresholdi.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;
}| Propietat | Tipus | Per defecte | Descripció |
|---|---|---|---|
missingFont | boolean | true | Avisa 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. |
looseLines | boolean | true | Avisa de les línies justificades amb un espaiat entre paraules que supera debug.. Complementa la capa de ressaltat: l'avís les llista al tauler, i la capa les mostra al seu lloc. |
headingHierarchy | boolean | true | Avisa 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. |
consecutiveHeadings | boolean | false | Avisa 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. |
listAfterHeading | boolean | false | Avisa 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. |
designIssues | boolean | true | Avisa 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
numberFormatde llista numerada, unpage.pageNumbering.formato elcounterFormatd'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 perfontFamily). - Columna lateral sense lloc: un
sideColumnPercentd'una disposició'oneAndHalf'(la del document, o ellayoutpropi 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, iusedho indica (sideColumnPercentClamped; vegeu la disposició'oneAndHalf'). - Nombre de columnes fora de rang: un
columnCountd'una disposició'multiple'(la del document, o ellayoutpropi 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), iusedl'indica (columnCountClamped; vegeu la disposició'multiple'). - Retícula de caràcters massa gran: un
cjk.gridamb 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, iusedn'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: unletterSpacngmal escrit, untrackingpres d'una altra eina, unlevelen un estil d'encapçalament, unfontStyle: 'italic'en un estil de paràgraf (que portaitalic: true). Una tabulació es comprova igual (unleadersperleader), i també una caplletra,lineNumbers,canvasViewer,checks,codeStylei 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 isuggestionindica 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'(admetauto,ltrortl). El motor llegeix en el seu lloc el valor per defecte, iuseddiu en què ha quedat: per adirection, la direcció de la llengua del document (unknownConfigValue). L'alignd'una tabulació que no és cap de les seves quatre paraules es llegeix com a'start', i unapositionque 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), isuggestionindica la paraula a què més s'assembla el valor, quan n'hi ha una de propera. Elleveli elmodede la comprovació del contrast es comproven igual:usedés'AA'o'auto'.canvasViewer.pageGapicanvasViewer.rowGapes 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.outputProfileiprint.renderingIntent(usedés el que va donar el valor per defecte), i unmaxWordsomaxCharsdechecks.contentInConfigque no sigui un enter igual o més gran que 0. - Números de línia en text vertical:
lineNumbers.enabled: trueen un document compost en vertical (layout.writingMode: 'vertical-rl'). Les pàgines verticals no porten números de línia, iusedésfalse(lineNumbersUnsupported; vegeu Numeració de línies). - Text al voltant en escriptura vertical: el
defaultPlacement.wrapd'un tipus de recurs en un document compost en vertical. Les pàgines verticals no componen text al costat d'una figura, iusedésnone(wrapUnsupported; vegeu Format del document › Ajust del text). Unwrapque no indica cap costat és un valor de paràmetre desconegut. - Estil de requadre basat en un altre: un estil de requadre amb un
extendsque no correspon a cap estil decalloutStyles(calloutStyleExtendsUnknown, amb l'id més semblant asuggestion), o amb una cadena d'extendsque torna a l'estil (calloutStyleExtendsCycle, amb el buclea → b → aavalue). 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
pageTemplatesolabelStyles: 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 quelabelStylesno té (es comprova quan es passen els recursos:collectConfigWarnings(config, { resources })). El seupathé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 llistaTambé 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ó.