En poques paraules
Una guia de reciclatge de quatre pàgines d'un ajuntament. Ensenya a crear un PDF que els lectors de pantalla poden seguir, amb descripcions de les imatges i taules que poden llegir en veu alta.
Què compondràs
Reciclar al barri és la guia de reciclatge d'un ajuntament inventat: quatre pàgines A4 per llegir en pantalla o imprimir a casa. La coberta, blau marí, porta els cinc contenidors sobre una vorada groga. La pàgina 2 reuneix l'índex, tres requadres i la carta de la regidora; la 3 i la 4, les dues seccions, a dues columnes en bandera. El PDF etiquetat que exporta el codi supera les comprovacions PDF/UA-1 de veraPDF, amb títols, llistes, requadres i taules en ordre de lectura, text alternatiu a la figura i cel·les de capçalera a les taules. El fitxer declara títol i llengua (es), i els marcadors i les files de l'índex són enllaços. Com que les etiquetes no s'imprimeixen, el codi les dibuixa només a la previsualització de la pàgina 3, la que veus aquí, amb un requadre numerat per bloc i el nom de la seva etiqueta.
Aquesta recepta respon a
- Com genero un PDF accessible (etiquetat, PDF/UA) amb text alternatiu i llengua del document?
- Com aconsegueixo les etiquetes «Figura» i «Taula» en la llengua del meu document?
- Com afegeixo un índex que s'actualitzi sol (línies de punts, números de pàgina, autors, files de part)?
- Com exporto un PDF de debò al navegador, amb les fonts incrustades?
La resposta curta
// renderToPdf writes a tagged PDF by default: the tag tree follows the headings, paragraphs,
// lists and boxes of the Markdown. Pictures and tables carry their own accessible text here.
const table = (id, tsv, columnWidths, caption, altText) => ({ id, typeId: 'table', kind: 'table',
caption, altText, createdAt: 0, updatedAt: 0, // altText → the Table's /Summary
placement: { position: 'here' }, // set under the sentence that cites it
table: { model: { headerRowCount: 1, columnWidths, // row 0: TH cells, scope Column
rows: parseTSV(tsv).rows.map((row) => row.map(({ content }, c) => ({ content: cell(content),
...(c === 0 && { isHeader: true }) }))) } } }); // column 0: TH cells, scope Row
const resources = () => [
{ id: 'contenedores', typeId: 'figure', kind: 'svg', placement: { position: 'here' },
svg: { fileId: 'contenedores.svg', width: FIGURE[0] * PX, height: FIGURE[1] * PX },
caption: 'Una isla del barrio: de izquierda a derecha, amarillo, azul, verde, marrón y gris.',
altText: 'Cinco contenedores en fila: amarillo con una botella de plástico, azul con una caja '
+ 'de cartón, verde con una botella de vidrio, marrón con un corazón de manzana y gris con '
+ 'una bolsa de basura cerrada.', createdAt: 0, updatedAt: 0 }, // → the Figure's /Alt
table('dudas', dudas, [3, 2], 'Los residuos que más dudas dan.',
'Once residuos y el contenedor de cada uno.'),
table('horarios', horarios, [2.2, 4, 1.4], 'Días y horas de recogida.',
'Qué días y desde qué hora se vacía cada contenedor.'),
{ id: 'calle', typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0, // the cover's row:
svg: { fileId: 'calle.svg', width: STREET[0] * PX, height: STREET[1] * PX } }, // an artifact
];
const exportPdf = (doc) => renderToPdf(doc, { fontProvider: fontsourceProvider,
resourceBytes: imageBytes }); // accessible and outlines default to true
Ingredients
- Funcions
- PDF accessible etiquetatÍndex generalExportació a PDFMarcadors del PDFFigura i Taula en la teva llenguaTaules a partir de dadesFigures just aquíMostres de colorCites que col·loquen les figuresMetadades del documentEstils de títolCapítols sense númeroObertures dissenyadesBanda de capítol d'amplada completaCobertes, portades i colofonsImatges als dissenys de pàginaRequadresFonts abans de compondrePàgines en un canvas
- També fa servir
- Atributs de títolTítols numeratsSortir de la retícula a propòsitSalts de pàgina i de columnaEstils de paràgrafFonts incrustades al PDFFigures i taules com a recursosGeometria per seccióCapçaleres per seccióSalts de línia als títols
- Tipografia
- Atkinson Hyperlegible Next, Atkinson Hyperlegible Mono, Public Sans (SIL OFL 1.1)
- Recursos
- Cap: totes les imatges es dibuixen en codi
Elaboració
#1 · La llengua i el títol del document
locale: LANG, // → /Lang es, and "Figura", "Tabla" in the captions and the citations
// /Title and /Author come from the frontmatter's title and author
postext-pdf escriu la llengua de les etiquetes a partir de locale, aquí /Lang es, perquè un lector de pantalla llegeixi la guia amb pronunciació espanyola; si falta, el fitxer declara en-US. El title i l'author del frontmatter de content.es.md donen el títol i l'autor del PDF, i el fitxer demana als visors que mostrin aquest títol a la barra de la finestra en lloc del nom del fitxer. El mateix locale dona als peus i a les cites els noms en espanyol: «Figura 1.1», «tabla 1.1». El text accessible de la figura i de les taules és a la resposta curta: l'altText dona la descripció alternativa de la figura (/Alt) i el resum de cada taula (/Summary), i la primera fila i la primera columna de les dues taules s'etiqueten com a cel·les de capçalera.
#2 · Un sol esquema, i una banda de coberta amb el títol i res més
const [BAND, COVER] = [54, 176]; // mm from the trim top to the foot of each band
const band = (height) => ({ kind: 'box', id: 'band', style: { backgroundColor: col('navy') },
placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(height) } } });
const display = (size, hue) => face('Public Sans', 800, size, { lineHeight: 1, color: col(hue) });
const section = { enabled: true, slot: { elements: [band(BAND),
text('number', '{number}', display(64, 'signal'), at('container', 'top-left', 0, 4)),
text('title', '{titleText}', display(28, 'paper'),
{ ...at('#number', 'right-of', 6, 3.5), size: { width: mm(130) } })] } };
// A heading design's text is tagged as the heading, so the cover's band holds only the title.
const cover = { enabled: true, minHeight: mm(COVER - TOP + 24), slot: { elements: [band(COVER),
{ kind: 'box', id: 'kerb', style: { backgroundColor: col('signal') },
placement: { ...at('bleed', 'top-left', 0, COVER), size: { width: 'fill', height: mm(3) } } },
{ kind: 'image', id: 'bins', resourceId: 'calle', // the wheels stand on the kerb
placement: { ...at('#kerb', 'align-bottom', SIDE), size: { width: mm(STREET[0]) } } },
text('title', '{titleText}', display(66, 'paper'),
{ ...at('container', 'top-left', 0, 26), size: { width: mm(STREET[0]) } })] } };
const plain = (id, more) => ({ id, numbered: false, span: 'column', ...more,
advancedDesign: { enabled: false }, fontSize: pt(26), lineHeight: pt(2 * LEAD) });
const headingStyles = [
{ id: 'portada', numbered: false, toc: false, span: 'page', advancedDesign: cover,
layout: { layoutType: 'single' }, footer: { elements: [] } },
plain('indice', { toc: false }), // the contents leave their own heading out
plain('presentacion', { breakBefore: { enabled: false } }), // gotcha: style-inherits-break
];
const headings = { fontFamily: 'Public Sans', fontWeight: 800, color: col('ink'),
levels: [ // parity 'any': a section opens the next page, whichever side it falls on
{ level: 1, numberingTemplate: '{1}', breakBefore: { enabled: true, parity: 'any' },
span: 'page', advancedDesign: section, marginBottom: pt(LEAD) }, // 9.7 mm under the band
{ level: 2, fontWeight: 700, fontSize: pt(13.5), lineHeight: pt(LEAD), marginTop: pt(0),
marginBottom: pt(0) }, // the line above an H2 is the paragraph's, or the resource's, gap
] };
L'arbre d'etiquetes pren els elements H1 i H2 dels títols del Markdown, i els marcadors del PDF surten de la mateixa llista, de manera que la coberta, l'índex, la carta i les dues seccions són de nivell 1, i els intertítols, de nivell 2. postext-pdf etiqueta cada text del disseny d'un títol dins d'aquest títol. Per això la banda de la coberta porta només el títol, i l'entradeta i el nom de l'ajuntament van a sota, com a paràgrafs. Les bandes blau marí, la vorada i la fila de contenidors són elements de disseny, i el PDF marca les caixes i les imatges de disseny com a artefactes, així que no necessiten text alternatiu i el lector de pantalla se les salta.
#3 · Un índex amb enllaços
const [NUMBER, GAP] = [6, 2.5]; // mm: the number column and the gap before a title
const toc = { levels: [{ level: 1, ...face('Public Sans', 700, 12), numberWidth: mm(NUMBER),
numberGap: mm(GAP), marginTop: pt(LEAD / 2) }, { level: 2, indent: mm(NUMBER + GAP) }],
unnumbered: { indent: mm(NUMBER + GAP) }, leader: { gap: mm(1.5) }, // Presentación: no number
// The page numbers, and the leaders with them, in the text face
pageNumber: { fontFamily: 'Atkinson Hyperlegible Next', fontWeight: 700, width: mm(8) } };
:::toc recull els H1 i els H2 amb el número de pàgina que imprimeixen, i al PDF cadascuna de les seves onze files enllaça amb el començament de la seva pàgina. Les cites :ref de la pàgina 3, «figura 1.1» i «tabla 1.1», i la de la pàgina 4, «tabla 2.1», porten a la figura i a les taules. Els números de pàgina van en la lletra del text, Atkinson Hyperlegible Next Bold, i les línies de punts prenen la lletra dels números, no la Public Sans de les entrades.
#4 · L'ordre de lectura, dibuixat a la pàgina
// An opener band's title, then each column from top to bottom; a float is read after the text
// that cites it, wherever it is painted. A paragraph continued in the next column stays one
// element, so its second part keeps its number.
const tagOf = (b) => ({ heading: `H${b.headingLevel ?? 1}`, callout: 'Div', listItem: 'LI',
resource: b.resourceBlock?.kind === 'table' ? 'Table' : 'Figure' })[b.type] ?? 'P';
function readingOrder(page) {
const ids = new Map(); // element → its number
const add = (block, box) => {
const key = block.id.replace(/-cont-\d+$/, ''); // fragments share their block's id
if (!ids.has(key)) ids.set(key, ids.size + 1);
return { n: ids.get(key), tag: tagOf(block), box, cont: key !== block.id };
};
const blocks = page.columns.flatMap((c) => c.blocks);
const title = blocks.find((b) => b.hidden && b.type === 'heading'); // drawn by the band
const flow = blocks.filter((b) => !b.hidden);
for (const float of page.floats ?? []) { // after the last block up to its place in the source
flow.splice(flow.findLastIndex((b) => b.contentIndex <= float.contentIndex) + 1, 0, float);
}
return [...(page.openerBand && title ? [add(title, union(page.openerBand.blocks
.filter((b) => b.kind === 'text')))] : []), ...flow.map((b) => add(b, b.bbox))];
}
Un lector de pantalla segueix les etiquetes. renderToPdf etiqueta primer el títol de la banda i després cada columna de dalt a baix, i llegeix un flotant just després del paràgraf que el cita, es pinti on es pinti. Aquesta funció repeteix aquest ordre per numerar els requadres de la pàgina 3, i l'arbre d'estructura del PDF dona els mateixos catorze elements en el mateix ordre. La figura i les dues taules van al flux, amb placement: { position: 'here' } i una línia ::resource, perquè qui llegeix amb la vista també les trobi sota la frase que les cita. El paràgraf del vidre que continua a la segona columna conserva un sol número, el 9, perquè el PDF etiqueta les dues parts com un únic paràgraf.
#5 · Colors triats pel seu contrast
const palette = {
ink: '#14243a', // text: 15.6:1 on white
navy: '#173556', // bands: white type on it 12.5:1
signal: '#f2b705', // yellow: only on navy (6.9:1) or as a fill, never as text on white
tint: '#e8eef5', // header cells and boxes: ink on it 13.4:1
rule: '#aebccb', // table rules
muted: '#4a5a6e', // footer and colophon: 7.0:1 on white
paper: '#ffffff',
};
// every colour is linked to its palette entry by id
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// 'main-color' is the id the engine's default styles link to: any default left in them is navy
const colorPalette = [...Object.entries(palette), ['main-color', palette.navy]]
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const BIN = { amarillo: '#f2b705', azul: '#1f6fc5', verde: '#2e8b4a', marron: '#8a5a2f',
gris: '#6b7480' }; // the street bins' colours, for the pictograms and the swatches
const NAME = { amarillo: 'Amarillo', azul: 'Azul', verde: 'Verde', marron: 'Marrón', gris: 'Gris',
punto: 'Punto limpio' }; // a table cell never shows a colour alone: its name goes beside it
const cell = (text) => (text in NAME // an unknown colour ('none') draws an empty square
? `:swatch{color="${BIN[text] ?? 'none'}"} ${NAME[text]}` : text);
PDF/UA-1 no comprova el color, però WCAG 2.2 demana 4,5:1 entre el text i el seu fons. La tinta dona 15,6:1 sobre blanc; la lletra blanca, 12,5:1 sobre les bandes blau marí, i el gris del peu de pàgina, 7,0:1. El groc dona 1,8:1 sobre blanc, així que només apareix sobre blau marí (6,9:1) i com a fons. Els pictogrames segueixen el 3:1 que WCAG demana als gràfics: blanc quan arriba a aquesta proporció sobre el seu contenidor i tinta sobre el groc. cell() escriu el nom de cada contenidor al costat de la seva mostra de color, i dona a la deixalleria un quadrat buit, de manera que cap indicació no depèn de distingir colors.
La recepta completa
// ═══ Postext Cookbook · Nº 039 · Accessible tagged PDF (PDF/UA) ═════════════════════
// https://postext.dev/en/cookbook/accessible-tagged-pdf
// Code: MIT · Text: original (CC BY 4.0) · Pictograms: generated in code (CC BY 4.0)
// Fonts: Atkinson Hyperlegible Next and Mono, Public Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, parseTSV,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
const LANG = 'es'; // @lang: the language of the sample document (this recipe is Spanish only)
const RECIPE = 'accessible-tagged-pdf';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: text colours chosen for their contrast, and never a colour without its name
const palette = {
ink: '#14243a', // text: 15.6:1 on white
navy: '#173556', // bands: white type on it 12.5:1
signal: '#f2b705', // yellow: only on navy (6.9:1) or as a fill, never as text on white
tint: '#e8eef5', // header cells and boxes: ink on it 13.4:1
rule: '#aebccb', // table rules
muted: '#4a5a6e', // footer and colophon: 7.0:1 on white
paper: '#ffffff',
};
// every colour is linked to its palette entry by id
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// 'main-color' is the id the engine's default styles link to: any default left in them is navy
const colorPalette = [...Object.entries(palette), ['main-color', palette.navy]]
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const BIN = { amarillo: '#f2b705', azul: '#1f6fc5', verde: '#2e8b4a', marron: '#8a5a2f',
gris: '#6b7480' }; // the street bins' colours, for the pictograms and the swatches
const NAME = { amarillo: 'Amarillo', azul: 'Azul', verde: 'Verde', marron: 'Marrón', gris: 'Gris',
punto: 'Punto limpio' }; // a table cell never shows a colour alone: its name goes beside it
const cell = (text) => (text in NAME // an unknown colour ('none') draws an empty square
? `:swatch{color="${BIN[text] ?? 'none'}"} ${NAME[text]}` : text);
// #endregion
const TRIM = [210, 297]; // A4, the size residents print at home
const [TOP, FOOT, SIDE, LEAD] = [20, 22, 18, 15.5]; // margins in mm, not mirrored; leading in pt
const [PX, FIGURE, STREET] = [12, [83, 30], [174, 44]]; // drawings: px per mm, sizes in mm
const face = (fontFamily, fontWeight, size, more) => ({ fontFamily, fontWeight, fontSize: pt(size),
...more });
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const text = (id, content, style, placement) => ({ kind: 'text', id, content, align: 'left',
...style, placement }); // a heading's design wraps its text; the footer clips its own
// #region answer: the alt text and header cells the tags take from the resources
// renderToPdf writes a tagged PDF by default: the tag tree follows the headings, paragraphs,
// lists and boxes of the Markdown. Pictures and tables carry their own accessible text here.
L'script.js compost funciona tal com és: enganxa'l com a script de mòdul en qualsevol pàgina o obre la recepta a CodePen. Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)
Variants
#Deixa flotar la figura
Treu la col·locació i la figura 1.1 flota al peu de la primera columna de la pàgina 3. El PDF la continua llegint després del paràgraf que la cita, de manera que el dibuix li manté el número 3 i l'ordre de les etiquetes no canvia.
- { id: 'contenedores', typeId: 'figure', kind: 'svg', placement: { position: 'here' },
+ { id: 'contenedores', typeId: 'figure', kind: 'svg',Errors freqüents
Error freqüent
Un estil de títol hereta el salt de pàgina del seu nivell
Una entrada de headingStyles pren del seu nivell de títol tot allò que no fixa, també breakBefore. Un índex o un colofó amb estil sobre un H1 després d'un :::pagebreak hereta la paritat 'odd' i cau darrere d'una pàgina en blanc. Dona a aquest estil breakBefore: { enabled: false }. Estils de títol →
Error freqüent
Els fitxers de Fontsource cobreixen lletres, no símbols
El kit incrusta el fitxer latin de Fontsource de cada font i, quan el text els fa servir, el seu fitxer latin-ext per a č, ł, † i el seu fitxer greek per a α, χ (en una família que en tingui: Lora i Gelasio no), a la pantalla i al PDF. Símbols com →, ≈, ✓ i ★ no són a cap d'aquests fitxers i falten al PDF: dibuixa'ls, escriu-los com a matemàtiques o tria una font els fitxers de la qual els tinguin. Fonts incrustades al PDF →
El codi no pot validar el seu propi PDF, perquè veraPDF funciona fora del navegador. Baixa el fitxer i executa verapdf -f ua1 accessible-tagged-pdf.pdf; el PDF capturat per a aquesta pàgina passa la validació. El validador no sap si un text alternatiu descriu la seva imatge, així que escolta també la guia amb un lector de pantalla.
El colofó imprimeix l'adreça web completa perquè la guia es va escriure per a postext 1.4.1, en què un enllaç de Markdown imprimia les seves paraules sense afegir cap enllaç al PDF. Des de postext 1.10 un enllaç [texto](url) funciona al PDF i s'etiqueta com a element Link, amb les paraules enllaçades com a text.
Crèdits
- Recepta
- Ignacio Ferro
- Text
- Text original, CC BY 4.0
- Fonts
- Atkinson Hyperlegible Next (SIL OFL 1.1) · Atkinson Hyperlegible Mono (SIL OFL 1.1) · Public Sans (SIL OFL 1.1)
- Codi
- MIT, com Postext
Editar aquest text ↗ (s'obre en una pestanya nova)Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)


