الفصل 3.17 · الجزء II · الحرفة
الإعدادات: الاستخدام البرمجي
استعمال Postext من الشيفرة: buildDocument وتحذيراته، والقيم الافتراضية، والخطوط، والذاكرات المؤقتة، وWeb Worker
باختصار
هذه الصفحة لمن يكتبون الشيفرة. تبيّن كيف تُخرج كتابًا باستدعاء دالة واحدة، وكيف تقرأ التحذيرات التي تعيدها. وتبيّن كيف تستكمل الإعدادات الافتراضية، وتحمّل الخطوط قبل بدء العمل، وتحفظ القياسات لوقت لاحق. وتشرح كيف تشغّل العمل في الخلفية، لتبقى الصفحة سريعة. ولملف PDF وعرض الويب والكتاب ثلاثي الأبعاد والكتاب الإلكتروني بصيغة EPUB وملفات الكتب صفحات خاصة بها.
#الاستخدام البرمجي
المسار الموصى به: استخدم عامل الويب (Web Worker). في المتصفح، شغّل الإخراج عبر
createLayoutWorker()منpostext/workerبدل استدعاءbuildDocumentفي الخيط الرئيسي. يُبقي العامل الصفحة مستجيبة أثناء الإخراج، ويحتفظ بقياسات النص بين إعادة إخراج وأخرى، ويلغي الإخراج الجاري حين يبدأ إخراج أحدث، فلا تنتظر ضغطة مفتاح إخراج نص أقدم. الطريقة في تشغيل الإخراج في Web Worker. وبقية هذا القسم (buildDocumentمباشرةً، والمحلِّلات، ودوال التجريد، والذاكرات المؤقتة) تبقى صالحة: يأخذ العامل المدخلات نفسها ويعيد المخرجات نفسها. لا تستدعِbuildDocumentفي الخيط الرئيسي إلا للتصدير لمرة واحدة، أو للعرض على الخادم (Node)، أو للاختبارات.
#التثبيت
المكتبات منشورة على npm وعلى JSR، بالشيفرة نفسها وأرقام الإصدارات نفسها في الاثنين.
| المكتبة | npm | JSR |
|---|---|---|
| المحرّك | postext | @postext/postext |
postext-pdf | @postext/pdf | |
| EPUB 3 | postext-epub | @postext/epub |
| عارض الكتاب ثلاثي الأبعاد | postext-folio (مع three) | @postext/folio |
| الاستشهادات | postext-citeproc | @postext/citeproc |
| SCORM | postext-scorm | @postext/scorm |
# من npm
npm install postext
# من JSR
deno add jsr:@postext/postext # Deno
pnpm add jsr:@postext/postext # pnpm 10.9 أو أحدث
npx jsr add @postext/postext # npm
bunx jsr add @postext/postext # Bunعند التثبيت من JSR تكون أسماء الاستيراد هي أسماء JSR: import { buildDocument } from '@postext/postext'، ويصير postext/worker هو @postext/postext/worker. تستخدم الأمثلة في هذا التوثيق أسماء npm. ملفات تعريف ICC (postext/icc/*) موجودة على npm وحده.
- الاستشهادات مع npm وBun. يثبّت
npx jsr addوbunx jsr addالحزمة@postext/postextاسمًا بديلًا لـ@jsr/postext__postext، التي تعتمد عليها@postext/citeprocأيضًا، فيصير الاسمان نسختين من المحرّك. يسجّل@postext/citeproc/registerمحرّك الاستشهادات في النسخة التي تستخدمها citeproc، فيبقى المستند المبني بالنسخة الأخرى باستشهادات غير منسّقة. استورد المحرّك عندئذٍ باسم@jsr/postext__postext. أما Deno وpnpm فيثبّتان نسخة واحدة ولا يحتاجان إلى شيء. - خارج المتصفح. يقيس المحرّك النص على
OffscreenCanvas. ولا يملكه Node وBun وDeno، فأعطها واحدًا قبل أول بناء، من@napi-rs/canvasمثلًا، وسجّل الخطوط التي يُصفّ بها نص الكتاب:
import { createCanvas, DOMMatrix, GlobalFonts, ImageData, Path2D } from '@napi-rs/canvas';
GlobalFonts.registerFromPath('fonts/EBGaramond-Regular.ttf', 'EB Garamond');
globalThis.OffscreenCanvas = class {
constructor(width, height) {
return createCanvas(Math.max(1, Math.ceil(width)), Math.max(1, Math.ceil(height)));
}
};
globalThis.Path2D ??= Path2D;
globalThis.DOMMatrix ??= DOMMatrix;
globalThis.ImageData ??= ImageData;يمكن استيراد postext-folio في Node، لكن عارض الكتاب ثلاثي الأبعاد نفسه يحتاج إلى متصفح.
#بناء مستند
تُشغّل الدالة buildDocument خطّ معالجة الإخراج كاملًا وتُعيد شجرة المستند الافتراضية (Virtual Document Tree، VDT) بإحداثيات دقيقة لكل عنصر. هذه هي نقطة الدخول الأدنى مستوى؛ وعلى شيفرة واجهة المستخدم أن تُفضّل غلاف Web Worker، الذي يستدعي buildDocument داخل خيط عامل مخصّص بالمعاملات نفسها.
import { buildDocument } from 'postext';
const content = {
markdown: '# Chapter One\n\nThe story begins here...',
};
const config = {
page: { sizePreset: '17x24' },
layout: { layoutType: 'double' },
bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt overrides the 8 pt default
};
// Build the layout — produces a VDT with one entry per page in `vdt.pages`
const vdt = buildDocument(content, config);
console.log(`Document has ${vdt.pages.length} pages`);#التحذيرات في المستند
لا تتوقف buildDocument عند مرجع خاطئ أو نمط مجهول: بل تضع قيمة بديلة وتسجّل ما فعلته في doc.contentWarnings. أما الإطارات التي اضطر الإخراج إلى وضعها رغم أنها لا تتسع فتجدها في doc.warnings، التي تحتفظ بالشكل الذي كان لها في postext 1.4: كل مدخل فيها من نوع calloutOverflow ومعه pageIndex وcolumnIndex وoverflowPx. يغيب كل حقل حين لا يكون هناك ما يُسجَّل فيه. لكل مدخل kind. وتتضمّن تحذيرات المحتوى نطاق المصدر للبنية المعنية، أي sourceStart / sourceEnd، وهما إزاحتان داخل نص Markdown الذي مرّرته، بما في ذلك البيانات التمهيدية (frontmatter)، ومعهما pageIndex إن وقعت البنية في صفحة.
| النوع | متى يُطلَق | ما الذي يفعله الإخراج |
|---|---|---|
calloutOverflow | إطار :::callout لا يتسع له أي عمود ولا يمكن لأي قطع أن يقسمه. وكذلك إطار span: 'side' أطول من عمود جانبي فارغ (منذ postext 1.25). | يُوضع على أي حال، فيتجاوز عموده بمقدار overflowPx (في pageIndex / columnIndex). وهو النوع الوحيد المُدرج في doc.warnings؛ أما الأنواع التالية فتقع في doc.contentWarnings. |
invalidFrontmatter | البيانات التمهيدية ليست YAML صالحة (علامة اقتباس لم تُغلق، نص بعد قيمة بين علامتي اقتباس). message هو سبب المحلّل مع السطر والعمود. | يُنضَّد المستند دون بياناته الوصفية؛ ويُنضَّد المتن الذي يلي سطر --- الختامي كالمعتاد. |
unknownResourceId | تضمين ::resource (usage: 'embed') أو :ref داخل السطر ('ref') أو صورة في خلية جدول ('cellImage') يذكر معرّفًا ليس لأي مورد. | يُحذف التضمين، ويطبع المرجع ? (أو تسميته في text=) بلا رقم ولا رابط، وتبقى الخلية نصًا فقط. يذكر inResource المورد الذي يحوي تعليقُه أو ملاحظته أو خليته ذلك المرجع. |
unknownDirective | سطر :::name ليس اسمه توجيهًا ولا حاوية. | يُنضَّد السطر نصًا. |
malformedEmbed | سطر ::name ليس تضمينًا سليم البنية قائمًا وحده: ::resource بمعرّف غير محاط بعلامات تنصيص أو محاط بعلامات تنصيص مفردة أو بسمة أخرى، أو سطر ملتصق تحت فقرة دون سطر فارغ. | يُنضَّد السطر نصًا. |
fullwidthMarkup | سطر يحوي ترميزًا كُتب بطريقة إدخال صينية أو يابانية: سطر حاوية :::، أو عنوان #، أو علامة حاشية [^…]، أو سمات {…} بعد سطر حاوية أو عنوان، أو نص عريض **…**. في typed الترميز كما كُتب، وفي ascii الشكل الذي ينبغي كتابته. تحذير واحد لكل سطر. | يُنضَّد السطر نصًا؛ ولا يُحوَّل شيء. |
attributeKeyInvalid | مفتاح سمة يحوي حروفًا من خارج ASCII (作者=曹雪芹)؛ ويشير التحذير إلى المفتاح. | تُتجاهَل السمة. |
unknownParagraphStyle | :::paragraphs{style} يذكر نمط فقرة غير موجود. | تُنضَّد الفقرات بنمط نص المتن. |
unknownCalloutType | :::callout{type} لا يذكر أيًا من calloutStyles، ولا يُطلَق إلا بعد ضبط بعضها. | يأخذ الإطار أول نمط إطار. |
columnsFlowUnknown | :::columns{flow} ليست snake ولا parallel؛ وvalue هي القيمة المكتوبة. | تأخذ المجموعة القيمة الافتراضية: parallel مع breaks، وsnake من دونها. |
templateUnknown | صفحة مركّبة (::::page{template}) لا تذكر أي مدخل من pageTemplates، أو لا تذكر قالبًا أصلًا؛ وtemplate هو المعرّف كما كُتب، وfenceIndex موضع الصفحة بين الصفحات المركّبة في الفصل. | لا تُفحص خاناتها. وإلى أن تُضبط القوالب، يُنضَّد محتواها في النص الجاري على صفحات خاصة به. |
slotUnknown | محتوى في صفحة مركّبة يذكر خانة slot ليست إطارًا من قالب الصفحة (slot وtemplate وfenceIndex؛ وframe إطار التدفق الذي يأخذه). | يذهب المحتوى إلى إطار التدفق في القالب. |
slotEmpty | إطار من القالب لا يتلقى شيئًا في الصفحة (frame وtemplate وfenceIndex). ولا يُطلَق لإطار optional، ولا لإطار لا يتلقى إلا ما يُكمله فيه إطار آخر. | يبقى الإطار فارغًا. ويسرده postext check ملاحظةً. |
pageFenceLength | :::page بثلاث علامات : وفيها template=. | تُقرأ صفحة قصة مصوّرة؛ والصفحة المركّبة تحتاج إلى أربع علامات :. |
frameOverflow | محتوى إطار في صفحة مركّبة لا يتّسع له الإطار بعد خطوات الملاءمة، ولم يبقَ للإطار next يُكمل فيه (template وframe وfenceIndex وlocale؛ وoverflowMm الارتفاع المقصوص؛ وconfigPath مؤشر JSON إلى إطار القالب، مثل /pageTemplates/0/frames/2؛ وstepsTried؛ وscale وimageScale، المقياس الذي انتهى إليه نصه وصوره؛ وproposals، وكل منها { kind, path, value }). يصدر عن التنضيد، ومعه pageIndex الصفحة. | تقصّ المخرجات المقسّمة إلى صفحات ما لا يتّسع عند أسفل الإطار، لكنه يبقى في المستند وفي خريطة المصدر وفي EPUB القابل لإعادة التدفق. |
frameContinuationLimit | استمر محتوى إطار في صفحات تُضاف بعد صفحته المركّبة (overflow. أو 'template:<id>') بقدر ما يجوز للصفحة المركّبة أن تضيف من الصفحات، أي 16، ولا يزال لا يتّسع (template وframe لآخر صفحة مضافة، وfenceIndex وpages وoverflowMm وconfigPath). يصدر عن التنضيد، ومعه pageIndex آخر صفحة مضافة. | تقصّ المخرجات المقسّمة إلى صفحات الباقي عند أسفل ذلك الإطار، لكنه يبقى في المستند وفي خريطة المصدر وفي EPUB القابل لإعادة التدفق. |
continueTargetMissing | قيمة overflow. في إطار لا تشير إلى كتلة صفحة تأتي بعد الكتلة التي فيها مقاله (template وframe وfenceIndex وtarget، وbefore حين تأتي تلك الكتلة قبلها، وconfigPath). يصدر عن التنضيد، ومعه pageIndex الصفحة المُرسِلة. | يستمر الباقي في صفحة تُضاف بعد الصفحة المُرسِلة، كما في 'next-page'. |
spreadMismatch | سطر فتح صفحة مركّبة وقالبها مختلفان في أمر الصفحتين المتقابلتين (template وfenceIndex؛ وfence هي spread في سطر الفتح؛ وtemplateSpread ما في القالب). | الحكم للقالب: قالب الصفحتين يُنضَّد على صفحتين متقابلتين، وغيره على صفحة واحدة. |
labelAnchorUnknown | تذكر ::label في :::figure عبر at مرساةً لا يملكها مورد شكلها (resourceId وanchor وknown أي مراسي المورد وlocale). | لا تُرسم التسمية؛ ويظل EPUB القابل لإعادة التدفق يتضمّنها. |
anchorUnlabelled | مرساة في مورد الشكل تذكر نمط تسمية، ولا توجد عندها أي ::label للشكل في هذه اللغة (resourceId وanchor وstyle وlocale). وهي ملاحظة. | لا يُرسم شيء عند المرساة. |
labelOverflow | تسمية شكل ما زالت أعرض من width مرساتها حتى عند أصغر مقياس يسمح به نمط تسميتها (resourceId وtext وanchor وwidthPct وscale وlocale). | تُرسم التسمية بذلك المقياس وتتجاوز عرضها المحدّد. |
labelOverlap | يتلامس سطرا تسميتين في شكل واحد (resourceId وtext وanchor وwith وwithAnchor وwithSymbol وcount وlocale). ويذكر التحذير التسمية اللاحقة بترتيب الكتابة. | تُرسم التسميتان حيث هما. |
figureWordsShared | يعطي :::figure موردًا كلمات (alt أو caption أو note) سبق أن أعطاه شكلٌ سابق في الفصل كلماته، وهي مختلفة (resourceId وwords). | تعرض الصفحات كلمات الشكل الأول وتُسقط كلمات الشكل اللاحق. |
frameCovered | حبر إطار من إطارات صفحة مركّبة يقع تحت إطار آخر مرسوم فوقه (template وframe وcoveredBy وcoveredByPath وfenceIndex وconfigPath وoverlapMm2 وtext أو picture وlocale؛ proposals: layer وexclude وmove). يصدره التنضيد، مع pageIndex للصفحة. منذ postext 1.48. | يُرسم الإطاران كما يقول القالب، ويبقى الحبر المغطّى مختفيًا. |
frameOutsideArea | إطار من إطارات صفحة مركّبة يتجاوز خط القص (نصه)، أو النزف (خلفيته أو صوره)، أو الإطار أو المجموعة المثبَّت داخلها (template وframe وfenceIndex وconfigPath وpast وtarget وexcessMm وsides وlocale؛ proposals: maxHeight وminHeight وcontinueNextPage وmove). يصدره التنضيد. منذ postext 1.48. | يُرسم الإطار في موضعه، ويُقصّ ما يتجاوز خط القص. |
folioMissing | صفحة مركّبة لا ترسم شيئًا من رقم صفحة أو ترويسة جارية (template, elementId, slot: 'header', 'footer' or 'decoration', folio, side, drawnOn, siblings) ترسمه drawnOn من صفحات قالبها وجهتها الأخرى البالغة siblings: نص في header أو footer، أو نص في الزخرفة يقرأ {pageNumber} أو اسمًا جاريًا أو {attr.x}. لا تُحسب صفحة تطفئ كتلتُها العنصر (when / unless)، ولا صفحة ليس في خانتها هذا العنصر؛ ويلزم صفحتان ترسمانه. يصدر عن التنضيد مع pageIndex، ويشير إلى كتلة الصفحة. منذ postext 1.53. | تُطبع الصفحة بدونه. اضبط في تلك الكتلة السمة التي يقرؤها العنصر، أو أطفئه هناك عمدًا بـ when أو unless. |
repeatOverflow | شبكة متكرّرة في صفحة مركّبة تتّسع لـmax من العناصر، والصفحة تعطيها أكثر (template وgroup وframe وitem وmax وflowFrame وfenceIndex). تحذير لكل عنصر زائد. منذ postext 1.48. | ينتقل العنصر إلى إطار التدفق، أو إلى ما بعد الصفحة. |
moduleUnknown | كتلة :::module لا تنضّدها الصفحة (template وmodule وname وfenceIndex؛ reason: 'unknown' و'notModule' و'noGroup'). منذ postext 1.48. | ينتقل محتواها إلى إطار التدفق. |
moduleAsPage | كتلة صفحة تذكر قالب وحدة (template وfenceIndex). منذ postext 1.48. | يُنضَّد محتوى الكتلة في التدفق. |
moduleNested | كتلة :::module داخل وحدة أخرى (template وmodule وfenceIndex). منذ postext 1.48. | تصير كتلها كتلًا للوحدة الخارجية. |
moduleNameRejected | اسم الوحدة name مأخوذ في الصفحة، أو فيه مسافة أو . أو # أو [ أو ] (template وmodule وname وused وreason: 'taken' و'invalid'، وfenceIndex). منذ postext 1.48. | تأخذ الوحدة الاسم used، وتُخاطَب خاناتها تحت ذلك الاسم. |
unknownChipStyle | :chip[…]{style} يذكر نمط شارة غير موجود. | تأخذ الشارة أول نمط شارة. |
unknownMarkStyle | لا يذكر :mark[…]{style} أي نمط تظليل. | تأخذ العلامة نمط التظليل الأول. |
undefinedFootnote | علامة حاشية [^id] لا تعرّفها أي فقرة [^id]: (id هو معرّف الحاشية). | يُطبع الرقم؛ وتبقى الحاشية فارغة. |
unusedFootnote | تعريف حاشية [^id]: لا تستشهد به أي علامة. | لا تُنضَّد الحاشية. |
indexMarkInvalid | علامة فهرسة بلا مصطلح: :index{}، أو سمات بلا term على علامة ليس لها نص بين قوسين معقوفين. | لا تُفهرس العلامة شيئًا. |
indexSeeUnknown | هدف see أو seealso (target) ليس مدخلًا في فهرسه (index، و'' للفهرس الرئيسي). يشير إلى سطر :::index. | تُطبع الإحالة على أي حال. |
indexRangeUnclosed | علامة range="start" بلا range="end" مقابلة، أو العكس (يبيّن missing أي الطرفين مفقود؛ ويذكر term المدخل). يشير إلى سطر :::index. | يطبع النطاق صفحته الوحيدة. |
unknownHeadingStyle | عنوان يذكر في {style="…"} نمط عنوان غير موجود (level هو مستوى العنوان). | يحتفظ العنوان وقسمه بإعدادات المستوى نفسه. |
unknownTableStyle | مورد جدول يذكر في table.styleId اسمًا ليس مدخلًا في tableStyles. | يُنضَّد الجدول بـtableStyle. |
raggedTableGrid | شبكة جدول ليست مستطيلة بعد احتساب دمج خلاياها (انظر بناء نماذج الجداول). | تنزاح الخلايا فوق خلية مدموجة أو تترك فراغًا. يحدّد reason ('spanOverlap' / 'missingCells') وrow وcol موضع المشكلة الأولى؛ ويبيّن count عدد المشكلات. |
lineNumberOverlap | مع lineNumbers.، يتراكب رقم سطر مع إطار أو تعليق أو شكل في العمود الجانبي. يشير إلى السطر المرقَّم؛ وnumber هو الرقم كما يُطبع. | يُرسم الرقم مع ذلك، ولا يتحرك أيٌّ منهما. |
dropCap | فقرة يفتتحها حرف استهلالي ولا تستطيع أخذه كما ضُبط. reason: 'shortParagraph' (أسطرها أقل مما ينزله الحرف الاستهلالي؛ وhandling هو ما فعله shortParagraph، وlines عدد الأسطر التي يمتد عليها الحرف المصغَّر)، أو 'split' (تنقطع قبل آخر سطر يجاور الحرف الاستهلالي، وهي وحدها في عمود أقصر من أن يسعه)، أو 'joiningScript' (حرفها الأول يتصل بما بعده)، أو 'verticalText'، أو 'noLetter' (تُفتتح بإحالة أو صيغة أو علامة حاشية). وtext هو سطرها الأول. 'inBox': تطلب مجموعة :::paragraphs أو نمط فقرة حرفًا استهلاليًا داخل إطار :::callout، ولا يُنضَّد فيه أي حرف استهلالي. | يُحفظ المكان، أو يُصغَّر الحرف الاستهلالي، أو يُترك، كما يقول التحذير. |
codeOverflow | في قائمة شيفرة أسطر أعرض من إطارها. mode هو ما فعله codeStyle.overflow ('wrap' أو 'shrink' أو 'clip')، وlines عدد أسطر المصدر التي زاد عرضها، وscale الحجم الذي نُضّدت به القائمة المصغَّرة (نسبةً من fontSize)، وlang لغة كتلة الشيفرة. يشير إلى القائمة. | تُقسَّم الأسطر، أو تُنضَّد أصغر، أو تُقطع، كما يقول mode. |
floatShrunk | نُضِّدت صورة عائمة أصغر من حجمها لتتسع في حيّز موضعها (placement.shrink). resourceId يحدّدها، وscale نسبة عرضها التي تحتفظ بها، وoverflowPx، إن وُجد، مقدار ما لا تزال تتجاوز به أسفل مساحة النص بأصغر مقياس لها (placement.minScale)، في صفحة جديدة لم يكن لها مكان آخر تذهب إليه. يشير إلى الفقرة التي تحيل إليها أولًا. | تُطبع الصورة بذلك المقياس؛ وتتجاوز مساحة النص فقط حين يقول ذلك overflowPx. |
floatCropped | قُصّت صورة عائمة داخل منطقتها الآمنة (Resource.safeArea) لتبقى في الصفحة التي تحيل إليها، بفعل layout.. resourceId يحدّدها، وshare نسبة ما قُصّ من ارتفاعها، وpageIndex الصفحة. يشير إلى الفقرة التي تحيل إليها أولًا. | تُطبع الصورة مقصوصة، ولا يتجاوز القصّ منطقتها الآمنة أبدًا. الخيار pullFloatsToCitation غير مستحسن: placement.citingPage وplacement.shrink: 'slot' يُبقيان الصورة قرب إحالتها دون قصّها. |
floatPinMissed | عنصر عائم وُضع يدويًا (placement.pin) ليس حيث يطلب تثبيته. resourceId يحدّده، وpageIndex الصفحة التي ذهب إليها، وrequestedPage الصفحة التي يسمّيها التثبيت. reason: notTaken (لم يتسع له الموضع: أطول من المساحة الباقية، أو مشغول، أو فوق الإحالة إليه، أو انتهى الفصل قبله)، أو tooFar (أكثر من MAX_PIN_PAGE_OFFSET، أي 3، صفحات بعد الصفحة المحيلة)، أو column (لا عمود كهذا في تلك الصفحة)، أو unsupported (مورد موضوع في النص، أو عنصر عائم في العمود الجانبي أو مُدار، أو لوحة كاملة). يشير إلى الفقرة التي تحيل إليه أولًا. | يُوضع العنصر كما لو لم يكن مثبّتًا، في الصفحة التي يسمّيها التثبيت إن اتسع له موضع فيها. التثبيت غير مستحسن: placement.citingPage وposition وshrink تُبقي الشكل قرب نصه في كل طبعة. |
pictureBelowPrintSize | صورة نقطية لها مقاس طباعة (دقّتها bitmap.resolution، أو رقم في layout.bitmapResolution؛ لا دقّة مقروءة من الملف) منضّدة في عمود يُبقيها دون نصف ذلك المقاس، في صفحة كتلة نصها أعرض من العمود. يحدّدها resourceId، وscale هي النسبة التي تبقى من عرض طباعتها، وprintWidthPx وwidthPx وpageWidthPx عروض الطباعة والعمود وكتلة النص. لا يصدر هذا التحذير عن صورة ضيّقها placement.width أو صُغّرت لتسع موضعها أو أُديرت أو وُضعت في خانة صفحة مركّبة. يشير إلى الفقرة التي تذكرها أولًا. منذ postext 1.37. | تُطبع الصورة بعرض عمودها. الصورة في المتن لا تكون أعرض من عمودها أبدًا، وللصفحة الافتراضية عمودان (layout.): نضّد الصفحة في عمود واحد، أو اجعل الصورة تطفو على عرض الصفحة (placement.span: 'page')، أو ارفع دقّتها إن كان هذا المقاس هو المراد. |
emptyCaption | لمورد من نوع له بادئة تعليق لا تعليق خاص به، فيطبع سطر تعليقه الوسم والرقم وحدهما. يسمّيه resourceId، وlabel هو السطر المطبوع. للعلم: يُبلَّغ عنه مرة لكل مورد، عند الفقرة التي تحيل إليه أو عند تضمينه. منذ postext 1.52. | يُطبع الوسم. اكتب التعليق، أو أبقِ الوسم وحده إن كان المقصود لوحة مرقَّمة. |
resourceMoved | مورد موضوع في النص (position: 'here') كان أطول من المساحة الباقية في عموده فانتقل كاملًا إلى العمود التالي. يسمّيه resourceId، ويذكر emptyPx وemptyMm المساحة التي تركها فارغة، وpageIndex الصفحة. يُبلَّغ عنه حين تبلغ تلك المساحة سطرين من شبكة النص أو أكثر؛ أما الصورة التي يلتف حولها النص فتقول ذلك بـtextWrap 'moved'. يشير إلى التضمين. منذ postext 1.52. | يقف المورد في أعلى العمود التالي. صغِّره، أو انقل سطر ::resource الخاص به، أو اجعله عائمًا (placement.). |
textWrap | مورد أو إطار ضُبط ليلتف النص حوله (placement.wrap، وwrap في الإطار) لم يُنضَّد كما طُلب. reason: 'tooNarrow' (سيكون النص المجاور أضيق من layout.wrap.minTextWidth)، أو 'fewLines' (أقصر من layout. سطرًا)، أو 'moved' (عنصر داخل النص أطول من المساحة المتبقية في عموده انتقل إلى العمود التالي مع مرساته)، أو 'verticalText'، أو 'noContour' (التفاف حول محيط صورة لا يُعرف شكلها: SVG بلا contour.points، أو صورة نقطية بلا شفافية، أو قناة ألفا لم يتتبّعها المضيف). resourceId يحدّد المورد، وbox نمط الصندوق. يشير إلى موضع المورد أو الإطار. | يأخذ العنصر الشريط كله، أو يوضع في العمود التالي، كما يقول السبب؛ ومع 'noContour' يلتف النص حول إطار الصورة. أعطِ الصورة مضلّعًا، أو استعمل PNG فيه شفافية، أو اقرأها عبر readBundle أو Sandbox، فكلاهما يتتبّع شكلها. |
columnsTooNarrow | الأعمدة الفرعية لمجموعة :::columns أضيق من ست وحدات em من نصها: عددها columns، وعرض كل منها widthPx. يشير إلى سطر فتح المجموعة. | تُنضَّد المجموعة كما طُلب، بكلمات قليلة في السطر. |
afterText | إطار span: 'side'، أو شكل أو جدول في العمود الجانبي (resourceId)، وُضع في صفحة لا نص فيها: انتهى نص فصله، أو نص المستند، وهو ما زال ينتظر مكانًا في العمود الجانبي. تحذير لكل إطار أو عنصر عائم؛ يشير إلى الإطار (أو إلى الكتلة التي تحيل إلى العنصر العائم)، مع صفحته. منذ postext 1.25. | يقف في العمود الجانبي لصفحة فُتحت بعد النص، والإطارات بترتيب ورودها في النص. |
unplaced | إطار أو مورد عائم (resourceId) كان ما زال ينتظر موضعًا حين انتهى التنضيد: الصفحات التي فُتحت له لم تتسع له (إطار جانبي وتلك الصفحات بلا عمود جانبي مثلًا). يشير إلى الإطار أو إلى الكتلة التي تحيل إلى المورد؛ بلا صفحة. منذ postext 1.25. | ليس في أي صفحة. حتى postext 1.24 كان يسقط بلا تحذير. |
paragraphCitedInNote | مورد موضوع بعد الفقرة التي تحيل إليه (position: 'paragraph') لا تحيل إليه إلا الحواشي، ومنها تعليقات نهاية الفصل: لا :ref له في المتن، ولا سطر ::resource، ولم يضعه فصل سابق. والحاشية تُصفّ بمعزل عن التدفق، فلا فقرة يأتي بعدها. resourceId يحدّده. يشير إلى أول :ref له في حاشية؛ بلا صفحة. | ليس في أي صفحة. أحِل إليه في المتن أيضًا، أو ضمِّنه بـ ::resource، أو أعطه موضعًا عائمًا. |
shortListSplit | قائمة عدد بنودها items، قصيرة بحسب bodyText.، مقسومة بين عمودين أو صفحتين. مع bodyText. يصدر تحذير عن كل قائمة كهذه؛ ومع 'avoid'، عن القائمة التي لم يتسع لها أي عمود كاملةً فقط. تحذير لكل قائمة؛ يشير إلى القائمة، مع صفحة بندها الأول. منذ postext 1.28. | تُقسم القائمة حيث ينتهي العمود. |
stack | سطران متتاليان من فقرة، في عمود واحد، ينتهيان (edge: 'end') أو يبدآن ('start') بالكلمة نفسها أو بـbodyText. من الأحرف نفسها: text ما يكرّرانه كما يطبعه السطر الأول، وlines السطران. مع bodyText.stacks: 'warn' يُبلَّغ عن كل تكرار؛ ومع 'avoid'، عن التكرارات التي أبقتها الخوارزمية. تحذير لكل تكرار؛ يشير إلى السطرين، مع صفحتهما. منذ postext 1.73. | تُنضّد الأسطر كما هي. |
hyphenLadder | أكثر من max أسطر متتالية من فقرة تنتهي بشرطة (bodyText.): lines عددها وtext الأسطر نفسها. مع bodyText. يُبلَغ عن كل سلّم؛ ومع 'avoid' عن السلالم التي أبقاها كسر الأسطر. واحد لكل سلّم؛ يشير إلى أسطره، مع صفحة أولها. منذ postext 1.74. | تُنضّد الأسطر كما هي. |
lastWordDivided | السطر الأخير من فقرة لا يحمل إلا بقية كلمة قُسمت في السطر الذي قبله: word الكلمة كما يطبعها السطران، بالشرطة. مع bodyText. يُبلَغ عن كل حالة؛ ومع 'avoid' عمّا أبقاه كسر الأسطر. يشير إلى السطرين الأخيرين، مع صفحتهما. منذ postext 1.74. | تُنضّد الأسطر كما هي. |
tocGroupSplit | مجموعة من المحتويات يُطلب إبقاؤها معًا (toc.groups.keepTogether، :::toc{keep="…"})، يتصدّرها title، ومنضّدة في columns من الأعمدة: إما أنها أطول من عمود كامل، وإما أن العمود الذي تبدأ فيه قصير (تحت إطار يمتد بعرض الصفحة، أو بجوار عنصر عائم). تحذير لكل مجموعة؛ يشير إلى التوجيه :::toc، مع الصفحة التي تبدأ فيها المجموعة. ولإزالته، أدرِج مستويات أقل (levels="1")، أو اجعل رأس المجموعات مستوى أدنى (toc.groups.head: 2)، أو صغّر المداخل أو ضيّق تباعدها. منذ postext 1.34. | تُقسم المجموعة؛ ومع toc.groups.continuation يُفتتح كل عمود تستمر فيه بصف رأسها وعلامة الاستمرار. |
openerFloat | عنصر عائم وُضع في صفحة افتتاح مع layout.: شكل أو جدول أو شريط قصص مصورة (resourceId)، أو إطار عائم. تحذير لكل عنصر عائم؛ يشير إلى الكتلة التي تحيل إليه (أو إلى الإطار)، مع صفحته. منذ postext 1.28. | يقف العنصر العائم في صفحة الافتتاح؛ و'avoid' تنقله إلى أول موضع بعدها. |
headingClaimsColumn | عنوان داخل العمود (span: 'column') يحجز تصميمه العمود كله، فيبدأ النص الذي يليه في العمود التالي أو الصفحة التالية (level وelement: عنصر التصميم الأبعد نزولًا، ويغيب حين يحدد minHeight الارتفاع). تحذير واحد لكل عنوان، يشير إلى العنوان مع صفحته. لا يصدر عن افتتاحية الصفحة الكاملة ولا عن عنوان في صفحة ذات عمود واحد ولا عن عنوان يتبعه فاصل صريح. منذ postext 1.43. | يبدأ النص بعد العنوان في العمود التالي أو الصفحة التالية. يزيله ضبط reserve: false على العنصر أو خفض minHeight أو span: 'page'. |
fontFallback | شكل خط نُضّد به النص (family، weight، style) ولم تستطع مجموعة الخطوط توفيره حين جرى البناء: reason: 'missing'، لم يكن أي شكل من العائلة محمَّلًا ولا مثبّتًا، أو لم يكن الشكل الموافق لهذا الوزن والميل قد اكتمل تحميله؛ و'synthesized'، ليس في العائلة شكل بهذا الوزن أو الميل فيأخذه المتصفح من شكل آخر فيها، كما هو أو مغلَّظًا أو مُمالًا (وزن 600 يُنضَّد بشكل 700، أو وزن 700 مائل يُطلب من عائلة ليس فيها إلا 400 عادي). يُفحص حيث توجد مجموعة خطوط (document.fonts، أو self.fonts في عامل، أو BuildDocumentOptions.)، ويخضع لـdebug.. بلا صفحة ولا نطاق في المصدر. | يُقاس النص ويُرسم بالخط البديل، أو بشكل آخر من العائلة، كما هو أو مغلَّظًا أو مُمالًا؛ وتتغيّر مواضع تقسيم أسطره حين يصل الشكل. انظر تحميل الخطوط قبل الإخراج. |
glyphFallback | محارف يجعلها النص في خط (family وweight وstyle) ليس فيه شكل لها: يذكر characters أول 24 منها، كلًّا مرة واحدة، ويذكر count عددها كله، ويسمّي supplier العائلة التي رسمتها (عائلة عامة مثل serif)، ويغيب حين يرسمها خط يختاره النظام. تحذير واحد لكل خط. في المتصفح أو في worker يسأل المحرك خطًّا مسبارًا يعلنه في مجموعة الخطوط (installGlyphProbe، وتستدعيه prepareFonts وworker التخطيط)؛ وفي غيرهما يقرأ جدول cmap من الملفات المسجلة بـregisterFontCoverage، كما يفعل سطر الأوامر. يخضع لـdebug.. بلا صفحة ولا نطاق في المصدر. منذ postext 1.52. | تُرسم المحارف بخط آخر قد لا يوافق تصميمه وعروضه خط النص. اختر عائلة تغطيها. |
glyphFallbackAt | كتلة فيها محارف لا يملكها خطها: الموضع الذي لا يذكره glyphFallback. واحد لكل كتلة وخط وصفحة وعائلة ترسمها (200 على الأكثر في المستند): characters يعدّها، وsupplier عائلة القائمة التي ترسمها (symbolFont)، ويغيب لما لا تملكه أي عائلة. يشير إلى الكتلة التي يسمّيها blockId. ولا تُبلَّغ المحارف التي ترسمها symbolFont بوصفها glyphFallback. | تُرسم بـ supplier؛ وبدونها يطبعها PDF مربعات فارغة. حدّد symbolFont تحويها. |
يسرد الجدول الأنواع التي يمكن أن يُصدرها أي مستند. أما أنواع الميزة الواحدة فتُوصف معها: القصص المصورة (comicPanelCount، comicBalloonOverflow…) في صفحة القصص المصورة، ومقاطع الفيديو (videoWithoutUrl، videoUrlInvalid، videoWithoutPoster) في الصور والجداول ومقاطع الفيديو، والاستشهادات والفهرس (unknownCitationKey، referencesUnreadable، indexMark…) في الحواشي والإحالات، والنص الصيني والياباني والعربي (cjkLooseLine، rubyExceedsLeading، arabicMarksExceedLeading…) في صفحات هذه الكتابات، وأنواع مقسِّم الأسطر (raggedLine، unbreakableWordOverflow، wordDividedByCharacter، wordDividedBySyllable) في تقسيم الكلمات وضبط الأسطر.
التحذيرات المتعلقة بمورد ما، سواء نمط جدوله أو شبكته أو مرجع داخل تعليقه أو ملاحظته أو خلاياه، تشير إلى أول تضمين لذلك المورد أو أول مرجع إليه في النص، ويُسجَّل كل منها مرة واحدة لكل مورد. ولا تُفحص إلا الموارد التي يستخدمها المستند: ففصل من كتاب يُصدر تحذيرات عن الجداول التي يستشهد بها، لا عن كل جدول في الكتاب.
import { buildDocument, formatWarning } from 'postext';
const doc = buildDocument({ markdown: 'See :ref{id="fig-map"}.\n\n:::sidebar\nNotes.' }, config);
for (const w of [...(doc.warnings ?? []), ...(doc.contentWarnings ?? []), ...(doc.configWarnings ?? [])]) console.warn(formatWarning(w));
// Unknown resource id "fig-map" in :ref — it prints "?" (or its text= label), with no number or link (page 1, offset 4)
// Unknown directive ":::sidebar" — the line is set as text (page 1, offset 25)
// Narrow on `kind` to read the fields of a kind.
const missing = (doc.contentWarnings ?? []).flatMap((w) => (w.kind === 'unknownResourceId' ? [w.resourceId] : []));تُعيد formatWarning(w) وصفًا بالإنجليزية في سطر واحد. أما المضيف الذي يترجم رسائله فيتفرّع بحسب kind بدلًا من ذلك، ويحتفظ بفرع افتراضي، لأن الإصدارات الفرعية قد تضيف أنواعًا. وتُعيد collectContentWarnings(markdown, config, resources) تحذيرات المحتوى دون إخراج أي شيء (القائمة التي يضيفها البناء، دون pageIndex)، لمحرّر يفحص النص أثناء الكتابة. وتفحص collectHeadingDesignCuts(doc) إخراجًا مكتملًا بحثًا عن تصاميم عناوين يتجاوز نصها أسفل صفحتها أو عمودها (kind: 'headingDesignCut'؛ انظر الارتفاع المحجوز)، وهو ما لا يُصدر عنه الإخراج نفسه تحذيرًا، وتصف formatWarning نتائجها كذلك. وتعرضها لوحة الفحوص في Sandbox جميعًا.
تُصدر المُخرِجات (renderers) تحذيرات عمّا لا تستطيع رسمه كما طُلب منها عبر خيار onWarning: renderPageToCanvas وrenderPage وrenderToCanvas (RenderPageOptions)، وrenderToHtml وrenderToHtmlIndexed (RenderHtmlOptions)، وrenderToPdf (RenderToPdfOptions، وعبر عامل PDF أيضًا). النوع الرئيسي من تحذيرات العرض هو missingImage: الصورة التي لا يوجد ما يُرسم لها، سواء أكانت شكلًا أم صورة في خلية جدول أم أيقونة إطار أم صورة تصميم، تُرسم عنصرًا نائبًا محايدًا ويصدر عنها تحذير مرة واحدة لكل fileId ولكل استدعاء عرض، ومعها pageIndex، وresourceId حين يعرفه المُخرِج (للأشكال وصور الخلايا)، وdocumentIndex في PDF عند عرض عدة مستندات. ويعني «لا يوجد ما يُرسم» غياب registerResourceImage للمعرّف fileId في Canvas، وغياب عنوان URL من resourceImageUrl في HTML، وغياب البايتات من resourceBytes في PDF، أو وجود بايتات يتعذّر فكّ ترميزها. أما المورد النقطي أو SVG الذي لا يذكر أي fileId فليس لديه ما يطلبه: فيُرسم عنصرًا نائبًا دون تحذير. ويأتي نوعان آخران من المضيفات التي تضمّن الخطوط في صور SVG (registerSvgImage وregisterBundleImages وbundleImageUrl وrenderToHtml مع inlineSvgFonts وpostext-epub؛ انظر الخطوط في نصوص SVG)، ومعهما fileId الصورة وresourceId: النوع svgFontUnavailable (family وweight وstyle)، عائلة يذكرها نصها ولا شكل لها يمكن تضمينه، فتنضّد الصورة ذلك النص بخط بديل؛ والنوع svgFontsTooLarge (bytes وmaxBytes)، أشكال خطوط تتجاوز حد الحجم، فلا يُضمَّن منها شيء. ولا تُخزَّن تحذيرات العرض في VDT، لأن ما يستطيع المضيف توفيره يتغيّر بعد الإخراج.
import { buildDocument, renderPage, type RenderWarning, type Resource } from 'postext';
const map: Resource = {
id: 'fig-map', typeId: 'figure', kind: 'bitmap', caption: 'The route.', createdAt: 0, updatedAt: 0,
bitmap: { fileId: 'map-file', format: 'png', width: 1200, height: 800 },
};
const doc = buildDocument({ markdown: 'See :ref{id="fig-map"}.', resources: [map] }, config);
const warnings: RenderWarning[] = [];
const canvas = renderPage(doc.pages[0], doc, { onWarning: (w) => warnings.push(w) });
// Until 'map-file' is registered with registerResourceImage:
// [{ kind: 'missingImage', fileId: 'map-file', resourceId: 'fig-map', pageIndex: 0 }]#رسم صفحة في صورة نقطية
يمكن تحويل كل صفحة إلى صورة نقطية (bitmap) على حدة. استخدم renderPage(page, doc) للحصول على HTMLCanvasElement لرقم صفحة معيّن، وCanvas صورة نقطية مقاسها يطابق تمامًا أبعاد الصفحة بالبكسل (بدقة DPI المضبوطة)، فيمكنك عرضها أو تصديرها أو تمريرها إلى أي سلسلة لمعالجة الصور:
import { buildDocument, renderPage } from 'postext';
const vdt = buildDocument(content, config);
// Render page 3 (zero-indexed) to a bitmap canvas
const pageNumber = 2;
const page = vdt.pages[pageNumber];
if (!page) throw new Error(`Page ${pageNumber} does not exist`);
const canvas = renderPage(page, vdt);
// canvas.width / canvas.height are the page bitmap size in pixels
// Show it in the DOM
document.body.appendChild(canvas);
// …or export it as a PNG data URL
const pngDataUrl = canvas.toDataURL('image/png');
// …or get a Blob for download / upload
canvas.toBlob((blob) => {
if (blob) saveAs(blob, `page-${pageNumber + 1}.png`);
}, 'image/png');
// …or grab raw RGBA pixels
const ctx = canvas.getContext('2d')!;
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);إذا كنت تفضّل الرسم في Canvas تملكه مسبقًا (مثلًا عنصر Canvas مُلحق بـDOM ضمن تخطيط معيّن)، فاستخدم renderPageToCanvas(page, doc, canvas)، فهي تغيّر مقاس Canvas الذي تمرّره وترسم فيه، بدلًا من إنشاء Canvas جديد.
لرسم كل الصفحات، كرّر على vdt.pages:
const bitmaps = vdt.pages.map((page) => renderPage(page, vdt));مثال حيّ: صفحة في صورة
كل ما سبق يعمل في المتصفح. يستورد المثال على CodePen أحدث إصدار من postext من شبكة توصيل المحتوى (CDN)، وينتظر خطوط الويب، ويُخرج مستندًا قصيرًا من عمودين، ويرسم صفحته الأولى في Canvas، ويتيح تلك الصورة النقطية بصيغة PNG. اضغط شغّل على CodePen لتحميل المحرّر وتغيير نص Markdown أو الإعدادات؛ وتُعاد الصفحة رسمها مع كل تعديل.
import { buildDocument, renderPage } from 'https://esm.sh/postext';
const markdown = `# The Lantern
The lantern hung from a nail by the door, and every evening someone lit it. Nobody remembered who had put the nail there, or why the lantern was never moved.
## Two columns
Postext lays this text out in **two columns**, breaking each paragraph with the *Knuth–Plass* algorithm and hyphenating with TeX patterns. Widows and orphans are avoided, and the columns are balanced on the last page.
The light it gave was small, but it was enough to find the step. The lantern hung from a nail by the door, and every evening someone lit it. Nobody remembered who had put the nail there, or why the lantern was never moved.
The light it gave was small, but it was enough to find the step. The lantern hung from a nail by the door, and every evening someone lit it. Nobody remembered who had put the nail there, or why the lantern was never moved.`;
const config = {
// 150 dpi: crisp enough for a preview, light enough to paint instantly.
page: { sizePreset: '17x24', dpi: 150 },
layout: { layoutType: 'double' },
bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 10, unit: 'pt' } },
};
// Postext measures text with the fonts the browser has loaded,
// so wait for every face the document uses before laying it out.
await Promise.all([
document.fonts.load('16px "EB Garamond"'),
document.fonts.load('bold 16px "EB Garamond"'),
document.fonts.load('italic 16px "EB Garamond"'),
document.fonts.load('bold 16px "Open Sans"'), // the default heading face
]);
// The whole layout: one entry per page in doc.pages, with exact coordinates.
const doc = buildDocument({ markdown }, config);
// Rasterise the first page. The canvas is sized to the page at the configured dpi.
const canvas = renderPage(doc.pages[0], doc);
document.getElementById('page').replaceChildren(canvas);
document.getElementById('status').textContent =
`${doc.pages.length} page(s) · page 1 is ${canvas.width} × ${canvas.height} px`;
// The same bitmap as a PNG file.
canvas.toBlob((blob) => {
const link = document.getElementById('download');
link.href = URL.createObjectURL(blob);
link.hidden = false;
}, 'image/png');index.html
<p id="status">Laying out…</p>
<a id="download" download="page-1.png" hidden>Download page 1 as PNG</a>
<div id="page"></div>style.css
body {
margin: 16px;
font-family: system-ui, sans-serif;
background: #e8e8e8;
}
#page canvas {
display: block;
max-width: 100%;
height: auto;
margin-top: 12px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
}يحمّل محررًا تفاعليًا من codepen.io. يستورد المثال أحدث إصدار من postext عبر شبكة توصيل المحتوى (CDN).
#React
يصدّر postext/react الدالة createLayout(content, config?): وهي مكوّن يُخرج المستند مرة واحدة عند تركيبه، ويعرض كل صفحة على هيئة <canvas> داخل <div>.
import { createLayout } from 'postext/react';
const Article = createLayout(
{ markdown: '# Hello\n\nThe first paragraph of the article.' },
{ page: { sizePreset: '17x24' } },
);
export function ArticlePage() {
return <Article className="pages" style={{ maxWidth: 480 }} />;
}- على الخيط الرئيسي، مرة واحدة. تُرسم الصفحات بدقة المستند وتُحجَّم إلى عرض الحاوية. يُثبَّت
contentوconfigعند استدعاءcreateLayout؛ فأنشئ مكوّنًا آخر لعرض شيء مختلف. وللمعاينة الحيّة، ابنِ في Web Worker وارسم باستخدامrenderPageToCanvas، كما في مثال React هناك. - الخطوط والصور أولًا. حمّل خطوط الويب الخاصة بالمستند قبل تركيب المكوّن، وسجّل صوره باستخدام
registerResourceImage. وحين يحوي نص Markdown الرمز$، يشغّل المكوّن محرّك الرياضيات بنفسه. - يبقى React خارج نقطة الدخول الرئيسية. لا يستورد
postextمكتبة React أبدًا؛ وحدهpostext/reactيفعل. ولا تزالcreateLayoutمُصدَّرة منpostextكي تستمر الشيفرة الحالية في العمل، لكنها مُهمَلة (deprecated): فهي تحمّلpostext/reactعند استدعائها، ويُعلَّق المكوّن (suspend) حتى يصل (ثم يعيد React عرضه من تلقاء نفسه). استوردها منpostext/react. - المكوّن المُهمَل يُعلَّق. إلى أن يصل
postext/react، تحتاجcreateLayoutالمستوردة منpostextإلى جذر متزامن (createRoot) أو حدّ<Suspense>فوقها. وفي جذرReactDOM.renderالقديم، أو فيrenderToString، دون حدّ، يُبلّغ React عن خطأ بدلًا من ذلك. ويبقىreactتبعية نظيرة (peer dependency) إلزامية، كي تستطيع أدوات التجميع حلّ ذلك الاستيراد الكسول.
#استكمال القيم الافتراضية
تملأ دوال الاستكمال (resolvers) القيم الافتراضية في كائنات الإعدادات الجزئية. ويفيد ذلك حين تحتاج إلى إعدادات كاملة لفحصها أو مقارنتها:
import { resolvePageConfig, resolveBodyTextConfig } from 'postext';
const fullPage = resolvePageConfig({ sizePreset: '21x28' });
// => { sizePreset: '21x28', width: { value: 21, unit: 'cm' }, height: { value: 28, unit: 'cm' },
// margins: { top: { value: 2, unit: 'cm' }, ... }, dpi: 300, cutLines: { enabled: false, ... }, ... }
const fullBody = resolveBodyTextConfig({ fontFamily: 'Inter' });
// => { fontFamily: 'Inter', fontSize: { value: 8, unit: 'pt' }, lineHeight: { value: 1.5, unit: 'em' }, ... }دوال الاستكمال المتاحة، واحدة لكل قسم من المستوى الأعلى: resolvePageConfig، resolveLayoutConfig، resolveBodyTextConfig، resolveHeadingsConfig، resolveHeadingStylesConfig، resolveTocConfig، resolvePartsConfig، resolveUnorderedListsConfig، resolveOrderedListsConfig، resolveMathConfig، resolveTableStyleConfig، resolveCaptionStyleConfig، resolveDiagramStyleConfig، resolveParagraphStylesConfig، resolveCalloutStylesConfig، resolveHeaderFooterConfig، resolveDebugConfig، resolveHtmlViewerConfig، resolvePdfGenerationConfig، إضافة إلى resolveDesignSlot لخانة تصميم واحدة. أما لوحات الألوان فتُطبَّق على حدة عبر applyPaletteToConfig(config) وapplyPaletteToResolvedConfig(resolved, palette) وresolveColorValue(value, palette, fallback)؛ انظر لوحة الألوان.
دوال الاستكمال التي تتسلسل قيمها الافتراضية من قسم آخر تأخذ ذلك القسم، مستكمَلًا، معاملًا إضافيًا. فتأخذ resolveUnorderedListsConfig وresolveOrderedListsConfig نص المتن المستكمَل، لأن القيم الافتراضية للقوائم في fontFamily وcolor تتسلسل منه؛ وتأخذ resolveCalloutStylesConfig نص المتن والعناوين والقوائم غير المرقّمة مستكمَلة (انظر المثال في أنماط الإطارات)، وتأخذ resolveHeadingStylesConfig الصفحة ونص المتن وقسمَي القوائم مستكمَلة. راجع تصريحات الأنواع في الحزمة لمعرفة التوقيع الدقيق لكل منها:
import { resolveBodyTextConfig, resolveUnorderedListsConfig } from 'postext';
const body = resolveBodyTextConfig({ fontFamily: 'Inter' });
const lists = resolveUnorderedListsConfig({ bulletChar: '—' }, body);
// => lists.fontFamily === 'Inter' (inherited)وتُصدَّر أيضًا مجموعات القيم الافتراضية الثابتة، أي القيم المستخدمة حين لا يدخل أي تسلسل في الحساب: DEFAULT_PAGE_CONFIG، DEFAULT_CUT_LINES، DEFAULT_PAGE_NUMBERING، PAGE_SIZE_PRESETS، DEFAULT_LAYOUT_CONFIG، DEFAULT_COLUMN_RULE، DEFAULT_COLUMN_BALANCING، DEFAULT_BODY_TEXT_CONFIG، DEFAULT_HYPHENATION_CONFIG، DEFAULT_HEADINGS_CONFIG، DEFAULT_UNORDERED_LISTS_STATIC، DEFAULT_ORDERED_LISTS_STATIC، DEFAULT_PARAGRAPH_STYLES، DEFAULT_CALLOUT_STYLES، DEFAULT_CALLOUT_STYLE_STATIC، DEFAULT_PARTS_CONFIG، DEFAULT_HEADING_STYLES، DEFAULT_TOC_CONFIG، DEFAULT_MATH_CONFIG، DEFAULT_DIAGRAM_STYLE_CONFIG، DEFAULT_DEBUG_CONFIG، DEFAULT_HTML_VIEWER_CONFIG، DEFAULT_PDF_GENERATION_CONFIG، DEFAULT_COLOR_PALETTE، DEFAULT_MAIN_COLOR، DEFAULT_MAIN_COLOR_ID، DEFAULT_MAIN_COLOR_NAME، DEFAULT_MAIN_COLOR_HEX، إضافة إلى القيم الافتراضية لعناصر الترويسة والتذييل (DEFAULT_HEADER_FOOTER_SLOT، DEFAULT_HEADER_SLOT، DEFAULT_FOOTER_SLOT، DEFAULT_TEXT_ELEMENT، DEFAULT_RULE_ELEMENT، DEFAULT_BOX_ELEMENT) والدالة defaultResourceTypes(locale) التي تراعي اللغة (انظر أنواع الموارد).
#حذف القيم الافتراضية
عند حفظ الإعدادات (في localStorage أو في ملف مثلًا)، استخدم stripConfigDefaults لإزالة القيم المطابقة للقيم الافتراضية. فتبقى الإعدادات المخزَّنة في حدّها الأدنى، ولا يُحفظ إلا ما غيّرته عن قصد:
import { stripConfigDefaults } from 'postext';
const minimal = stripConfigDefaults(fullConfig);
// Only properties that differ from defaults remainتتوفر أيضًا دوال حذف (strippers) منفردة، واحدة لكل دالة استكمال: stripPageDefaults، stripLayoutDefaults، stripBodyTextDefaults، stripHeadingsDefaults، stripHeadingStylesDefaults، stripTocDefaults، stripPartsDefaults، stripUnorderedListsDefaults، stripOrderedListsDefaults، stripMathDefaults، stripTableStyleDefaults، stripCaptionStyleDefaults، stripDiagramStyleDefaults، stripParagraphStylesDefaults، stripCalloutStylesDefaults، stripHeaderFooterDefaults، stripDesignSlotDefaults، stripDebugDefaults، stripHtmlViewerDefaults، stripPdfGenerationDefaults.
بعض القيم الافتراضية تتوقف على بقية الإعدادات: موازنة الأعمدة معطّلة في شبكة المحارف وفي النص العمودي، وbodyText.avoidWidows معطّلة في شبكة المحارف (وكذلك bodyText.avoidOrphans في المنطقة japan)، والحواشي السفلية والتعليقات والفهرس الأبجدي تتبع لغة المستند. تقارن stripConfigDefaults كل قيمة بالقيمة الافتراضية للإعدادات التي تتلقاها، فتبقى headings.balancing.enabled: true حين تكون الموازنة معطّلة افتراضيًا، وتُحذف false هناك. وتبقى bodyText.avoidWidows: true على النحو نفسه في شبكة المحارف. ودالة الحذف المنفردة تأخذ هذا السياق في وسائطها: stripHeadingsDefaults(headings, balancingOnByDefault(config))، stripIndexDefaults(index, locale)، stripCaptionStyleDefaults(captionStyle, locale)، stripFootnotesDefaults(footnotes, locale, writingMode)، stripBodyTextDefaults(bodyText, locale, avoidWidowsByDefault(config), avoidOrphansByDefault(config)).
القيمة التي تعني «لا شيء» تبقى حيثما لا يكون «لا شيء» هو القيمة الافتراضية. نمط العنوان يأخذ ترويسة المستند وتذييله حين لا يحدّد ما يخصّه، فالنمط الذي يفرغهما (footer: { elements: [] } في غلاف) يحتفظ بالموضع الفارغ، وتبقى margins وlayout وbodyStyle فيه ولو كانت فارغة. ومستوى العنوان المُعاد إلى قيمته الافتراضية تحت قيم عامة للعناوين تخالفها يحتفظ بقيمته. وتبقى calloutStyles: [] وchipStyles: [] قائمتين فارغتين: لو حُذفتا لعاد النمط المدمج. وفي كل الأحوال تُستكمل resolveAllConfig(stripConfigDefaults(config)) كما تُستكمل resolveAllConfig(config).
#التحليل
يتيح المحرّك مُقطِّع Markdown الخاص به وقارئ البيانات التمهيدية. استخدمهما لفحص مستند قبل بنائه، أو لتغذية أدوات أخرى ببنية الكتل نفسها التي يراها Postext:
import { parseMarkdown, extractFrontmatter } from 'postext';
const source = '---\ntitle: Chapter One\n---\n\n# Opening\n\nThe story begins here.';
const { metadata, content } = extractFrontmatter(source);
// metadata.title === 'Chapter One'
const blocks = parseMarkdown(content);
// => [ { type: 'heading', level: 1, text: 'Opening', … },
// { type: 'paragraph', text: 'The story begins here.', … } ]راجع صفحة صيغة المستند للاطلاع على القائمة الكاملة لبنى Markdown التي يتعرّف عليها Postext.
#خريطة المصدر لمستند منضد
تُرجع sourceAt(doc, pageIndex, x, y, options?) ما تعرضه نقطة من صفحة، من الداخل إلى الخارج، وكل عنصر معه id الثابت وsource (مقطع من Markdown، أو مؤشر JSON في الإعدادات، أو سمة من سطر فتح كتلة الصفحة، أو مورد) وrect. وتُرجع elementsForSource(doc, start, end, options?) ما صار إليه مقطع من Markdown، لكل صفحة على حدة، وتعيد findElement(doc, id) العثور على عنصر بعد إعادة التنضيد. وهي تقرأ ما وسمه التنضيد على VDT ولا تنضّد شيئًا. وتخبر composedPagePaintKey(page) هل ترسم الصفحة المركّبة ما رسمته من قبل. وأنواع المصادر والمعرّفات وكيف يُعاد تنضيد الصفحة المركّبة حيث تغيّرت فقط مشروحة في الصفحات المركّبة › خريطة المصدر.
#تحميل الخطوط قبل الإخراج
يقيس الإخراج النص بأشكال الخطوط الموجودة في مجموعة الخطوط لحظة تشغيله. وتحمّل prepareFonts قبل البناء الأول كل شكل خط تطلبه الإعدادات ونصها: نص المتن، والعناوين، والقوائم، وعناوين الإطارات ونصوصها، والجداول، ونصوص التصميم، والترويسات الجارية، والفهرس، والشيفرة، وحروف القصص المصوّرة، بكل وزن وميل تضبطه الإعدادات (والأربعة كلها لعائلة نص المتن، لأن ** و* ينضّدان العريض والمائل بها). ويُحمَّل كل شكل للمحارف التي ينضّدها المستند، فالعائلة المقدَّمة شرائحَ unicode-range (اللاتينية الموسّعة، واليونانية، والعربية، وشرائح الصينية واليابانية والكورية في Google Fonts وFontsource) تجلب الملفات التي يحتاج إليها النص.
import { prepareFonts, buildDocument, buildDocumentWithFonts } from 'postext';
// ملفات المضيف: عقد مزوّد الخطوط في PDF نفسه، فدالة واحدة تخدم الاثنين.
async function resolve(family: string, weight: number, style: 'normal' | 'italic') {
const id = family.toLowerCase().replace(/\s+/g, '-');
return `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${weight}-${style}.woff2`;
}
const report = await prepareFonts(content, config, { resolve });
// report.loaded, report.missing, report.synthesized: { family, weight, style }[]
const doc = buildDocument(content, config);
// أو في استدعاء واحد: التحضير، فالبناء، فتحميل أي وجه استعملته الصفحات ولم يكن موجودًا، فالبناء من جديد.
const same = await buildDocumentWithFonts(content, config, { resolve });- أشكال الخطوط التي تصرّح بها الصفحة (قاعدة
@font-face، أوFontFaceأُضيف من قبل) تُحمَّل عبر مجموعة الخطوط (document.fonts.load، أوself.fontsداخل عامل). أما أشكال الخطوط التي لا تصرّح بها فتُطلب منresolve(family, weight, style, { text, codePoints })، التي تجيب بملف (بايتات أو عنوان URL)، أو بعدة ملفات (شرائح شكل واحد)، أو بـ{ source, unicodeRange, weight, style }لشريحة أو لمدى متغيّر، أو بـnull. ويضيفها المحرّك كائناتِFontFaceبعد أن يكتمل تحميلها جميعًا، بترتيب الإعدادات وترتيب كل إجابة (latin، ثم latin-ext، ثم greek إن أجاب المحلِّل بذلك)، فتبقى مجموعة الخطوط هي نفسها أيًّا كان الترتيب الذي تصل به الملفات. ويسجّلها أيضًا في سجل الخطوط الذي تقرؤه صور SVG وعمّال الإخراج. ويجوز للمحلِّل أن يصرّح بالشكل بنفسه (بإضافة ورقة أنماط) ثم يجيب بـnull. - التقرير يسرد في
loadedأشكال الخطوط التي يغطيها شكل محمَّل (أو عائلة مثبّتة)، وفيmissingالأشكال التي لا تزال مفقودة، وفيsynthesizedالأشكال التي سيرسمها المتصفح من وزن أو ميل آخر؛ ويعدّaddedكائناتFontFaceالتي أُضيفت من ملفات المحلِّل. ويحدّtimeoutMs(10 000 افتراضيًا) من مدة الانتظار؛ فالشكل الذي لم يكتمل تحميله عندئذ يُعدّ مفقودًا. وحيث لا توجد مجموعة خطوط (Node) لا تفعلprepareFontsشيئًا، وتعدّ كل أشكال الخطوط محمَّلة. buildDocumentWithFonts(content, config, options)تحضّر، ثم تبني بـbuildDocumentAsync، ثم تقرأ أشكال الخطوط التي نُضّد بها النص فعلًا في الصفحات، فتحمّل ما لم تستطع مجموعة الخطوط توفيره منها (الوزن الذي لا تكشفه إلا الصفحات يُطلب منresolveولو كان في العائلة وزن آخر ينوب عنه)، وتبني من جديد (بنائين إضافيين على الأكثر). وتفعلwithLoadedFonts(build, options)الشيء نفسه حول أي دالة بناء، لكتاب يُبنى فصلًا فصلًا أو لحزمة (buildBundle) تُعيد عدة مستندات. ويتلقىoptions.onFontsالتقرير النهائي.- بعد البناء، يُضاف إلى
doc.contentWarningsكل شكل خط نُضّد به النص ولم تستطع مجموعة الخطوط توفيره، بوصفهfontFallback(انظر التحذيرات في المستند).
أنماط الأرقام. النمط الذي له figureStyle يصفّ نصه في عائلة بميزات: اسم العائلة الأساسية تتبعه ميزات OpenType بعد @ (EB Garamond@onum). ويُطلب من prepareFonts وresolve العائلةُ الأساسية، ويصرّح المحرّك بأشكال العائلة ذات الميزات من الملفات نفسها مع الواصف featureSettings. ويقبل FontPayload في عامل الإخراج featureSettings اختياريًا لمثل هذا الشكل، وتكون family فيه العائلة ذات الميزات والمخزن ملف العائلة الأساسية. وتسرد configFeatureFamilies(config) العائلات ذات الميزات التي يصفّ بها إعدادٌ ما نصًا. والمضيف الذي يصفّ نصًا بخطوط ليست لديه ملفاتها يسمّي بـsetFigureStyleFamilies((family) => boolean) العائلات التي تقبل الميزات؛ وتحتفظ العائلات الأخرى بأرقامها. وتفكّك baseFontFamily وfeatureFamilyParts هذا الاسم، وتبنيه withFigureStyle(fontFamily, figureStyle)، وتعيد freezeFontFeatures(bytes, features) نسخة من ملف TrueType أو OpenType يوجّه جدول cmap فيها المحارف إلى الأشكال التي تعطيها الاستبدالات البسيطة للميزات، من أجل canvas لا يطبّق ميزات (Skia في Node).
وأشكال الخطوط التي تصل لاحقًا يلتقطها المحرّك من تلقاء نفسه. فهو يحتفظ، لكل مجموعة خطوط، بأشكال كل عائلة التي كانت محمَّلة آخر مرة نظر فيها؛ ويعيد البناء النظر عند بدايته (فقط إن كبرت المجموعة أو صغرت، أو كانت تحمّل، أو اكتمل فيها تحميل شكل) ويطرح ما قيس بالعائلات التي تغيّرت أشكالها. وتفعل watchFonts(fontSet) الشيء نفسه أثناء تحميل أشكال الخطوط، مرة واحدة على الأكثر في كل إطار رسوم متحركة مهما كثرت الشرائح التي تأتي بها دفعة واحدة، وتُعلم onFontsChanged(listener) المضيفَ بالعائلات التي تغيّرت، ليعيد إخراج الصفحات:
import { watchFonts, onFontsChanged } from 'postext';
const stop = watchFonts(); // document.fonts افتراضيًا
const off = onFontsChanged((families) => relayout());وتبدأ prepareFonts المراقبة على المجموعة التي تحمّل فيها (watch: false يتركها متوقفة).
#ذاكرة القياس المؤقتة
قياس النص هو الخطوة المكلفة في الإخراج. يحافظ نوعان من الذاكرة المؤقتة على انخفاض كلفتها:
- ذاكرة كتل تملكها أنت. تُعيد
createMeasurementCache()كائنMeasurementCacheيتذكّر كل فقرة قيست، مفهرسةً بنصها وخطوطها وعرضها وخيارات تقسيم الأسطر وقاموس تقسيم الكلمات بالواصلة النشط. مرّره معاملًا ثالثًا إلىbuildDocument(أوbuildDocumentAsync) لإعادة استخدام القياسات عبر تمريرات التوزيع في عملية البناء الواحدة وعبر عمليات البناء: فالمحرّر الذي يُخرج المستند مع كل ضغطة مفتاح لا يقيس حينئذ إلا الفقرات التي تغيّرت. ومن دونها، تقيس كل تمريرة كل كتلة من جديد. والفقرة المقروءة من الذاكرة المؤقتة مطابقة لفقرة قيست من جديد، فالبناء الذي يستخدم ذاكرة مؤقتة ينضّد كل سطر كما ينضّده بناء من دونها؛ وفي postext 1.4.1 كانت الفقرة المخزّنة تفقد علامة السطر الأخير ذي الكلمة المعزولة، فكان تضييق الكلمة المعزولة وموازنة الأعمدة قد يقسمانها تقسيمًا مختلفًا. وتسجّل الذاكرة جيل القياس الذي مُلئت فيه: فحين تصل أشكال عائلة أو تزول، يطرح أول بحث تالٍ فيها الكتل المنضّدة بتلك العائلة، فلا تقدّم ذاكرةٌ محفوظة عبر تحميل الخطوط أسطرًا مقيسة بالخط البديل أبدًا. - ذاكرات العرض العامة. تُخزَّن عروض الكلمات لكل سلسلة خط في حالة على مستوى الوحدة (module) تشترك فيها كل عمليات البناء في الصفحة، وللمكتبة pretext ذاكرتها المؤقتة الخاصة. ويطرح المحرّك عروض عائلة حين تتغيّر أشكالها (في بداية البناء، ومن
watchFonts، ومنprepareFontsوloadBundleFonts)؛ أما ذاكرة pretext فلا فهرس فيها للعائلات، فتُمسح كلها.
import { buildDocument, createMeasurementCache, evictFontFamilies, clearMeasurementCache } from 'postext';
const cache = createMeasurementCache();
let doc = buildDocument(content, config, cache);
// أُضيف وجه من "EB Garamond" إلى document.fonts: يراه البناء التالي،
// بالذاكرة نفسها، ويقيس تلك العائلة من جديد.
doc = buildDocument(content, config, cache);
// المضيف الذي يغيّر أوجهًا لا يراها المحرّك (مجموعة خطوط خاصة به) يُعلمه بذلك:
evictFontFamilies(['EB Garamond']); // عروض تلك العائلة وكتلها المخزّنة
clearMeasurementCache(); // كل العائلاتوللتطبيقات التي تقيس النص قطعة قطعة، تأخذ cachedMeasureBlock(text, font, maxWidthPx, lineHeightPx, options, cache) وcachedMeasureRichBlock(spans, normalFont, boldFont, italicFont, boldItalicFont, maxWidthPx, lineHeightPx, options, cache) معاملات measureBlock وmeasureRichBlock إضافة إلى الذاكرة المؤقتة في آخرها.
#مقسِّم الأسطر (WebAssembly)
تُقسَّم الفقرات إلى أسطر بخوارزمية Knuth–Plass. منذ postext 1.33 ينفّذها المحرّك في قاطع أسطر مكتوب بلغة Rust ومترجَم إلى WebAssembly (30 كيلوبايت، داخل الحزمة). يختار مواضع القطع نفسها التي يختارها القاطع المكتوب بـTypeScript، بالحساب نفسه وبالترتيب نفسه، ويُنضَّد الكتاب كاملًا أسرع بنحو 15 %. لا يلزم أي إعداد:
- في worker وفي Node وفي Bun، تُترجَم الوحدة عند أول فقرة.
- في الخيط الرئيسي للصفحة، حيث لا يترجم المتصفح وحدة بهذا الحجم إلا بشكل غير متزامن، تُترجَم في الخلفية ويجيب القاطع المكتوب بـTypeScript حتى ذلك الحين. استدعاء
await initLineBreaker()قبل أول تنضيد يجعله يعمل من أول فقرة، ويُرجعfalseحيث لا يتوفر WebAssembly. - حيث لا يتوفر WebAssembly، أو ترفضه سياسة أمان المحتوى (
script-srcمن دون'wasm-unsafe-eval')، يجيب القاطع المكتوب بـTypeScript عن كل الفقرات.
يختار الاثنان مواضع القطع نفسها، فلا يتغيّر التنضيد أبدًا أيًّا كان الذي أجاب. useWasmLineBreaker(false) يُبقي القاطع المكتوب بـTypeScript، للمقارنة بينهما.
import { initLineBreaker, buildDocument } from 'postext';
await initLineBreaker(); // اختياري: أول صفّ يستخدمه أصلًا
const doc = buildDocument({ markdown }, config);#الحالة العامة المشتركة في صفحة واحدة
يعيش جزء من حالة Postext في متغيّرات على مستوى الوحدة. ويشترك فيها كل ما يستورد postext ضمن نطاق JavaScript نفسه (realm): فالصفحة ونصوصها البرمجية تتشارك نسخة واحدة، بينما لكل إطار iframe ولكل عامل نسخته الخاصة. ولا يلاحظ ذلك من يضع مستندًا واحدًا في الصفحة. أما من يضع عدة مستندات في صفحة واحدة، كمعاينتين حيّتين أو معرض أمثلة، فيلاحظه:
- صور الموارد. تملأ
registerResourceImage(fileId, image)سجلًا واحدًا مفهرسًا بـfileId، تقرؤهrenderPageوrenderPageToCanvas. فإذا سجّل مستندان كلاهماfigure.svgتشاركا ذلك المدخل: ويسري آخر تسجيل على كليهما. أعطِ معرّفات الملفات بادئة خاصة بكل مستند، واستدعِunregisterResourceImage(fileId)أوclearResourceImages()حين يزول مستند. والصور النقطية التي يخزّنها مُخرِج Canvas مفهرسة بالطريقة نفسها وتُحذف مع الصورة. - قياسات النص. تُخزَّن العروض المقيسة لكل سلسلة خط ونص على مستوى النطاق كله. وحين تصل أشكال عائلة أو تزول، يطرح المحرّك عروض تلك العائلة في كل المستندات (انظر تحميل الخطوط قبل الإخراج)؛ وتطرحها
clearMeasurementCache()كلها. - الإعدادات المستكمَلة. يُستكمل كل كائن إعدادات مرة واحدة وتُخزَّن النتيجة مقرونة بذلك الكائن. ويقارن كل بناء أولًا الكائنَ بالنص الذي كان عليه حين استُكمل (استدعاء
JSON.stringifyواحد، نحو 0.1 ms لإعدادات كتاب حجمها 55 KB و1.5 ms لإعدادات حجمها 240 KB)، فالإعدادات التي تُعدَّل في مكانها، على أي عمق (config.bodyText.fontSize = …، أو لون في لوحة الألوان)، تُستكمل من جديد. وتطرحinvalidateConfig(config)الاستكمال يدويًا. وتعطيstableStringifyوhashStringمفتاح محتوى لا يتوقف على ترتيب المفاتيح، للمضيفين الذين يخزّنون الإخراجات مؤقتًا بحسب الإعدادات. - لغة تقسيم الكلمات. يضبط كل بناء لغة تقسيم الكلمات بالواصلة على مستوى العملية كلها لتكون
bodyText.hyphenation.localeالخاصة بمستنده. وتستخدمhyphenateText(text)المُصدَّرة وlayoutDesignSlotلغة آخر بناء ما لم تمرّر لغة: استدعِhyphenateText(text, 'es'). - محرّك الرياضيات. هناك محرّك MathJax واحد وذاكرة مؤقتة واحدة للصيغ المرسومة في النطاق كله؛ وتشغّله
initMathEngine()للجميع. - قاطع الأسطر. هناك قاطع أسطر WebAssembly واحد في النطاق، يُترجَم مرة واحدة؛
useWasmLineBreaker(false)يعطّله للجميع.
أبسط طريقة للعزل نطاقٌ لكل مستند: إطار iframe لكل مثال حيّ (وتضمين CodePen واحد منها)، أو عامل إخراج لكل مستند للقياسات وتقسيم الكلمات (أما الصور فلا تزال تُسجَّل في الصفحة).
#مستندات Word (postext/word)
يكتب المسار الفرعي postext/word مستندات Word (.docx) ويقرؤها دون DOM، في المتصفح أو في Worker أو في Node. وعليه تقوم نوافذ Word في Sandbox، والأمران docx وimport-docx في سطر الأوامر (انظر سطر الأوامر › docx وimport-docx وSandbox › مستندات Word). منذ postext 1.68.
import { buildDocument } from 'postext';
import { semanticDocx, facsimileDocx, planWordFonts, isExportedDocx, applyDocxEdits } from 'postext/word';
import { decompressWoff2 } from 'postext-pdf';
const chapters = [{ id: 'ch1', title: 'Field notes', markdown }]; // المعرّفات نفسها عند التصدير والاستيراد
// منسَّق: نص متصل بتصميم الكتاب، مع تضمين خطوطه.
const fonts = await planWordFonts(faces, { decompressWoff2 }); // faces: { family, weight, style, files }[]
const formatted = await semanticDocx({ chapters, config, resources, resourceBytes, fonts, title: 'Field notes' });
// دلالي: النص نفسه محتوًى فقط، بأنماط Word بسيطة.
const semantic = await semanticDocx({ chapters, config, resources, resourceBytes, design: 'plain', title: 'Field notes' });
// نسخة طبق الأصل من الصفحات: الصفحات المخرَجة، كل سطر في مربع نص ثابت.
const docs = chapters.map((c) => buildDocument({ markdown: c.markdown, resources }, config));
const facsimile = await facsimileDocx({ docs, chapters, resources, resourceBytes, fonts });
// الملف المصحَّح، مدموجًا في الكتاب كما هو الآن.
if (isExportedDocx(edited)) {
const result = applyDocxEdits(edited, { chapters: current, resources });
for (const e of result.edits) console.log(e.status, e.reason ?? '', e.before, '→', e.after);
if (result.changed) save(result.chapters, result.resources);
}semanticDocx(options)تُرجع بايتات ملف.docx(Uint8Array). وتأخذchapters({ id, title?, markdown }) وconfigوresourcesمعresourceBytes(fileId)لبايتات صورها، وrasterizeSvg(svg, width, height)لصورة PNG التي يحتاجها Word بجانب SVG (ومن دونها يُستبعد SVG)، وfonts(خطة منplanWordFonts)، وtitleوauthorوdate(تاريخ ISO ثابت يجعل البايتات قابلة للتكرار)، وonWarningلما يصفّه Word على طريقته ({ code, message, chapter? }). وتحتاج الصيغ إلى محوّل من TeX إلى Word يُحمَّل عند أول استعمال؛ فإن تعذّر تحميله بقيت TeX مع تحذيرmathUnavailable. ويختارdesignالمظهر:'book'(الافتراضي) يصفّ النص بتصميم الكتاب بقدر ما يسمح Word، و'plain'يكتب المحتوى وحده، على صفحة A4 بعمود واحد وبخط Arial، بأنماط Word تسمّي كل جزء.facsimileDocx(options)تأخذdocs، أيVDTDocumentلكل فصل بترتيبchapters(سلسلة الطباعة التي يُرسم منها PDF)، وresourcesوresourceBytesوrasterizeSvgوfontsوtitleوauthorوdateوonWarningنفسها. ويعدّonProgress(done, total)الصفحات المكتوبة. وهي تكتب النسخة طبق الأصل من الصفحات: كل سطر في مربع نص ثابت كما يطبعه PDF، لمعاينة الإخراج في Word على سطح المكتب. وformattedDocxاسمها القديم، وهو باقٍ.planWordFonts(faces, options)تحوّل خطوط الكتاب ({ family, weight, style, files }: WOFF2 أو sfnt، بأي عدد من شرائح unicode-range) إلى خطوط TrueType الثابتة التي يضمّنها Word. وتقرأdecompressWoff2(التي يصدّرهاpostext-pdf) صيغة WOFF2؛ ويستبعدusedTextوfontStringsالشرائح والخطوط التي لا يستعملها التصدير؛ ويُضافfamilySuffix(افتراضيًا' PTX') إلى كل عائلة مضمَّنة. وتسمّيwarningsالخطوط المستبعدة (restrictedوcffوvariableوmissingوmerge-failed) والمضمَّنة للمعاينة والطباعة فقط (preview-print).isExportedDocx(bytes)تقول هل يحمل الملف خريطة التصدير، ولا ترمي خطأ أبدًا. وتقرأreadExportMap(files)الخريطة نفسها من الأجزاء المفكوكة (unzipSyncمن fflate): exportIdوvariantوengineوالفصول مع بصماتها ونسخة النص المصدَّر.applyDocxEdits(bytes, { chapters, resources })متزامنة. تُرجع كل الفصول بعد تطبيق التصحيحات (chapters)، ونسخًا عميقة من الموارد التي تغيّر تعليقها التوضيحي أو حاشيتها أو نصها البديل أو خلايا جدولها (resources)، وeditsوcommentsوvariantوexportIdوchanged. ولكل تعديلchapter، أوresourceIdوfield(captionوnoteوaltوcell:<الصف>:<العمود>)، وstartوendفي النص الحالي، وbeforeوafter، وkind(textوformatوparagraphوtracked)، وstatusمعreason: applied، أوconflict(changed-since-exportوtarget-missingوno-snapshotوoverlap)، أوrejected(generatedوformat-crosses-markupوformat-partialوbookmarks-lostوresource-removed). ولكل تعليقauthorوtextوموضعه (startقيمته -1 لتعليق لا يقع على نص مصدَّر). والملف الذي ليس.docxمصدَّرًا يرميDocxReadError. ويجب أن تكون معرّفات الفصول هي معرّفات التصدير: فالتعديل في فصل مجهول يُبلَّغ عنه ولا يُطبَّق.
وأي ملف Word آخر يُقرأ Markdown بقالب أنماط:
import { readDocx, parseTemplate, emptyTemplate, analyzeDocx, wordToPostext } from 'postext/word';
const word = readDocx(bytes); // Uint8Array أو ArrayBuffer
const template = parseTemplate(word.embeddedTemplate) ?? emptyTemplate();
const report = analyzeDocx(word, template, config); // report.verdict, report.findings
const { chapters, pictures, tables } = wordToPostext(word, {
template, config, chapters: 'split', existingIds: new Set(), untitledChapter: 'Untitled',
});readDocx(bytes)يقرأ الملف إلى نموذج Word: أنماطه وفقراته وحواشيه وصوره، وtitleالمستند، وقالب الاستيراد الذي يحمله الملف (embeddedTemplate، الذي كانت تكتبه صادرات Word في postext 1.67 وما قبله). والملف الذي ليس مستند Word يرميDocxReadError.wordToPostext(word, settings)يحوّل النموذج إلى فصول ({ title, markdown }) وصور وجداول. ويربط القالب كل نمط من أنماط Word بعنوان أو نمط فقرة أو إطار أو اقتباس أو تعليق في الإعدادات. ويفتحchapters: 'split'فصلًا عند كل عنوان من المستوى 1، ويُبقي'single'فصلًا واحدًا. وعلى المضيف أن يخزّن الصور (id،media.bytes،caption،alt) والجداول (id،model،caption) بوصفها موارد؛ ويذكرskippedPicturesصور EMF وWMF وTIFF التي تُركت.analyzeDocx(word, template, config)هو تقرير الجودة الذي يعرضه Sandbox قبل الاستيراد: الأنماط المستعملة، وعدد الفقرات التي لها نمط، وملاحظات مثلdirectFormattingوmanualHeadingsوtypedNumbering، لكل منها عدد وأمثلة.wordStyleTracking(word, template, config)وapplyStyleTracking(config, tracking)ينقلان تباعد الحروف في أنماط Word إلى أنماط الإعدادات التي لا تحدّده.
#حزم InDesign (postext-idml)
تكتب الحزمة postext-idml الصفحاتِ بعد إخراجها حزمةَ InDesign Markup (.idml)، ليُتمّ مصمّمٌ الكتابَ في InDesign، وتقرأ ملف .idml كتابًا في Postext. ويقوم التصدير، مثل النسخة طبق الأصل من الصفحات لـWord، على قائمة العرض الخاصة بالصفحة، دون DOM. وعليه يقوم الأمر idml في سطر الأوامر (انظر سطر الأوامر › idml). وهي حزمة مستقلة منذ postext 1.76 (npm install postext-idml؛ وعلى JSR @postext/idml) وتحتاج إلى postext 1.76 أو أحدث؛ ومن postext 1.71 إلى 1.75 كان التصدير هو المسار الفرعي postext/idml، الذي لم يعد موجودًا في 1.76.
import { buildDocument } from 'postext';
import { idmlDocument } from 'postext-idml';
const docs = chapters.map((c) => buildDocument({ markdown: c.markdown, resources }, config));
const { bytes, links } = idmlDocument({ docs, resourceBytes, images: 'embed', title: 'ملاحظات ميدانية' });idmlDocument(options)تُرجع بايتات الحزمة (bytes، وهيUint8Array)، ومعimages: 'link'الصورَ التي تُكتب بجانبها (links: { path, bytes }، بمسارات مثلLinks/photo.jpgنسبيةً إلى ملف.idml). وتأخذdocs(VDTDocumentلكل فصل، بترتيب الكتاب)، وresourceBytes(fileId)لبايتات الصور، وimages('embed'وهي القيمة الافتراضية، أو'link')، وtitle، وfontStyleName(family, weight, italic)لاسم الوجه في InDesign (يُشتقّ افتراضيًاRegularوBold Italic… من الوزن والميل؛ أعِد أسماء الأنماط الخاصة بالخطوط حين تختلف، مثلRoman)، وstyleNamesلأنماط فقرات النص الواقع خارج إطارات الصفحات المركّبة (بحسب الدور:bodyوheadingوlist…)، وforms(افتراضيًاtrue: الشارات التي تحمل حقل نموذج تصير حقول نماذج في InDesign)، وonWarning({ code, message }).lineBreaksقيمته'keep'(الافتراضية) أو'reflow'. مع'keep'ينتهي كل سطر حيث أنهاه Postext، بفاصل سطر إجباري، ونصُّه موسوم بعدم الانقسام وله تباعد أسطره الخاص، فيعرض InDesign الأسطر نفسها التي في PDF. ومع'reflow'يعيد منضِّد InDesign قطع الفقرات: الإطارات والأنماط والكلمات وخطوط الأساس الأولى من Postext، وقد تختلف فواصل الأسطر. وspreadsقيمته'facing'(الصفحات اثنتين اثنتين في كل صفحتين متقابلتين على جانبي الكعب، والأولى وحدها) أو'single'(صفحة واحدة في كل spread)؛ والقيمة الافتراضية'facing'في كتاب له هوامش صفحات متقابلة (page.margins.mirror) و'single'في غيره. وتعيدfontFile(family, weight, italic)ملف الخط لأحد الأوجه (بايتات TrueType أو OpenType؛ وملف WOFF2 بعد فكّ ترميزه): فتسمّي الحزمة حينئذ كل وجه كما يسمّيه جدول الأسماء في الملف، وبهذا الاسم يجده InDesign، ويحمل الناتجfonts({ path, bytes }، لتُكتب فيDocument fonts/<الملف>بجانب ملف.idml). ويكتبinlineObjects(الافتراضيtrue) الصيغ الرياضية والنوتة الموسيقية وعيّنات اللون داخل السطر كائناتٍ مثبّتة داخل السطر؛ ومعfalseتُترك، مع تحذيرtext.inline.- تقف الصفحات بمقاسها النهائي في صفحات متقابلة (spread) أو في spread من صفحة واحدة (
spreads)، في أقسام تحمل نمط أرقام الصفحات (عربية أو رومانية) والرقم الذي تبدأ به كل سلسلة، ونزف (bleed) الصفحة الأولى هو نزف المستند. وتصير الخطوط والمربعات والمسارات والصور خطوطًا ومستطيلات ومضلّعات وإطاراتِ رسوم؛ وتصير ألوان CMYK التي حدّدها المؤلف عيّناتِ ألوان رباعية (process)، بأسمائها في اللوحة حين يسمّيهاcolorPalette. - نص كل إطار من إطارات الصفحة المركّبة إطارُ نص واحد بقصة واحدة، بنمط فقرة يحمل اسم نمط الإطار؛ والإطارات المتسلسلة بـ
nextتشترك في قصة واحدة عبر إطارات نص مترابطة، والفقرة التي قسمها فاصل إطار تبقى فقرة واحدة. والنص خارج الإطارات المركّبة إطارُ نص لكل كتلة، في الموضع الذي وضعه فيه Postext. والإطار الذي صغّرت الملاءمةُ نصَّه (fit.shrinkText) يحتفظ بالأحجام والتباعد بين الأسطر بعد التصغير، وتصغر معها إزاحاته ومواضع الجدولة والمسافات بين الفقرات (أما الحشوة الداخلية للإطار فلا). وعلامة عنصر القائمة تفتتح فقرته، يليها حرف جدولة، مع إزاحة معلّقة. وتحتفظ الفقرة بإزاحاتها (اليسرى وإزاحة السطر الأول واليمنى، مقروءةً من حيث وضع Postext أسطرها)، وبمواضع الجدولة مع محاذاتها وأحرف التعبئة (leaders)، وبالمسافة التي تليها؛ ويأخذ نمط الفقرة قيم فقرتها الأولى، وتصير الحشوة الداخلية للإطار هامشًا داخليًا لإطار النص. ويبقى فاصل السطر الإجباري كما هو. وتبقى كلمات الشارة في النص، ويصير مربعها (التعبئة والحدّ) مستطيلًا خلفها، والشارة الفارغة فسحةٌ من مسافات رفيعة. - الشارة التي تحمل حقل نموذج (
field="…"، انظر مخرجات PDF › حقول النماذج) تصير حقلَ نموذج في InDesign فوق مربعها، مرسومًا بتعبئة الشارة وحدّها: مربع نص للنص والأرقام (باسم الحقل، وبحجم نص الشارة، معmultilineوreadonlyوrequiredوtooltip)، ومربع تحرير وسرد للاختيار (مع خياراته)، وخانة اختيار بمظهريها (مؤشَّر عليها افتراضيًا حين تقول قيمتها ذلك). وتُستبعد كلمات الحقل من النص، ويبقى مكانها فارغًا. ولا تحمل حقول النماذج في InDesign قيمة افتراضية ولا تنسيق أرقام ولا حسابًا ولا محاذاة، فتنتقل هذه في تسميات البرامج النصية (script labels) للحقل (postext:valueوpostext:format، وpostext:calcمكتوبًا كما تُكتب السمةcalc، بما في ذلك الأرقام والحسابات المتداخلة)، مع تحذيرfield.valueأوfield.script. ومعforms: falseتُكتب هذه الشارات كأي شارة أخرى، والقيمة نصًّا. - الجدول جدولٌ في InDesign؛ والإطار المستدير الزوايا لجدول يُكتب قائم الزوايا (
table.radius). والصيغ الرياضية والنوتة الموسيقية وعيّنات اللون داخل السطر كائنات مثبّتة في سطرها. والروابط ارتباطات تشعبية في InDesign، إلى عنوان URL أو إلى صفحة. ومع الأسطر المحفوظة يُكتب النص المكتوب من اليمين إلى اليسار في قصص من اليمين إلى اليسار؛ ومعlineBreaks: 'reflow'يُكتب من اليسار إلى اليمين، مع تحذيرtext.rtl. ويُكتب النص العمودي في قصص عمودية، كل عمود من الحروف سطرًا؛ وما لا يصل إلى InDesign (نقاط التوكيد) يصدر عنه تحذيرtext.vertical.*. وتوضع صورة SVG بصيغة SVG، التي يقرؤها InDesign 2020 وما بعده (image.svg).
وفي الاتجاه الآخر، تقرأ idmlToPostext ملف .idml وتعيد فصول كتاب Postext (Markdown) وإعداداته وموارده، مع تقرير بما قُرئ وبما ليس له مقابل في Postext:
import { createBundle } from 'postext/bundle';
import { idmlToPostext, importBundleInput } from 'postext-idml';
const result = idmlToPostext(bytes, { layout: 'auto', linkBytes: (link) => pictures.get(link.name) });
console.log(result.report.verdict, result.report.findings);
const { bytes: book } = await createBundle(importBundleInput(result));idmlToPostext(bytes, options)دالة متزامنة.layoutقيمته'pages'(صفحات مركّبة تتبع الأصل صفحةً صفحة) أو'flow'(كتاب بنص متدفق) أو'auto'(الافتراضية: يختار المستورد ويذكر سببه فيreason). وتقدّمlinkBytes(link)بايتات صورة مرتبطة (link.name،link.uri)؛ والصور المضمّنة تُقرأ من الحزمة، والروابط التي بقيت بلا بايتات تُسرد فيmissingLinks. ويحمل الناتجchapters({ title, markdown }) وconfig(ما يحدّده المستند فقط) وresourcesمعfilesالخاصة بها وfontsالتي يحتاج إليها الكتاب (الأسماء فقط: ملف.idmlلا يحمل ملفات خطوط) وreport: فيهverdict(faithfulأوapproximateأوlossy) وfindings، لكل منهاseverity(info،warning،loss) وmessageوcountوexamples. وimportBundleInput(result)هو مُدخَلcreateBundleمنpostext/bundle.- الأسطر التي ينهيها الأصل بفواصل أسطر إجبارية تبقى أسطر الكتاب: يفعّل المستورد
bodyText.justifyHardBreaks. والكتاب المصدَّر من Postext يعود بالأسطر نفسها. والمستند المصنوع في InDesign يُقرأ مع فقد، يسرده التقرير. وسطر الأوامر يستورد بالأمرpostext import-idml، وSandbox من قائمة «جديد» في لوحة الكتب؛ وتبقى مهارة الوكيل الطريقة الموصى بها لاستنساخ تخطيط الأصل، وتقارن صفحة InDesign: الاستيراد والتصدير والنقل بين الطريقين. وspreadsخيار في سطر الأوامر أيضًا (--spreads) منذ postext 1.78. readIdml(bytes)وinspectIdml(doc)هما القارئ المنمَّط وحده: الحزمة في صورةIdmlDocument، وملخّص لها (الصفحات والقصص والخطوط والأنماط المستعملة والصور).
#تشغيل الإخراج في Web Worker
هذه هي الطريقة الموصى بها لاستخدام Postext في المتصفح. إذا كنت تبني أي شيء تفاعلي، كمعاينة حيّة أو محرّر أو عارض يستجيب لتغيّر المقاس أو ساحة تجريب على غرار Sandbox، فشغّل خطّ المعالجة عبر createLayoutWorker() من postext/worker. لا تستدعِ buildDocument مباشرة على الخيط الرئيسي في شيفرة واجهة المستخدم.
استدعاء buildDocument على الخيط الرئيسي يُشغّل خطّ المعالجة كاملًا، من تحليل وقياس وتوزيع وكل إعادة تشغيل لتمريرة التوزيع يحتاج إليها الإخراج، على الخيط الذي استدعاه أيًّا كان. وهذا مقبول للتصدير الذي يجري مرة واحدة. أما في واجهة تفاعلية فهو الخيط الخطأ: فإخراج يستغرق 150 ms يحجب أحداث الإدخال، فتتراكم ضغطات المفاتيح ويتقطّع التمرير. والعامل ينقل كل واحدة من تلك الأجزاء من الثانية إلى خيط في الخلفية.
يأتي Postext بنقطة دخول مخصّصة لعامل الويب هي postext/worker، تُخرج خطّ المعالجة من الخيط الرئيسي. وهي المسار الذي نتوقع أن تستخدمه غالبية عمليات التكامل: فمساحات عرض Canvas وHTML وPDF في Sandbox تتشارك جميعها مقبض createLayoutWorker() نفسه عبر خطّاف useLayoutWorker واحد (packages/postext-sandbox/src/worker/useLayoutWorker.ts) وتشغّله بإلغاء «الأحدث يفوز»، فتُلغي ضغطة المفتاح الجديدة البناء الجاري قبل أن ينتهي.
باختصار، التكامل المعتمد هو:
- أنشئ عاملًا مرة واحدة لكل مساحة عرض باستخدام
createLayoutWorker(). - سجّل الخطوط مرة واحدة لكل عائلة بإرسال كائنات
ArrayBufferقابلة للنقل عبرregisterFonts(payloads). - ابنِ باستخدام
build(content, config, { signal })، ممرّرًاAbortSignalجديدًا في كل استدعاء كي يمكن إلغاء عمليات البناء القديمة. - استبدل أي بناء سابق بإلغاء إشارته قبل بدء البناء التالي؛ وهذا هو نمط «الأحدث يفوز».
- تخلّص من العامل حين يُفكّ تركيب المكوّن الذي يملكه.
ويغذّي كائن VDTDocument نفسه العائد من build(...) كل المُخرِجات اللاحقة: renderPage/renderPageToCanvas لـCanvas، وrenderToHtmlIndexed لـHTML، وrenderToPdf (من postext-pdf) لـPDF. فتبني مرة واحدة في العامل وتحوّل إلى صور نقطية بقدر ما تحتاج الواجهة على الخيط الرئيسي.
#ما يقدّمه لك العامل
- يبقى الخيط الرئيسي حرًّا. يجري التحليل والقياس وكل تمريرات التوزيع داخل العامل. ولا يُمسّ الخيط الرئيسي إلا حين يُرسَل
VDTDocumentالمكتمل إليه. - إلغاء «الأحدث يفوز». يمرّر
build(content, config, { signal })إشارةAbortSignalإلى العامل. والإلغاء قبل الاكتمال يُطلقAbortErrorفي الجانب الرئيسي؛ وداخل العامل يرمي خطّ المعالجةBuildCancelledErrorعند نقطة فحص الإلغاء التالية الخاصة بكل كتلة ويتوقف فورًا. - ذاكرة قياس مؤقتة لكل عامل. يحتفظ العامل بكائن
MeasurementCacheواحد طوال عمره. وعمليات البناء اللاحقة التي تتشارك الخط والنص والعرض تعيد استخدام قياسات الأسطر المخزّنة، فكتابة حرف واحد في مستند طويل لا تعيد قياس إلا الكتل التي تغيّرت مدخلاتها فعلًا. - مقاييس مطابقة لمقاييس الخيط الرئيسي. تُرسَل الخطوط إلى العامل على هيئة كائنات
ArrayBufferقابلة للنقل وتُسجَّل عبرnew FontFace(...)فيFontFaceSetالخاص بالعامل. ويقيس العامل بمقاييس خطوط Canvas نفسها التي كان الخيط الرئيسي سيستخدمها، فتتطابق مواضع تقسيم الأسطر وارتفاعات الأعمدة بايتًا ببايت. - تبقى ذاكرة الصور النقطية للرياضيات قائمة عبر عمليات البناء في العامل. يأتي راسم الصيغ الرياضية بذاكرة صور نقطية مفهرسة بالمحتوى إلى جانب الذاكرة المفهرسة بالهوية، إذ إن الاستنساخ البنيوي لكائن
MathRenderعبر حدود العامل كان سيُفوّت ذاكرة الهوية في كل إعادة بناء. - الأسطر نفسها التي في الصفحة. عنصر Canvas المُنشأ في عامل ليس له صفحة يأخذ منها لغة، والخط يُجيب برسوم أخرى بحسب اللغة. يضبط المحرّك لغة المستند (
locale) على كل سياق يقيس به، في العامل كما في الصفحة، فيعيدbuild()الأسطر التي يعطيهاbuildDocumentفي صفحة بأي لغة (bodyText.shapingLanguage: 'document'، وهي القيمة الافتراضية منذ postext 1.30). ومع'host'، وهي القيمة التي يحتفظ بها الإعداد المحفوظ قبل 1.30، يقيس العامل بلا لغة والصفحة بلغتها، كما كان حتى postext 1.28.
#الواجهة البرمجية العامة
يقع عميل العامل في المسار الفرعي postext/worker، وهو مجموعة قليلة من الأسماء:
createLayoutWorker(opts?): LayoutWorkerHandle: ينشئ عاملًا مخصّصًا (أو يغلّف عاملًا تمرّره عبرopts.worker، أو يشغّل مدخل العامل الموجود فيopts.url) ويُعيد مقبضًا محدّد الأنواع. انظر تحميل العامل من CDN.LayoutWorkerHandle.registerFonts(faces: FontPayload[]): Promise<void>: يرسل بايتات الخطوط إلى العامل. تُنقل المخازن (buffers)، فاحتفظ بنسخة جديدة على الخيط الرئيسي إن احتجت إلى إعادة إرسالها لاحقًا.LayoutWorkerHandle.unregisterFonts(families: string[]): Promise<void>: يحذف من العامل أشكال خطوط تلك العائلات، فيسريregisterFontsالتالي لعائلة منها بدل أن يُطابَق بالشكل الذي يحمله العامل من قبل.LayoutWorkerHandle.build(content, config?, options?): Promise<VDTDocument>: يشغّل خطّ المعالجة. وoptionsهو{ signal?, onProgress?, onStats?, resourcesKey?, cacheKey? }. وإلغاءsignalيُلغي البناء الجاري. ويُستدعىonProgress({ pass, blocks, totalBlocks, pages })كلما تقدّم وضع الكتل؛ ويتلقىonStats({ passes, totalMs, cached?, missingFonts? })توقيتات مراحل البناء المكتمل. وresourcesKeyبصمة لـcontent.resources: فعمليات البناء المتتالية بالمفتاح نفسه ترسل القائمة مرة واحدة، ويحتفظ بها العامل. وcacheKeyبصمة للبناء كله: يحتفظ العامل بآخر بضعة مستندات بحسبها، ويجيب البناءَ الذي يحمل مفتاحًا عنده من تلك الذاكرة المؤقتة.LayoutWorkerHandle.warm(content, config, { cacheKey, … }): Promise<void>: يبني في ذاكرة المستندات المؤقتة في العامل دون أن يعيد المستند، لفصل قد يفتحه القارئ بعد ذلك؛ ويُجابbuildالتالي بذلكcacheKeyمن الذاكرة المؤقتة.LayoutWorkerHandle.prepareFonts(content, config?, options?): يشغّلprepareFontsفي الصفحة، ثم يرسل إلى العامل أشكال الخطوط التي وجدها؛ انظر تحميل العامل من CDN.LayoutWorkerHandle.dispose(): void: يُنهي العامل ويرفض أي عمليات بناء معلّقة بـAbortError.FontPayload:{ family, weight, style, unicodeRange?, buffer: ArrayBuffer }.weightسلسلة وزن CSS ('700'،'bold')؛ وتقبلهregisterFontsأيضًا رقمًا (700). ويُنقلbufferإلى العامل حين تستدعيregisterFonts.BuildCancelledError(يُعاد تصديره منpostext): ما ترميهbuildDocumentداخليًا حين تُعيدoptions.shouldCancelالقيمةtrue. لا تراه عادة على الخيط الرئيسي: فبروتوكول العامل يحوّله إلىAbortErrorقبل أن يصل إلى شيفرتك.
وتنشر الحزمة أيضًا مسار postext/worker/entry الذي يشير إلى سكربت العامل المُصرَّف. وتحلّ createLayoutWorker() عنوان URL هذا تلقائيًا؛ ولا تحتاج إلى الإشارة إليه صراحة إلا حين تتطلب أداة التجميع لديك استدعاء new Worker(new URL(...), { type: 'module' }) مكتوبًا يدويًا، أو حين تقدّم المدخل بنفسك (opts.url).
#التكامل الأدنى
import { createLayoutWorker } from 'postext/worker';
import type { FontPayload, LayoutWorkerHandle } from 'postext/worker';
import type { PostextConfig, VDTDocument } from 'postext';
// 1. Create the worker once and keep the handle for the lifetime of your viewport.
const layout: LayoutWorkerHandle = createLayoutWorker();
// 2. Register fonts once per family (transferable ArrayBuffers).
// getConfigFontFamilies(config) is a helper that lists the families your config will render.
const payloads: FontPayload[] = await collectFontPayloadsForFamilies([
'EB Garamond',
'Open Sans',
]);
await layout.registerFonts(payloads);
// 3. Drive builds with last-wins cancellation: abort the previous signal
// before starting a new build. A stale build is thrown away inside the worker.
let pending: AbortController | null = null;
async function rebuild(
markdown: string,
config: PostextConfig,
): Promise<VDTDocument | null> {
pending?.abort();
pending = new AbortController();
try {
return await layout.build({ markdown }, config, { signal: pending.signal });
} catch (err) {
if ((err as { name?: string } | null)?.name === 'AbortError') return null;
throw err;
}
}
// 4. Dispose when the component that owns the worker unmounts.
// Pending builds reject with AbortError.
layout.dispose();وحين يُغلَّف في مكوّن React يكون شكله:
import { useEffect, useRef } from 'react';
import { createLayoutWorker } from 'postext/worker';
import type { LayoutWorkerHandle } from 'postext/worker';
import { renderPageToCanvas } from 'postext';
import type { PostextConfig } from 'postext';
export function CanvasPreview({
markdown,
config,
}: {
markdown: string;
config: PostextConfig;
}) {
const canvasRef = useRef<HTMLCanvasElement | null>(null);
const workerRef = useRef<LayoutWorkerHandle | null>(null);
const pendingRef = useRef<AbortController | null>(null);
// Mount: spin up the worker and ship the fonts once.
useEffect(() => {
const handle = createLayoutWorker();
workerRef.current = handle;
(async () => {
const payloads = await collectFontPayloadsForFamilies(
getConfigFontFamilies(config),
);
await handle.registerFonts(payloads);
})();
return () => {
pendingRef.current?.abort();
handle.dispose();
};
}, []); // fonts registered once; re-register only when the family set changes
// Every keystroke or config change: supersede the in-flight build and kick a new one.
useEffect(() => {
const handle = workerRef.current;
if (!handle) return;
pendingRef.current?.abort();
const ac = new AbortController();
pendingRef.current = ac;
(async () => {
try {
const vdt = await handle.build({ markdown }, config, { signal: ac.signal });
const canvas = canvasRef.current;
if (!canvas || !vdt.pages[0]) return;
renderPageToCanvas(vdt.pages[0], vdt, canvas); // rasterise on the main thread
} catch (err) {
if ((err as { name?: string } | null)?.name !== 'AbortError') throw err;
}
})();
}, [markdown, config]);
return <canvas ref={canvasRef} />;
}النمط واحد دائمًا: أنشئ مرة واحدة، وسجّل الخطوط مرة واحدة، وابنِ مع AbortSignal مرات كثيرة، وتخلّص من العامل عند فكّ التركيب.
#تحميل العامل من CDN
يجب أن يأتي سكربت العامل من أصل الصفحة نفسه، لذا لا تستطيع نسخة من postext/worker تقدّمها شبكة توصيل محتوى (CDN) أن تشغّل الملف layout.worker.js المجاور لها. وتعالج createLayoutWorker() ذلك:
- esm.sh، دون خيارات. حين يكون
postext/workerنفسه قد حُمّل من esm.sh (ويكون عنوان URL لوحدته مثلhttps://esm.sh/postext@1.5.0/es2022/worker.mjs)، يشغّل العميلhttps://esm.sh/postext@1.5.0/worker/entryالمقابل عبر وحدة blob من سطر واحد ومن الأصل نفسه تستورده. ويصحّ الأمر نفسه على الاستيرادات التي تضيف?deps=أو?external=أو?alias=، وعلى الصيغةhttps://esm.sh/*postext@1.5.0/worker. ويحصل العامل دائمًا على البناء العادي لذلك الإصدار، لأن العامل لا يملك خريطة استيراد (import map) يحلّ بها التبعيات الخارجية. - أي خادم آخر، مع
url. لا تُكتشف شبكات CDN الأخرى، مثل jsDelivr (/+esm) أو unpkg. وتشغّلcreateLayoutWorker({ url })وحدة مدخل العامل الموجودة فيurl: مباشرة إن كان العنوان من الأصل نفسه، وعبر غلاف blob نفسه إن كان من أصل آخر. ويجب أن يسمح ذلك الخادم بالطلبات عبر الأصول (CORS). - أدوات التجميع لا تغيّر شيئًا. مع Vite أو webpack أو Next.js، واصل استدعاء
createLayoutWorker()دون خيارات: فهي تُخرج العامل جزءًا (chunk) من تطبيقك.
import { createLayoutWorker } from 'https://esm.sh/postext/worker';
const layout = createLayoutWorker();
const face = async (weight, style) => ({
family: 'EB Garamond',
weight,
style,
buffer: await (await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/eb-garamond@5/files/eb-garamond-latin-${weight}-${style}.woff2`)).arrayBuffer(),
});
await layout.registerFonts(await Promise.all([face(400, 'normal'), face(700, 'normal'), face(400, 'italic')]));
const doc = await layout.build({ markdown }, { bodyText: { fontFamily: 'EB Garamond' } });لا يرى العامل خطوط الصفحة. فله مجموعة خطوط خاصة به لا تحوي إلا أشكال الخطوط المرسلة عبر registerFonts والخطوط المثبّتة على النظام. وحين يُنضّد بناءٌ نصًا بعائلة لا يجدها العامل، يُقاس ذلك النص بخط بديل، فلا تتطابق مواضع تقسيم أسطره مع الصفحة. ويطبع العميل حينئذ تحذيرًا واحدًا في وحدة التحكم لكل عائلة ("EB Garamond" is not available inside the layout worker…)، ويسرد العائلات في BuildStats.missingFonts، التي يتلقاها رد النداء onStats الخاص بـbuild. ويذكر المستند نفسه أشكال الخطوط ذاتها في تحذيرات محتوى من نوع fontFallback.
تشغّل handle.prepareFonts(content, config, options) الدالة prepareFonts في الصفحة، ثم ترسل إلى العامل ملفات كل شكل خط يحفظه سجل الخطوط (ملفات المحلِّل، وأشكال الحزمة، وقواعد @font-face المقروءة في الصفحة)، ولا ترسل من الشرائح إلا ما يحوي محارف المستند. وحين تصل أشكال الخطوط إلى العامل، يطرح قياسات تلك العائلات وحدها وذاكرته المؤقتة للمستندات المنجزة.
وقد تصل أشكال الخطوط إلى العامل بعد إخراج أيضًا: وزن تبيّن أن الصفحات تحتاج إليه، أو شريحة unicode-range أخرى من الوزن نفسه، أو ملف رُفع من جديد باسم العائلة نفسه. والإخراج التالي يقيس بها. ولا يفعل canvas العامل ذلك من تلقاء نفسه: ففي Chrome يحلّ الخط أول مرة تُسند إليه صيغة الخط المختصرة، ولا يعود إلى مجموعة الخطوط من أجل تلك الصيغة، فيبقى النص بعروض شكل الخط الذي أجاب أولًا. لذلك يكتب العامل اسم العائلة مرة أخرى في الصيغ التي يسندها بعد أن يصل شكل من تلك العائلة متأخرًا (Geist, Geist): قائمة عائلات أخرى في نظر canvas، والخط نفسه والعروض نفسها. والمستندات التي يعيدها تحتفظ بسلاسل الخطوط كما يكتبها المحرّك، والعامل الذي تصله أشكال خطوطه قبل أول إخراج يسند كل صيغة كما هي.
#جمع بيانات الخطوط (Fontsource / Google Fonts)
تأخذ registerFonts بايتات الخطوط الخام. والخيط الرئيسي هو المكان المناسب لجلبها، لأن ذاكرة مؤقتة مركزية تتيح لعدة نُسخ من العامل أن تتشارك البايتات نفسها.
ودالة collectFontPayloadsForFamilies في Sandbox (packages/postext-sandbox/src/controls/fonts/fontLoader.ts) تطبيق مرجعي. وهي:
- تستعلم
https://api.fontsource.org/v1/fonts/{family-id}لمعرفة الأوزان والأنماط التي تملكها العائلة. - تقرأ المجموعات الفرعية للعائلة ونطاق
unicode-rangeلكل منها من حزمتها على jsDelivr (@fontsource/{family-id}@5/400.css)، مرة لكل عائلة. ثم تُطلب الملفات من الإصدار المحدد الذي أُجيب منه عن ورقة الأنماط تلك (x-jsd-versionمن jsDelivr)، فلا تصل العائلة أبدًا من إصدارين من حزمتها. - تنزّل كل ملفات الشكل العادي والعريض ومائليهما لكل عائلة (
files/{family-id}-{subset}-{weight}-{style}.woff2)؛ أماcollectFontPayloadsForConfig(config, markdown)فتأخذ الأوزان والأنماط التي تطلبها الإعدادات. وهي ملفات ثابتة، هي التي يضمّنها ملف PDF، فيقيس العامل بما يرسم به PDF. والملف المتغيّر يعطي عروض تقدّم أخرى بين اثنين من أصوله (masters)، فينقسم في موضع آخر السطرُ الذي لا يفصله عن طول السطر إلا جزء من البكسل. - تُعيد
FontPayload[]يكون فيهاbufferكائنArrayBufferجديدًا في كل استدعاء، وهذا مهم لأنregisterFontsتنقل المخزن وتترك النسخة في جانب المُرسِل منفصلة (detached).
تُرتَّب ملفات الوزن والنمط الواحد كما يعلنها مثال CodePen من دليل الوصفات: latin أولًا وملفات الكتابة نفسها آخرًا (arabic، والشرائح المرقّمة لعائلة صينية أو يابانية)، لأن الملف المضاف أخيرًا هو الذي يجيب عن محرف موجود في ملفين. والعائلة التي لا ملفات لها في Fontsource تُقرأ من ورقة أنماط Google CSS2، وهي لا تُعيد WOFF2 إلا لسلاسل User-Agent الشبيهة بالمتصفحات.
واقرنها بـgetConfigFontFamilies(config) للحصول على قائمة العائلات التي سيرسمها إعداد PostextConfig معيّن فعلًا (نص المتن، والعناوين، ورموز القوائم النقطية، وأرقام القوائم المرقّمة).
#الإلغاء التعاوني داخل المحرّك
إذا كنت تشغّل buildDocument بنفسك، داخل عامل مخصّص مثلًا، فإن خطّ المعالجة يتيح خطّاف shouldCancel يمكنك استخدامه مباشرة:
import { buildDocument, BuildCancelledError } from 'postext';
let superseded = false;
try {
const vdt = buildDocument(content, config, cache, {
shouldCancel: () => superseded,
});
} catch (err) {
if (err instanceof BuildCancelledError) return; // a newer build took over
throw err;
}تُستدعى shouldCancel مرة واحدة لكل كتلة من المستوى الأعلى أثناء التوزيع. والخطّاف تعاوني عن قصد: فهو لا يستطيع إيقاف استدعاء الإخراج الخاص بمكتبة pretext في منتصف سطر، لكنه يُبقي دقة الإلغاء صغيرة بما يكفي (أجزاء من الثانية) كي لا ينتظر مستخدمٌ سريع الكتابة بناءً قديمًا أبدًا.
#تصدير PDF انطلاقًا من العامل
يأخذ مُخرِج PDF كائن VDTDocument جاهزًا ويحوّله إلى بايتات PDF. وهو لا يعيد تشغيل الإخراج. ويعني ذلك أن مسار PDF المعتمد في المتصفح يقترن بالعامل اقترانًا طبيعيًا: ابنِ VDT في العامل (بعيدًا عن الخيط الرئيسي، وقابلًا للإلغاء، ومعيدًا استخدام الذاكرة المؤقتة)، ثم استدعِ renderToPdf على الخيط الرئيسي على VDT نفسه.
import type { LayoutWorkerHandle } from 'postext/worker';
import { renderToPdf } from 'postext-pdf';
import type { PostextConfig } from 'postext';
import { createPdfFontProvider } from './pdfFontProvider';
const fontProvider = createPdfFontProvider();
export async function exportPdf(
layout: LayoutWorkerHandle,
markdown: string,
config: PostextConfig,
): Promise<Uint8Array> {
// 1. Build the VDT in the worker — UI stays responsive during the layout passes.
const vdt = await layout.build({ markdown }, config);
// 2. Rasterise to PDF on the main thread. renderToPdf is fast once the VDT exists
// because it is walking precomputed coordinates, not remeasuring text.
return renderToPdf(vdt, {
fontProvider,
// pdfGeneration config on `vdt.config` is honoured automatically.
});
}إذا كنت تحتفظ أصلًا بمقبض عامل للمعاينة الحيّة، فأعد استخدامه للتصدير بدلًا من تشغيل عامل ثانٍ، فذاكرة القياس المؤقتة داخل العامل تجعل تصدير PDF الذي يلي معاينة على الشاشة شبه مجاني.
وفي الكتاب الطويل، تستغرق كتابة ملف PDF نفسه ثواني أيضًا؛ ويشغّل postext-pdf/worker تلك الخطوة على عامل خاص بها (انظر رسم PDF على عامل).
#متى تستخدم العامل ومتى لا تستخدمه
استخدم العامل في:
- المعاينات الحيّة والمحرّرات وساحات التجريب. أي حالة يُعاد فيها بناء المستند استجابةً لإدخال المستخدم.
- عارضات HTML التي تستجيب لتغيّر المقاس وتعيد تشغيل الإخراج مع كل نبضة من
ResizeObserver. - تصدير PDF داخل المتصفح حين يُطلق من واجهة فيها معاينة حيّة أصلًا؛ أعد استخدام مقبض العامل الموجود كي يستفيد التصدير من ذاكرة القياس المؤقتة.
- تبويبات إخراج متعددة تحتاج جميعها إلى VDT نفسه (مساحات عرض Canvas / HTML / PDF في Sandbox تتشارك مقبض عامل واحدًا لكل تركيب لمساحة العرض).
واستغنِ عن العامل في:
- التوليد على جانب الخادم: لا يملك Node كائن
FontFaceSetالخاص بالمتصفح، وأنت تتحكم في الخيط على أي حال. - عمليات التصدير المعزولة التي تجري مرة واحدة (أداة سطر أوامر، أو سكربت تصدير بلا واجهة، أو Cloud Function) حيث لا توجد واجهة تفاعلية يمكن حجبها. فاستدعاء
buildDocumentمباشرة أبسط ويتجنّب كلفة النقل الأولي للخطوط.