# الاستخدام البرمجي: HTML وFolio وEPUB
> الكتاب المُخرَج داخل صفحة ويب، وكتابًا ثلاثي الأبعاد مع postext-folio، وبصيغة EPUB 3 ثابتة التخطيط أو متدفقة مع postext-epub
- نسخة HTML: https://postext.dev/ar/docs/configuration-html-folio-epub
- آخر تحديث: 2026-10-16
- مدة القراءة: 17 دقيقة
- لغات أخرى: [en](https://postext.dev/en/docs/configuration-html-folio-epub.md), [es](https://postext.dev/es/docs/configuration-html-folio-epub.md), [ca](https://postext.dev/ca/docs/configuration-html-folio-epub.md), [de](https://postext.dev/de/docs/configuration-html-folio-epub.md), [fr](https://postext.dev/fr/docs/configuration-html-folio-epub.md), [it](https://postext.dev/it/docs/configuration-html-folio-epub.md), [pt](https://postext.dev/pt/docs/configuration-html-folio-epub.md), [zh](https://postext.dev/zh/docs/configuration-html-folio-epub.md), [ja](https://postext.dev/ja/docs/configuration-html-folio-epub.md)
## باختصار
هذه الصفحة لمن يكتبون الشيفرة ويريدون عرض كتاب على الشاشة. يضع القسم الأول الصفحات داخل صفحة ويب، ويشرح كيف يختلف هذا العرض عن Canvas وPDF. ويعرض القسم الثاني الكتاب بالأبعاد الثلاثة، مفتوحًا على مكتب، بصفحات يقلّبها القارئ. ويصنع القسم الأخير كتابًا إلكترونيًا بصيغة EPUB، بصفحات ثابتة أو بنص يتدفق ليناسب الشاشة، ثم يفحص الملف.
## دمج عارض HTML
عارض HTML هو مُخرِج Postext المصمَّم للشاشة أولًا. فبدلًا من تحويل الصفحات إلى صورة نقطية، يُنتج عُقد DOM ذات مواضع مطلقة تحدّد هندستَها سلسلةُ المعالجة نفسها التي تُنتج مخرجات الطباعة. وهذا يجعله الخيار المناسب حين تريد في المتصفح تنضيدًا مقروءًا وقابلًا للتحديد ويستجيب لتغيّر المقاس، في تطبيق قراءة أو معاينة داخل منتج أو واجهة توثيق مضمّنة، دون الحاجة إلى عارض PDF.
العناصر الأساسية من الواجهة البرمجية العامة:
- **`buildDocument(content, config, cache?)`**: يشغّل خطّ معالجة الإخراج كاملًا ويُعيد `VDTDocument`.
- **`renderToHtmlIndexed(doc, options)`**: يحوّل VDT إلى سلسلة HTML واحدة مع تفصيل لكل صفحة ولكل كتلة. ويتيح هذا التفصيل ترقيع DOM بكلفة زهيدة حين لا تتغيّر بين عمليتَي عرض إلا كتل قليلة.
- **`resolveHtmlViewerConfig(partial)`**: يملأ القيم الافتراضية لعارض HTML (`maxCharsPerLine`، `columnGap`، `optimalLineBreaking`).
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`**: أدوات قياس أولية تُستخدم لاستنتاج عرض عمود فعلي بالبكسل من عدد حروف مستهدف.
- **`createMeasurementCache` / `clearMeasurementCache`**: ذاكرات مؤقتة قابلة للتوصيل تتيح لك إعادة استخدام القياسات عبر عمليات إعادة الإخراج.
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`**: تحمّل أوجه المستند قبل الإخراج وتعيد الإخراج حين تصل أوجه جديدة (انظر [تحميل الخطوط قبل الإخراج](https://postext.dev/ar/docs/configuration-programmatic-usage.md#تحميل-الخطوط-قبل-الإخراج)).
### مثال حيّ: سلسلة HTML
الدورة الكاملة بلغة JavaScript المجرّدة، قبل التكامل مع React أدناه: ابنِ المستند، وسلّم `VDTDocument` إلى `renderToHtml`، وضع السلسلة في حاوية. يرصّ `mode: 'single'` الصفحات عموديًا؛ ويمنحها `background` لونًا، لأن الصفحات شفافة افتراضيًا. ويطبع المثال على CodePen أيضًا الترميز المولَّد، فترى الأسطر ذات المواضع المطلقة التي يُنتجها المُخرِج، والتي يرسمها المتصفح دون أن يعيد تدفّقها أبدًا.
> **مثال قابل للتشغيل: Postext · تحويل مستند إلى HTML** — أخرِج مستند markdown باستخدام postext وحوّله إلى سلسلة HTML. ([الشيفرة](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### التكامل الأدنى
المقتطف أدناه أقصر تكامل مفيد: ابنِ المستند بمقاس مساحة العرض الحالي، وارسمه في حاوية، وأعد التشغيل عند تغيّر المقاس.
```tsx
import { useEffect, useRef } from 'react';
import {
buildDocument,
renderToHtmlIndexed,
resolveHtmlViewerConfig,
buildFontString,
measureGlyphWidth,
dimensionToPx,
createMeasurementCache,
watchFonts,
onFontsChanged,
} from 'postext';
import type { PostextConfig, MeasurementCache } from 'postext';
// Screen-friendly DPI: at 144 DPI, an 8pt body size resolves to 16 px.
const HTML_DPI = 144;
const PADDING_PX = 24;
// Prose sample used to measure the target column width. Proportional fonts
// make "N × average width" unreliable, so we measure a representative string.
const SAMPLE =
'The quick brown fox jumps over the lazy dog. Sphinx of black quartz, judge my vow.';
function sampleForChars(n: number): string {
let s = SAMPLE;
while (s.length < n) s += ' ' + SAMPLE;
return s.slice(0, n);
}
export function PostextHtmlViewer({
markdown,
config,
mode = 'multi',
}: {
markdown: string;
config: PostextConfig;
mode?: 'single' | 'multi';
}) {
const hostRef = useRef(null);
const cacheRef = useRef(createMeasurementCache());
useEffect(() => {
const host = hostRef.current;
if (!host) return;
const relayout = () => {
const rect = host.getBoundingClientRect();
if (rect.width === 0 || rect.height === 0) return;
const viewer = resolveHtmlViewerConfig(config.htmlViewer);
const fontFamily = config.bodyText?.fontFamily ?? 'EB Garamond';
const fontWeight = config.bodyText?.fontWeight ?? 400;
const fontSize = config.bodyText?.fontSize ?? { value: 8, unit: 'pt' as const };
const fontSizePx = dimensionToPx(fontSize, HTML_DPI);
// Measure the *actual* column width for N characters of body prose.
const targetColumnPx = measureGlyphWidth(
sampleForChars(viewer.maxCharsPerLine),
buildFontString(fontFamily, fontSizePx, String(fontWeight), 'normal'),
);
const inner = Math.max(rect.width - PADDING_PX * 2, 100);
let columnWidthPx: number;
if (mode === 'single') {
columnWidthPx = Math.min(targetColumnPx, inner);
} else {
// Fit as many columns as we can at the target width.
const count = Math.max(
1,
Math.floor((inner + viewer.columnGap) / (targetColumnPx + viewer.columnGap)),
);
columnWidthPx = (inner - viewer.columnGap * (count - 1)) / count;
}
columnWidthPx = Math.max(Math.floor(columnWidthPx), 80);
// Single mode uses one very tall page; multi mode uses the viewport
// height so each VDT "page" becomes one column.
const pageHeightPx =
mode === 'single' ? Math.max(rect.height * 20, 200_000) : Math.max(rect.height - PADDING_PX * 2, 400);
const override: PostextConfig = {
...config,
page: {
...config.page,
dpi: HTML_DPI,
width: { value: columnWidthPx, unit: 'px' },
height: { value: pageHeightPx, unit: 'px' },
margins: {
top: { value: 0, unit: 'px' },
bottom: { value: 0, unit: 'px' },
left: { value: 0, unit: 'px' },
right: { value: 0, unit: 'px' },
},
},
layout: { ...config.layout, layoutType: 'single' },
bodyText: {
...config.bodyText,
optimalLineBreaking: viewer.optimalLineBreaking,
},
};
const doc = buildDocument({ markdown }, override, cacheRef.current);
const { html } = renderToHtmlIndexed(doc, {
mode,
columnGap: viewer.columnGap,
padding: PADDING_PX,
background: 'transparent',
});
host.innerHTML = html;
};
relayout();
const ro = new ResizeObserver(() => relayout());
ro.observe(host);
// Re-measure when web fonts land so glyph widths aren't taken from fallbacks.
const stopWatching = watchFonts();
const off = onFontsChanged(() => relayout());
return () => {
ro.disconnect();
off();
stopWatching();
};
}, [markdown, config, mode]);
return ;
}
```
بعض الملاحظات حول ما يفعله هذا المثال:
- **قياس العمود بدلًا من تقديره.** لأن `maxCharsPerLine` قيمة *مستهدفة* معبَّر عنها بالحروف، فإن العرض الفعلي بالبكسل يتوقف على خط النص الأساسي. وتعطي `measureGlyphWidth` قياسًا حقيقيًا بالخط المختار، فيبقى طول السطر ثابتًا عند تبديل الخطوط.
- **إعادة كتابة الصفحة.** يعامل عارض HTML كل «صفحة» من VDT عمودًا واحدًا على الشاشة. ويستبدل المثال `page.width` بعرض العمود المقيس، ويجعل الهوامش صفرًا (فالحشو يقع خارج الصفحة في عنصر div `.pt-doc` المغلِّف)، ويستخدم `HTML_DPI = 144` كي يصبح النص الأساسي `8pt` مساويًا `16px`.
- **مراعاة تحميل الخطوط.** تستمع `watchFonts` إلى `document.fonts`، وتطرح مرة في كل إطار ما قيس بالعائلات التي وصلت أوجهها؛ ثم تعيد `onFontsChanged` إخراج العمود. ومن دون إعادة الإخراج، يستخدم العرض الأول مقاييس خط بديل ثم يقفز حين يصل الخط الحقيقي.
- **إعادة استخدام ذاكرة القياس المؤقتة.** إنشاء الذاكرة مرة واحدة لكل مكوّن يعني أن تغيّر المقاس وتغيّر حجم الخط يعيدان استخدام قياسات العرض السابق بدلًا من إعادة قياس كل فقرة.
### أبعد من ذلك
المثال أعلاه مبسّط عن قصد. وعادة ما تضيف عمليات التكامل في بيئة الإنتاج ما يلي:
- **العزل عبر Shadow DOM**: ارسم داخل `host.attachShadow({ mode: 'open' })` كي لا يتسرّب أي CSS من الصفحة الخارجية إلى العارض.
- **الترقيع التدريجي**: تُعيد `renderToHtmlIndexed` القيمة `pages[i].blocks`، لكل منها `id` ثابت وHTML الخارجي للكتلة. وحين لا تختلف بين عمليتَي عرض إلا كتل قليلة، يمكنك استبدال أغلفة تلك الكتل في مكانها بدلًا من إعادة بناء `innerHTML`.
- **الطبقات العلوية**: وضع SVG ذي موضع مطلق فوق كل `.pt-page` للمؤشرات أو التحديدات أو شبكات خطوط الأساس.
- **الروابط**: تُغلَّف كلمات رابط Markdown في ``، الذي يأخذ لون النص بلا خط تحته؛ انظر [صيغة المستند › الروابط](https://postext.dev/ar/docs/document-format-inline.md#الروابط). وفي عارض شبيه بالمحرّر، اعترض النقرات على `a[href]` التي لا تبدأ بـ`#` وافتحها في تبويب جديد (فروابط `:ref` تشير إلى مواضع داخل المستند).
- **الصور أحادية الحبر**: حين يكون `diagramStyle.singleInk` مفعّلًا، تحصل عناصر `![]()
` من نوع SVG على مرشّح CSS ما لم تمرّر `singleInk: false` لعناوين URL المُعاد تلوينها أصلًا؛ انظر [الحبر الواحد في Canvas وفي HTML](https://postext.dev/ar/docs/configuration-resources.md#الحبر-الواحد-على-اللوحة-canvas-وفي-html).
ويطبّق المكوّن `HtmlPreview` في Sandbox (`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`) كل ذلك فوق الواجهة البرمجية نفسها المعروضة هنا، ويمكن استخدامه مرجعًا. وهو يمرّر أيضًا كل عملية بناء عبر عامل إخراج مشترك (انظر [تشغيل الإخراج في Web Worker](https://postext.dev/ar/docs/configuration-programmatic-usage.md#تشغيل-الإخراج-في-web-worker)) كي لا تحجب التعديلات الحيّة وتغيّرات المقاس الخيطَ الرئيسي أبدًا؛ استبدل استدعاء `buildDocument(...)` المباشر في المقتطف أعلاه بـ`layoutWorker.build(...)` حين تكون مستعدًا لنقل الإخراج بعيدًا عن الخيط الرئيسي.
### كيف يختلف إخراج HTML عن Canvas وPDF
تضع `renderToHtml` كل سطر وشكل وعنصر تصميم في الموضع نفسه تمامًا الذي يضعه فيه Canvas وPDF، لكنها ترسم حولها أقل:
| الميزة | Canvas (`renderPage`) | HTML (`renderToHtml`) | PDF (`renderToPdf`) |
| --- | --- | --- | --- |
| خلفية الصفحة | بيضاء، مع `page.backgroundColor` فوق حدّ القص والنزف. | **شفافة**، ما لم تمرّر `background` أو تضبط `page.backgroundColor` (الذي يملأ حينئذ صندوق الصفحة كله، بما في ذلك الحاشية الخارجية خلف النزف). | بيضاء، مع `page.backgroundColor` فوق حدّ القص والنزف. |
| شبكة خطوط الأساس (`page.baselineGrid`) | تُرسم | لا تُرسم | تُرسم |
| الخط الفاصل بين الأعمدة (`layout.columnRule`) | يُرسم | لا يُرسم | يُرسم |
| علامات القص (`page.cutLines`) | تُرسم | لا تُرسم؛ لكن صندوق الصفحة لا يزال يضم الحاشية الخارجية المحيطة بحدّ القص. | تُرسم |
| الصفحة السالبة | الخيار `pageNegative` | غير متاحة | الخيار `pageNegative` |
| النص | بكسلات | نص قابل للتحديد في عناصر ذات مواضع مطلقة، منضَّد بعائلات خطوط CSS: يجب أن تحمّل الصفحة الأوجه نفسها. | خطوط مضمّنة من `fontProvider` الخاص بك؛ والنص قابل للتحديد والبحث وموسوم. |
| النص العمودي (`layout.writingMode: 'vertical-rl'`) | تُرسم الحروف خلية خلية، مُعادةً إلى وضعها القائم؛ والأشكال العمودية عبر وجه توأم (`loadVerticalAlternates`). | يُدار التدفق في صندوق واحد ربع دورة؛ ويُعاد كل سطر إلى وضعه القائم ويُنضَّد بـ`writing-mode: vertical-rl`، فيأخذ المتصفح الأشكال العمودية ويُقيم الحروف؛ والأرقام القصيرة في `text-combine-upright: all`؛ والشرطة أو علامة الحذف أو النقطة الوسطى أو الشرطة المموّجة في صندوق خاص بخليتها (فالمتصفح كان سيقدّمها بعرضها الأفقي)، والشرطة تُمدّ لتملأه بحسب `flow.dashAdvances`. | حروف قائمة عبر توأم `Identity-V` لكل خط؛ انظر [النص العمودي في PDF](https://postext.dev/ar/docs/configuration-pdf-output.md#النص-العمودي-في-ملف-pdf). |
| الصور | `registerResourceImage` | الخيار `resourceImageUrl(fileId)`؛ ومن دونه صندوق نائب رمادي. | الخيار `resourceBytes(fileId)`. |
| الصيغ | مسارات متجهية | `