انتقل إلى المحتوى الرئيسي
الوصفة رقم 39

دليل الوصفات · الفصل 10 · الإخراج والدمج

ملف PDF موسوم ومتاح للجميع (PDF/UA)

دليل لإعادة التدوير يُصدَّر ملف PDF/UA-1 موسومًا فيه نص بديل وخلايا عناوين للجداول ولغة المستند ومحتويات مرتبطة، وترسم المعاينة الوسوم على الصفحة 3.

في هذه الصفحة
المُخرَج
Canvas · PDF
المستوى
متوسط
Postext
اختُبرت مع Postext 1.65.0
تتطلب ≥ 1.25.0 · postext-pdf ≥ 1.25.0
الترخيص
حُدّثت في 10 أكتوبر 2026
الشيفرة MIT · النص CC BY 4.0
  • نموذج باللغة الإسبانية: لا توجد طبعة عربية بعد
  • مقاس القص 210 × 297 مم
  • عمودان, فاصل 8 مم بين الأعمدة
  • Atkinson Hyperlegible Next 10.5/15.5
  • Atkinson Hyperlegible Mono
  • Public Sans
  • 4 صفحات
  • المستوى
  • Postext 1.65.0
  • أُخرجت في 205 ms
  • أسطر الشيفرة: 179

باختصار

دليل بلدي لإعادة التدوير في أربع صفحات. يبيّن كيف تصنع ملف PDF تتابعه قارئات الشاشة، فيه وصف للصور وجداول تستطيع قراءتها بصوت عالٍ.

ما الذي ستنضده

Reciclar en el barrio دليل لإعادة التدوير في أربع صفحات بقياس A4، صادر عن بلدية إسبانية متخيَّلة، يُقرأ على الشاشة أو يُطبع في البيت. يُظهر الغلاف الكحلي حاويات الشارع الخمس على رصيف أصفر. تضم الصفحة 2 المحتويات وثلاثة إطارات بجانب رسالة من مستشار البلدية، وتضم الصفحتان 3 و4 القسمين، في عمودين غير مضبوطين بخط Atkinson Hyperlegible Next. يصدّر المثال ملف PDF موسومًا يجتاز فحوص PDF/UA-1 في veraPDF، فيه العناوين والقوائم والإطارات والجداول بترتيب القراءة، ونص بديل للشكل، وخلايا عناوين في الجدولين كليهما. يعلن الملف عنوانه ولغته (es)، وترتبط إشاراته المرجعية وأسطر المحتويات بالصفحات. الوسوم لا تُطبع، لذلك يرسمها المثال فوق الصفحة 3 من معاينته، وهي المعروضة هنا، فتقع كل كتلة موسومة في إطار مرقّم عليه اسم وسمها. ملف PDF المنزَّل خالٍ من هذه الطبقة.

تجيب هذه الوصفة عن

  • كيف أنتج ملف PDF يسهل الوصول إليه (موسوم، PDF/UA) فيه نص بديل ولغة للمستند؟
  • كيف أحصل على تسميتي «شكل» و«جدول» بلغة مستندي؟
  • كيف أضيف جدول محتويات يحدّث نفسه (نقاط توجيه، أرقام صفحات، مؤلفون، صفوف الأجزاء)؟
  • كيف أصدّر ملف PDF حقيقيًّا في المتصفح مع تضمين الخطوط؟

الجواب المختصر

script.js · الأسطر 47–70في الشيفرة الكاملة
// 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

المكونات

الخطوط
Atkinson Hyperlegible Next, Atkinson Hyperlegible Mono, Public Sans (SIL OFL 1.1)
الأصول
لا شيء: كل صورة مرسومة بالشيفرة

طريقة التحضير

#1 · لغة المستند وعنوانه

script.js · الأسطر 126–127في الشيفرة الكاملة
  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 لغة الوسوم من locale، وهي هنا /Lang es، فيقرأ قارئ الشاشة الدليل بنطق إسباني؛ ومن دونها يعلن الملف en-US. يصير title وauthor في البيانات التمهيدية (frontmatter) للملف content.es.md عنوان ملف PDF ومؤلفه، ويطلب الملف من برامج العرض أن تُظهر ذلك العنوان في شريط النافذة بدل اسم الملف. وتمنح الخاصية locale نفسها التعليقات والاستشهادات أسماءها الإسبانية: “Figura 1.1” و“tabla 1.1”. أما الجواب المختصر فيحدّد للشكل والجدولين نصّها المتاح: يصير altText الوصف البديل للشكل (/Alt) و/Summary لكل جدول، ويُوسَم الصف الأول والعمود الأول في الجدولين خلايا عناوين.

#2 · مخطط واحد، وشريط غلاف لا يحمل إلا العنوان

script.js · الأسطر 74–104في الشيفرة الكاملة
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
  ] };

تأخذ شجرة الوسوم عناصر H1 وH2 من عناوين Markdown، وتأتي الإشارات المرجعية في ملف PDF من القائمة نفسها، فيكون الغلاف والمحتويات والرسالة والقسمان في المستوى 1، والعناوين الفرعية في المستوى 2. يَسِم postext-pdf كل عنصر نصي في تصميم العنوان على أنه جزء من ذلك العنوان، لذلك لا يتضمّن شريط الغلاف إلا العنوان، وتُنضَّد المقدمة واسم البلدية تحته فقرتين. الأشرطة الكحلية والرصيف وصف الحاويات عناصر تصميم، ويَسِم ملف PDF إطارات التصميم وصوره بأنها زخارف (artifacts)، فلا تحتاج إلى نص بديل ويتخطاها قارئ الشاشة.

#3 · محتويات مرتبطة بالصفحات

script.js · الأسطر 108–113في الشيفرة الكاملة
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 عناصر H1 وH2 مع تسميات الصفحات التي تطبعها، وفي ملف PDF يرتبط كل سطر من أسطره الأحد عشر بأعلى صفحته. وترتبط استشهادات :ref “figura 1.1” و“tabla 1.1” في الصفحة 3 و“tabla 2.1” في الصفحة 4 بالشكل والجدولين. تُنضَّد أرقام الصفحات بخط النص، Atkinson Hyperlegible Next Bold، وتأخذ الخطوط المنقّطة خط الأرقام لا خط Public Sans الذي تُنضَّد به المداخل.

#4 · ترتيب القراءة مرسومًا على الصفحة

script.js · الأسطر 299–319في الشيفرة الكاملة
// 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))];
}

يتبع قارئ الشاشة الوسوم. يَسِم renderToPdf عنوان الشريط أولًا، ثم كل عمود من أعلاه إلى أسفله، ويقرأ العنصر العائم بعد الفقرة التي تستشهد به مباشرة أينما رسمته الصفحة. تعيد هذه الدالة ذلك الترتيب لترقّم الإطارات في الصفحة 3، وتسرد شجرة البنية في ملف PDF العناصر الأربعة عشر نفسها بالترتيب نفسه. ويقع الشكل والجدولان في مجرى النص، مع placement: { position: 'here' } وسطر ::resource، ليجد القارئ المبصر أيضًا كلًّا منها تحت الجملة التي تستشهد به. وتحتفظ فقرة الزجاج الممتدة إلى العمود الثاني برقم واحد، 9، لأن ملف PDF يَسِم جزأيها فقرة واحدة.

#5 · ألوان مختارة بنسبة التباين

script.js · الأسطر 15–34في الشيفرة الكاملة
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 الألوان، لكن WCAG 2.2 يطلب نسبة 4.5:1 بين النص وخلفيته. يبلغ الحبر 15.6:1 على الأبيض، والحروف البيضاء 12.5:1 على الأشرطة الكحلية، ورمادي التذييل 7.0:1. ونسبة الأصفر 1.8:1 على الأبيض، لذلك لا يظهر إلا على الكحلي (6.9:1) وكلون تعبئة. وتتبع الرسوم الرمزية نسبة 3:1 التي يطلبها WCAG للرسوم: أبيض حيث يبلغها مقابل لون الحاوية، وبلون الحبر على الحاوية الصفراء. تكتب cell() اسم كل حاوية بجانب مربعها اللوني، وتجعل لمركز إعادة التدوير مربعًا فارغًا، فلا تعتمد أي تعليمة على التمييز بين الألوان.

الوصفة كاملة

Sandbox
// ═══ 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.

يعمل ملف script.js المجمّع كما هو: الصقه في سكربت الوحدة (module) لأي صفحة، أو افتح الوصفة على CodePen. مجلد الوصفة على GitHub ↗ (يفتح في تبويب جديد)

تنويعات

#دع الشكل يطفو

احذف الموضع فيطفو الشكل 1.1 إلى أسفل العمود الأول في الصفحة 3. ويظل ملف PDF يقرؤه بعد الفقرة التي تستشهد به، فيحتفظ في الطبقة المرسومة برقمه 3 ولا يتغير ترتيب الوسوم.

-  { id: 'contenedores', typeId: 'figure', kind: 'svg', placement: { position: 'here' },
+  { id: 'contenedores', typeId: 'figure', kind: 'svg',

أخطاء شائعة

خطأ شائع

يرث نمط العنوان فاصل الصفحة من مستواه

يأخذ مُدخل headingStyles كل حقل يتركه من مستوى عنوانه، بما فيه breakBefore. فصفحة المحتويات أو صفحة بيانات النشر المنسّقة على H1 بعد :::pagebreak ترث الزوجية 'odd' وتقع بعد صفحة فارغة. أعطِ هذا النمط breakBefore: { enabled: false }. أنماط العناوين →

خطأ شائع

ملفات Fontsource تغطي الحروف لا الرموز

تضمّن العُدّة ملف latin من Fontsource لكل خط، ومعه ملف latin-ext للحروف č وł و†، وملف greek للحروف α وχ (في عائلة تضمه: لا يضمه Lora ولا Gelasio)، حين يستعملها النص، على الشاشة وفي PDF. أما رموز مثل → و≈ و✓ و★ فليست في أي من هذه الملفات فتغيب عن PDF: ارسمها، أو اكتبها رياضيات، أو اختر خطًا تضمها ملفاته. الخطوط المضمَّنة في PDF →

لا يستطيع المثال التحقق من ملف PDF الذي يُنتجه، لأن veraPDF يعمل خارج المتصفح. نزّل الملف وشغّل verapdf -f ua1 accessible-tagged-pdf.pdf؛ النسخة الملتقطة لهذه الصفحة تجتاز الفحص. ولا يستطيع المدقّق أن يحكم هل يصف النص البديل صورته، فاستمع إلى الدليل بقارئ شاشة أيضًا.

تطبع بيانات الطبع عنوان الموقع كاملًا لأن هذا الدليل كُتب للإصدار postext 1.4.1، وفيه كان رابط Markdown يطبع كلماته ولا يضيف رابطًا إلى ملف PDF. ومنذ postext 1.10 صار الرابط [text](url) فعّالًا في ملف PDF، موسومًا عنصر Link نصّه الكلمات المرتبطة.

الحقوق

الوصفة
Ignacio Ferro
النص
نص أصلي, CC BY 4.0
الخطوط
Atkinson Hyperlegible Next (SIL OFL 1.1) · Atkinson Hyperlegible Mono (SIL OFL 1.1) · Public Sans (SIL OFL 1.1)
الشيفرة
MIT، مثل Postext
SandboxPDF