# صيغة المستند: الصور والجداول ومقاطع الفيديو

> الموارد في النص: الإحالات والتضمين، والترقيم، والموضع وأين يستقر العنصر العائم، والتفاف النص، ومقاس الصورة النقطية، والمناطق الآمنة، ونقاط الارتكاز في القصص المصورة، ومقاطع الفيديو

- نسخة HTML: https://postext.dev/ar/docs/document-format-resources
- آخر تحديث: 2026-10-16
- مدة القراءة: 40 دقيقة
- لغات أخرى: [en](https://postext.dev/en/docs/document-format-resources.md), [es](https://postext.dev/es/docs/document-format-resources.md), [ca](https://postext.dev/ca/docs/document-format-resources.md), [de](https://postext.dev/de/docs/document-format-resources.md), [fr](https://postext.dev/fr/docs/document-format-resources.md), [it](https://postext.dev/it/docs/document-format-resources.md), [pt](https://postext.dev/pt/docs/document-format-resources.md), [zh](https://postext.dev/zh/docs/document-format-resources.md), [ja](https://postext.dev/ja/docs/document-format-resources.md)

## باختصار

تتناول هذه الصفحة صور الكتاب وجداوله ومقاطع الفيديو فيه. تضيفها مرة واحدة وتذكرها في النص، فيضع Postext كلًّا منها قرب الموضع الذي ذُكر فيه أول مرة. ويمكنك أن تختار مكانها: أعلى الصفحة، أو بعرض كل الأعمدة، أو في الموضع الذي كُتبت فيه بالضبط. ويمكن أن يلتف النص حول الصورة. ويمكن أن تحدد في الصورة الجزء الذي يجب أن يظهر دائمًا حين تُقصّ لتناسب مكانها. وتعمل مقاطع الفيديو في عرض الويب وفي الكتب الإلكترونية، وتظهر في الطباعة صورةً.

## الموارد

لا تُكتب الصور ورسوم SVG والجداول ومقاطع الفيديو داخل النص. تُعرَّف مرة واحدة بوصفها **موارد** (تديرها [لوحة الموارد](https://postext.dev/ar/docs/sandbox.md#لوحة-الموارد) في Sandbox، وفيها رفع الصور وملفات SVG، ومحرّر جداول تفاعلي، ومقاطع يوتيوب وفيميو والفيديو المرفوع، وتحرير التعليقات والمواضع)، ثم تُربط بنصّك عبر معرّفها. **تكفي الإحالة إلى المورد لإدراجه**: تذكره مرة واحدة بإحالة داخل السطر `:ref{id="…"}`، فيُعوِّم المحرّك الشكل أو الجدول إلى أول موضع شاغر بعد تلك الإحالة، كأسفل العمود الذي ذكرته فيه، أو أعلى العمود التالي، أو شريط في الصفحة التالية، كما يفعل المنضّد في المطبعة. ولا تضعه مرة ثانية.

الصيغتان أدناه صياغة جديدة كليًا لا تتعارض مع CommonMark، فيبقى المستند الذي يستعملهما مقروءًا نصًا عاديًا في أي عارض Markdown آخر.

### الإحالة داخل السطر (الصيغة الأساسية)

أحِل إلى مورد من داخل النص بالصيغة `:ref{id="…"}`. الإحالة الأولى **تُدرج** المورد (فيوضع في الصفحة) وتعرض رقمه المحسوب في آن واحد، مسبوقًا افتراضيًا بالتسمية المختصرة لنوعه:

```md
As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery.
```

وتظهر هكذا: *As shown in Fig. 1.7, the lantern room sits above the gallery.* ويطفو الرسم نفسه إلى أقرب موضع شاغر بعد الجملة (أسفل هذا العمود، أو أعلى العمود التالي، أو شريط في الصفحة التالية)، بينما تتدفق هذه الجملة والنص الذي يليها دون انقطاع.

لا ينقطع النص الجاري أبدًا عند نقطة الإحالة. أما المكان الذي يستقر فيه المورد (أول موضع شاغر، أو موضع علوي أو سفلي فقط؛ داخل عمود واحد أو بعرض الصفحة كله) فيحكمه **موضعه** (انظر [الموضع](https://postext.dev/ar/docs/document-format-resources.md#الموضع) أدناه)، ويحكمه كذلك المكان الذي تذكره فيه: يبدأ البحث مباشرة بعد الإحالة.

### التضمين في كتلة (اختياري، لوضع صريح داخل التدفق)

قد تريد أحيانًا أن يقع المورد في نقطة محددة من التدفق بدل أن يطفو. ألغِ التعويم بإعطاء المورد `placement.position: "here"` وتضمينه بالصيغة `::resource{id="…"}` في سطر مستقل:

```md
Here is the floor plan we discussed.

::resource{id="lighthouse-diagram"}

The keeper's quarters occupy the eastern wing.
```

لا حاجة إلى التوجيه `::resource` مع مورد عائم، فقد وضعته `:ref` من قبل، ويُعامل `::resource` الزائد للمعرّف نفسه إحالةً أخرى ببساطة، لا نسخة ثانية. ولا يعرض `::resource` المورد داخل التدفق إلا إذا كان موضعه المحسوم `"here"`. ويحتفظ المورد المضمّن بمسافة سطر فوقه (فجوة العنصر العائم) كما يفعل العنصر العائم، ما لم تطلب الكتلة التي قبله أكثر من ذلك. وفي النص الجاري يحتفظ بالمسافة نفسها تحته؛ ثم يعود النص الذي يليه إلى شبكة خطوط الأساس، وقد يضيف ذلك ما يصل إلى سطر آخر. وإذا تلاه مباشرة عنوان أو قائمة أو إطار أو مورد مضمّن آخر، تقاسمت تلك المسافة مع المسافة التي فوقه: يُطبَّق الأكبر منهما، لا كلاهما. (حتى postext 1.4 لم تكن المسافة تحته سوى ما يتركه الالتصاق بالشبكة، من لا شيء إلى سطر كامل؛ ويحافظ `layout.inlineResourceGap: 'above'` على تلك القاعدة، وتُقرأ بها الكتب المحفوظة قبل 1.5.) وداخل الإطار (`:::callout`) يحتفظ المورد بالمسافة نفسها، أي سطر من نص الإطار نفسه فوقه، وتحته أيضًا مع `'around'`؛ وفي أعلى الإطار أو أسفله تفصله الحشوة بدلًا من ذلك. (حتى postext 1.4 كان يلتصق بنص الإطار مباشرة؛ ويحافظ `layout.inlineResourceGapInBoxes: false` على ذلك، وتُقرأ به الكتب المحفوظة قبل 1.5 التي تضمّن أطرها موردًا.)

وفي التخطيط متعدد الأعمدة، يمتد المورد المضمّن الذي يذكر موضعه أيضًا `span: 'page'` (`placement: { position: 'here', span: 'page' }`) على عرض الصفحة عند موضع توجيهه، كما يفعل الإطار الممتد على الصفحة: تُغلق الأعمدة التي فوقه على ارتفاع واحد (بموازنتها، أو ينتقل المورد إلى رأس الصفحة التالية إن تعذّر ذلك)، ويُصفّ بعرض منطقة المحتوى كله مع المسافة نفسها فوقه وتحته، ويستمر النص في كل الأعمدة تحته. وفي صفحة ذات عمود واحد يُصفّ كما كان من قبل، بعرض السطر كاملًا. أما المورد ذو `span: 'column'` مع `columns` فيبقى في عموده حين يُضمَّن في التدفق: فالأعمدة لا تُحتسب إلا للعناصر العائمة. منذ postext 1.19.

يجب أن يطابق `id` موردًا معرّفًا في لوحة الموارد. يرسم المحرّك المورد (صورة نقطية أو SVG أو جدول) وتعليقه تحته ذيلًا للشكل أو الجدول. ويتألف نص التعليق من `captionPrefix` لنوع المورد، والرقم المحسوب، والتعليق الخاص بالمورد، مثل **Figure 1.7. The original lighthouse plan.** وتحكم تنسيقه [الإعدادات › نمط التعليق](https://postext.dev/ar/docs/configuration-resources.md#نمط-التعليقات): تتشارك التسمية والوصف خطًا واحدًا وحجمًا واحدًا، بينما تحتفظ التسمية بإعدادات مستقلة للعريض والمائل واللون؛ والفجوة فوق التعليق `0.75em` افتراضيًا، والمحاذاة إلى اليسار. ويمكن أن يقع التعليق فوق المورد بدلًا من ذلك (`captionStyle.position: 'above'`، على مستوى المستند أو لكل نوع مورد)، على شريط ملوّن إن شئت. ويمكن أن يحمل المورد أيضًا `note`، وهو سطر قصير للمصدر أو الحقوق، بالتنسيق داخل السطر نفسه وعلامات `:ref` نفسها التي في التعليق، يُنضَّد بحجم أصغر تحت المورد (تحت التعليق حين يكون التعليق أسفله، وتحت جسم المورد حين يكون التعليق أعلاه) وينسَّق عبر `captionStyle.note`.

**فواصل الأسطر في التعليقات والملاحظات.** التعليق أو الملاحظة فقرة واحدة تُنضَّد بعرض موضعها، والسطر الجديد المكتوب فيها مسافة. لبدء سطر جديد، اكتب `\\`، وهو الفاصل الإجباري في العناوين، أو أنهِ السطر بشرطة مائلة عكسية، وهي الفاصل الصلب في Markdown: `¹ Measured at 20 °C. \\ ² Mean of three runs.` تضع كل حاشية من حواشي جدول عريض في سطر مستقل. يحتفظ السطر الذي يسبق الفاصل بعرضه الطبيعي ولا يُمدَّد إلى عرض السطر، ولا يُنتج فاصلان متتاليان سطرًا فارغًا (أما مسافة غير فاصلة بينهما فتُنتجه). وفي خلية الجدول يفعل `\\` ما يفعله السطر الجديد: يفتح فقرة جديدة؛ وتُحفظ إزاحة السطر الذي يليه، فتظل مسافتان في أوله تُدرجان بند القائمة في مستوى أعمق. وفي النص نفسه تكون الشرطتان المائلتان العكسيتان فاصلًا دائمًا، ولا سبيل إلى تهريبهما: لطباعتهما، ضعهما في شيفرة داخل السطر، حيث تُطبع الشرطات المائلة العكسية كما كُتبت. وفي وجهة الرابط تبقيان جزءًا من عنوان URL، وفي سمات التوجيه (`text` في `:ref`) جزءًا من القيمة؛ وداخل الشارة (chip)، التي تُنضَّد في سطر واحد، يكون الفاصل مسافة. (حتى postext 1.4 كانت الشرطتان تُطبعان، ولم يكن التعليق أو الملاحظة ينكسر إلا حيث ينتهي عرض السطر.)

ترسم موارد الجداول شبكتها الخاصة، وتُنسَّق عبر [الإعدادات › نمط الجدول](https://postext.dev/ar/docs/configuration-resources.md#نمط-الجداول): لخلايا المتن وخلايا الترويسة تنسيق مستقل تمامًا، وخلفية الترويسة `#f0f0f0` افتراضيًا، والحدود `0.75pt`، و`cellPadding` قيمته `0.375em`؛ وكل حقل لم يُضبط يرث من نص المتن. عروض الأعمدة جزء من الجدول نفسه: يحمل `TableModel.columnWidths` وزنًا نسبيًا واحدًا لكل عمود (`[2, 1, 1]` يمنح العمود الأول نصف العرض)؛ وإذا لم يُضبط، تقاسمت الأعمدة العرض بالتساوي. ويمكن أيضًا تنضيد الجدول بنمط مسمّى: يختار `table.styleId` واحدًا من `tableStyles` في المستند (انظر [الإعدادات › أنماط الجداول المسمّاة](https://postext.dev/ar/docs/configuration-resources.md#أنماط-الجداول-المسمّاة))، وترث حقوله غير المضبوطة من `tableStyle`؛ والمعرّف المجهول أو الغائب يُبقي على `tableStyle`.

تضع الخلية محتواها بالخاصية `TableCell.align` (`left`، `center`، `right`؛ وتبقى بنود القوائم محاذية لليسار) والخاصية `TableCell.verticalAlign` (`top`، وهي الافتراضية، أو `middle` أو `bottom`). تنقل المحاذاة الرأسية محتوى الخلية كله، أي الصورة والنص الذي تحتها بوصفهما وحدة واحدة، داخل خلية أطول منه: صف مدّته خلية مجاورة أطول، أو الصفوف التي يغطيها `rowSpan`. وتسري في كل المخرجات (Canvas وHTML وPDF)، وفي الجداول المدوّرة، وفي كل شريحة من جدول مقسوم على عدة صفحات. ويُضبط كلاهما لكل خلية من أزرار المحاذاة في شريط أدوات محرّر الجداول في Sandbox.

ويمكن أن تحتوي خلية الجدول صورة أيضًا. يسمّي `TableCell.image` موردًا من نوع صورة نقطية أو SVG بمعرّفه (`{ "resourceId": "fig-arm", "width": 0.7 }`): تُرسم الصورة داخل الخلية، دون ترقيم أو تعويم أو تعليق، بحيث تلائم العرض الداخلي للخلية (أو الكسر منه الذي يحدده `width`، وقيمته الافتراضية `1`) مع الحفاظ على نسبة أبعادها، وتُحاذى كما يُحاذى نص الخلية، ويجري أي نص في الخلية تحتها. ويزداد ارتفاع الصف ليتسع لها. وفي محرّر الجداول في Sandbox يختار زر الصورة في شريط الأدوات المورد للخلية النشطة، ويضبط حقل العرض الكسر. والمعرّف الذي لا يطابق أي مورد صورة يترك الخلية نصية فقط.

ويمكن أن تحمل الخلية تعبئتها الخاصة. `TableCell.background` قيمة لون (`{ "hex": "#c1dfd6", "model": "hex" }`، ويمكن ربطها بمُدخل في لوحة ألوان المستند عبر `paletteId`) تُطلى بدل خلفية الترويسة أو المتن في النمط؛ وبهذه الطريقة تظلّل مصفوفة التوافق خلاياها بالأخضر والأحمر والأصفر. ويضبطها محرّر الجداول في Sandbox من أداة التعبئة في شريط الأدوات. ولشرح دلالة هذه التعبئات، يقبل التعليق والملاحظة وأي كتلة نصية **عيّنة لون** داخل السطر: `:swatch{color="#c1dfd6"}` (قيمة hex، أو معرّف مُدخل في لوحة الألوان، مثل `:swatch{color="table-compatible"}`) تضع مربعًا صغيرًا على خط الأساس، بثلاثة أرباع حجم الخط، مملوءًا باللون ومحاطًا بإطار بلون النص، فيمكن أن تقرأ الملاحظة `:swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible`. واللون الذي لا يُحسم إلى شيء يرسم إطارًا فارغًا. ويمكن أن تحمل قيمة hex قناة شفافية (`#rrggbbaa`، `#rgba`)، وتعمل ألوان `rgb()` / `rgba()` أيضًا، فيكون لتعبئة الخلية الشفافة مفتاح شفاف مطابق (انظر [الإعدادات › الشفافية](https://postext.dev/ar/docs/configuration-fonts-colors-viewers.md#الشفافية)).

ويمكن كذلك إعادة تلوين موارد SVG للطباعة بلون موضعي واحد عبر `diagramStyle.singleInk` (القيمة الافتراضية `false`). عند تفعيله، يُعاد تعيين كل لون في رسم SVG إلى درجة من `diagramStyle.inkColor` بحسب سطوعه (وقيمته الافتراضية لون لوحة الألوان الرئيسي، `#295AA3`)، فيصير الأبيض لون الورق والأسود الحبر كاملًا، فتُطبع الأشكال بأمانة حين يُطبع المستند بلون موضعي واحد. انظر [الإعدادات › نمط الرسوم التخطيطية](https://postext.dev/ar/docs/configuration-resources.md#نمط-المخططات).

التضمين المعيب (`id` مفقود أو فارغ، أو `id` غير محاط بعلامتي تنصيص أو محاط بعلامتي تنصيص مفردتين، أو سمات زائدة) لا يُرقّى إلى كتلة مورد؛ بل يُحلَّل فقرةً عادية ويبقى ظاهرًا في المخرجات. وكذلك سطر التضمين السليم الملتصق تحت سطر فقرة دون سطر فارغ بينهما: يُقرأ جزءًا من تلك الفقرة. وكلاهما يطلق تحذير `malformedEmbed`، وهو مُدخل **تضمين نُضِّد نصًا** في لوحة الفحوص في Sandbox.

تُتعرَّف الإحالات داخل السطر في أي كتلة نصية، أي الفقرات والعناوين والاقتباسات الكتلية وبنود القوائم، ويمكن أن تجاور العريض والمائل والشيفرة داخل السطر والرياضيات داخل السطر.

#### خيارات الإحالة

يقبل التوجيه `:ref` ثلاث سمات اختيارية، بأي ترتيب. تختار `style` طريقة عرض التسمية المحسوبة: `style="number"` يطبع الرقم مجردًا (`1.7`)، و`style="full"` يطبع الاسم الكامل للنوع مع الرقم (`Figure 1.7`)، وإذا لم تُضبط `style` استُعملت `shortLabel` للنوع مع الرقم (`Fig. 1.7`). وتغيّر `case` حالة الأحرف في جزء التسمية وحده، `lower` أو `upper` أو `capitalize`، ولا تمسّ الرقم. أما `text` فتجاوزٌ حرفي يحل محل أي تسمية محسوبة وله الأسبقية على `style` و`case` كلتيهما. خيارات العرض جنبًا إلى جنب:

| الصياغة | الناتج | ملاحظات |
| --- | --- | --- |
| `:ref{id="…"}` | `Fig. 1.7` | النمط الافتراضي: `shortLabel` للنوع يليها الرقم، تصل بينهما مسافة غير فاصلة فلا ينفصلان أبدًا عند التفاف السطر. |
| `:ref{id="…" style="number"}` | `1.7` | الرقم المحسوب مجردًا، دون تسمية. |
| `:ref{id="…" style="full"}` | `Figure 1.7` | الاسم الكامل للنوع `name` يليه الرقم. استعمله في بداية الجملة أو حيث يبدو الاختصار ركيكًا. |
| `:ref{id="…" case="lower"}` | `fig. 1.7` | يغيّر حالة أحرف التسمية وحدها: `lower` (`fig. 1.7`)، أو `upper` (`FIG. 1.7`)، أو `capitalize` (الحرف الأول كبير). ويجتمع مع `style="full"` (`figure 1.7`)؛ ولا يُمسّ الرقم أبدًا، وتُتجاهل القيمة غير المعروفة. |
| `:ref{id="…" text="see the plan"}` | `see the plan` | تجاوز صريح. يُستعمل النص المعطى حرفيًا بدل أي تسمية محسوبة، وهو مفيد للروابط داخل النص مثل «كما رأينا سابقًا». وعند وجود `text` تكون له الأسبقية على `style` و`case`. |

إذا سمّت `:ref` (أو `::resource`) معرّفًا لا يطابقه أي مورد، تعود التسمية إلى `?` (وتُطبع تسمية `text=` بدلًا منها، دون رقم أو رابط أيضًا) ويطلق Sandbox تحذير **مورد غير معروف**. ويسجّله المحرّك مُدخلًا من نوع `unknownResourceId` في `contentWarnings` الخاصة بالمستند، مع نطاق الإحالة في المصدر وصفحتها، وكذلك لإحالة `:ref` داخل تعليق أو ملاحظة أو خلية جدول لمورد يستعمله النص.

### الترقيم بحسب الإحالة الأولى

يُسند رقم المورد **أول مرة يُذكر فيها بترتيب القراءة**، سواء أكان هذا الذكر الأول تضمينًا في كتلة `::resource` أم إحالة داخل السطر `:ref`. ومن ثَمّ تطبع كل إحالة إلى المعرّف نفسه الرقم نفسه.

أي أن الأرقام تتبع ترتيب لقاء القارئ بالموارد، لا ترتيب إنشائها في اللوحة:

- إذا أحلت إلى شكل بـ`:ref` في المقدمة ولم تضمّنه (`::resource`) إلا بعد صفحتين، أخذ مع ذلك رقم المقدمة، لأن الإحالة جاءت أولًا.
- إدراج إحالة جديدة في موضع *أسبق* من المستند يعيد ترقيم كل ما بعدها تلقائيًا. فلا ترقيم يدوي تحتاج إلى مزامنته.

الترقيم خاص بكل نوع مورد، ويراعي نطاق إعادة الضبط وصيغة العدّاد لكل نوع؛ انظر [الإعدادات › أنواع الموارد](https://postext.dev/ar/docs/configuration-resources.md#أنواع-الموارد) لرموز القالب (`{h1}`، `{n}`)، و`resetOn`، و`counterFormat`.

لا يُعدّ إلا ما يحيل إليه النص: المورد الذي لا يرسمه إلا التصميم (عنصر صورة في صفحة افتتاح الفصل مثلًا) لا يأخذ رقمًا ويترك العدّاد على حاله. ويعدّ `{h1}` كل عنوان من المستوى 1 لا يكون نمطه `numbered: false`، حتى لو كان `numberingTemplate` فيه فارغًا، فالمقالة التي عنوانها هو عنوانها الوحيد من المستوى الأول ترقّم أشكالها 1.1، 1.2… افتراضيًا. وفي [الإعدادات › ما الذي يُرقَّم](https://postext.dev/ar/docs/configuration-resources.md#ما-الذي-يُرقَّم) القاعدتان كلتاهما والإعدادات اللازمة لـ Figure 1، 2….

### الموضع

لكل مورد **موضع** (placement) يحدد أين يستقر عنصره العائم، ويُحسم لكل مورد على حدة (من `placement` الخاص به)، ثم من `defaultPlacement` لنوعه، ثم من القيمة الافتراضية المدمجة `auto` / `column`:

| الحقل | القيم | المعنى |
| --- | --- | --- |
| `position` | `"auto"` · `"top"` · `"bottom"` · `"here"` | `"auto"` (القيمة الافتراضية) يأخذ أول موضع شاغر بعد الإحالة، علويًا كان أو سفليًا؛ و`"top"` / `"bottom"` لا يقبلان إلا مواضع من ذلك النوع؛ و`"here"` يلغي التعويم ويضمّن المورد داخل التدفق عند التوجيه `::resource` (والجدول الموضوع هناك يُقطع بين الصفوف حين لا يتسع له ما بقي من عموده، انظر [الجداول الأطول من الصفحة](https://postext.dev/ar/docs/configuration-resources.md#الجداول-الأطول-من-الصفحة)). |
| `width`, `align` | `0 < width < 1`; `"left"` · `"center"` · `"right"` | مورد أضيق من موضعه: `width` هو الكسر الذي يشغله من عرض العمود (أو الصفحة)، و`align` مكانه داخل الموضع (جدول صغير في وسط عموده؛ شريط بعرض الصفحة تمتد صورته على عمود واحد). والصورة الأضيق من موضعها، كصورة نقطية أصغر من العمود أو صورة صغّرها `layout.fitFiguresToPage`، تقع هناك أيضًا بحسب `align`، تحت تعليق يحتفظ بعرض الموضع. يسري ذلك على العناصر العائمة وعلى تضمينات `::resource` داخل التدفق على السواء. |
| `captionSide` | `true` · `false` | في تخطيط العمود ونصف الذي يُخصَّص فيه العمود الجانبي للعناصر العائمة (`layout.sideColumnRole: 'floats'`)، يُبقي العنصر العائم من نوع `"column"` ذو `captionSide` جسمه في العمود الرئيسي، ويُنضّد تعليقه (وملاحظته) في العمود الجانبي، محاذيًا لأعلى الشكل، أو لأسفله في العنصر العائم السفلي؛ ويتنازل العمود الجانبي عن ذلك الشريط. والصفحة التي ليس فيها هذا العمود تُبقي التعليق تحت الشكل. ومنذ postext 1.28 يأخذه أيضًا المورد الموضوع في النص (`"here"`) بعرض عمود واحد: يُنضّد تعليقه وملاحظته في العمود الجانبي، بمحاذاة أعلى جسمه، ويكون ارتفاع الكتلة في النص ارتفاع الجسم وحده، وتتجنب الأشكال والإطارات الجانبية الموضوعة بعده هذا التعليق. وحيث يكون العمود الجانبي مشغولًا بجوار المورد يبقى التعليق تحت الجسم؛ والمورد الذي ينتقل إلى العمود التالي أو الصفحة التالية يُقرَّر أمره هناك من جديد. ولا يسري داخل إطار، ولا في صفحة عمودية، ولا على صورة يلتف النص حولها. و`layout.inlineCaptionSide: false` يقصر التعليقات الجانبية على العناصر العائمة بعرض العمود. |
| `span` | `"column"` · `"page"` | يشغل عمودًا واحدًا، أو يقطع تدفق الأعمدة ويمتد بعرض المحتوى كاملًا عبر كل الأعمدة. وفي التخطيط ذي العمود الواحد تتطابق القيمتان. |
| `columns` | عدد صحيح، الافتراضي `1` | في صفحة ذات أعمدة عدة، يمدّ العنصر العائم `"column"` على هذا العدد من الأعمدة المتجاورة، مع الفواصل بينها: صورة تمتد على عمودين من أعمدة الجريدة الخمسة. ويأخذ رأس سلسلة من الأعمدة الفارغة التي تبدأ على مستوى واحد، أو أسفل العمود الذي يشير إليه والأعمدة الفارغة التي تليه. وإذا بلغ عدد الأعمدة عدد أعمدة الصفحة أو زاد عليه صار عنصرًا عائمًا بعرض الصفحة. ويُتجاهل مع `span` بالقيمتين `"page"` و`"side"`، ومع المورد المدوَّر، ومع الإدراج المضمّن (`"here"`)؛ ولا يسري `captionSide` إلا على عنصر عائم بعرض عمود واحد. منذ postext 1.18. |
| `rotate` | `"ccw"` · `"cw"` | يُنضّد المورد مُدارًا ربع دورة، كجدول أفقي في كتاب عمودي. `"ccw"` يديره عكس عقارب الساعة، فيواجه أعلاه الحافة اليسرى للصفحة (ويدير القارئ الكتاب مع عقارب الساعة)، وهو العُرف المعتاد؛ و`"cw"` في الاتجاه الآخر. المورد المُدار عنصر عائم بعرض الصفحة دائمًا في صفحة مستقلة: يُخرَج على امتداد ارتفاع منطقة المحتوى، مقرَّبًا إلى الأدنى إلى أسطر كاملة من شبكة خطوط الأساس وناقصًا سطرًا واحدًا من المتن، وهو فجوة العنصر العائم التي يحتفظ بها كل شريط عائم (منطقة نص ارتفاعها 237 mm على شبكة 14 pt تسع 47 سطرًا، أي 232.1 mm، فيأخذ المورد 46 منها، أي 227.2 mm)، ويلتصق بالكعب حين تكون الهوامش متناظرة (وبالحافة اليسرى في غير ذلك)، والجدول الأعرض من صفحة واحدة يُقطع بين الصفوف ويُستأنف، مُدارًا، في الصفحات التالية مع تكرار ترويسته، تمامًا كالجدول القائم الأطول من صفحة. ويُصغَّر الشكل المُدار ليلائم الصفحة. ويُتجاهل هذا الحقل في التضمين داخل التدفق (`"here"`). |
| `shrink`، `minScale` | `"never"` · `"page"` · `"slot"`؛ `0 < minScale ≤ 1`، الافتراضي `0.7` | يصغّر صورة عائمة (صورة نقطية، SVG، ملصق فيديو)، مع حفظ نِسَبها، إلى الحيّز المتاح في موضع بدل نقلها إلى ما بعده. `"never"` (الافتراضي) يصفّها بحجمها. `"page"` يصغّرها فقط حين تكون أطول من شريط صفحة جديدة: مساحة المحتوى ناقص ما يشغل تلك الصفحة أصلًا (افتتاحية، أشكال عائمة أخرى، حواشٍ) وفسحة العنصر العائم، كلوحة في فهرس معرض تُقاس على صفحتها. `"slot"` يصغّرها كذلك لتدخل موضعًا في الصفحة التي تحيل إليها، أو الحيّز الباقي بجانب شريط آخر، إن اتسعت هناك بمقياس `minScale` أو أكثر؛ وإلا انتقلت إلى ما بعده كما من قبل. وتُجرَّب المواضع بترتيبها المعتاد، ويبقى الشريط منتهيًا على شبكة خطوط الأساس. وتُقصّ الصورة ذات المنطقة الآمنة داخلها قبل تصغيرها (انظر [المنطقة الآمنة](https://postext.dev/ar/docs/document-format-resources.md#المنطقة-الآمنة)). وفي صفحة جديدة، حيث لا مكان آخر تذهب إليه، تُصفّ الصورة التي لا تتسع حتى بمقياس `minScale` بهذا المقياس وتتجاوز الشريط. ويبلّغ التخطيط عن كل عنصر عائم مصغَّر بتنبيه `floatShrunk`. ولا تُصغَّر أبدًا الجداول (فهي تُقسَّم)، ولا الصناديق العائمة، ولا شرائط القصص المصورة، ولا الموارد المدوَّرة، ولا التضمينات داخل التدفق. والقيمة الافتراضية للمستند هي `layout.floatShrink`. منذ postext 1.24. |
| `captionMeasure` | `"slot"` · `"body"` | عرض سطور التعليق والملاحظة لصورة أضيق من موضعها (مصغَّرة، أو صورة نقطية أصغر من العمود): `"slot"` (الافتراضي) يُبقي عرض الموضع؛ `"body"` يصفّهما بعرض الصورة، تحتها بحسب `align`، فتحمل اللوحة المتوسطة تعليقها متوسطًا تحتها. للعناصر العائمة والتضمينات داخل التدفق على السواء. منذ postext 1.24. |
| `wrap`, `wrapGap` | `"none"` · `"left"` · `"right"` · `"start"` · `"end"`; طول | يُصفّ النص بجانب المورد: يوضع المورد في ذلك الجانب من عموده، وتُصفّ الأسطر المجاورة له بالعرض المتبقي، على بُعد `wrapGap` من إطاره (مع تعليقه)، ثم تعود إلى العرض الكامل تحته. ينطبق على الإدراج داخل النص (`"here"`) وعلى عنصر عائم بعرض عمود واحد في أعلى عمود أو أسفله؛ أما العناصر العائمة بعرض الصفحة أو عبر عدة أعمدة أو في العمود الجانبي أو المُدارة فتحتفظ بشريطها. يأخذ المورد `width` من العمود، أو `layout.wrap.defaultWidth` (0.45). القيمة الافتراضية لـ`wrapGap` هي `layout.wrap.gap`، وإلا فسطر واحد من المتن. انظر [التفاف النص](https://postext.dev/ar/docs/document-format-resources.md#التفاف-النص). منذ postext 1.24. |
| `citingPage` | `true` · `false`، والافتراضي `false` | يتيح للشكل العائم `"top"` أو `"auto"` أن يحتل رأس الصفحة (شكل عائم بعرض الصفحة) أو رأس العمود (شكل عائم بعرض العمود، ومنه ما يمتد عبر `columns`) حيث يقع السطر الذي يشير إليه أول مرة، كما يفعل الموضع `t` في LaTeX، بدلًا من أول موضع شاغر بعد ذلك السطر. وينزل النص الذي فوق الإحالة تحت الشكل. ولا يكون ذلك إلا إذا اتسع له المكان في حدود `layout.maxTopFraction` من العمود (0.7 افتراضيًا)، وكانت الأشكال السابقة من تسلسل ترقيمه قد وُضعت، ولم تبدأ الصفحة بفاصل صريح (الصفحة الأولى من فصل، أو جزء، أو `:::pagebreak`) ولم يكن فوق سطر الإحالة شيء بعرض الصفحة، وإذا بقي سطر الإحالة بعد هذا الوضع في تلك الصفحة (في عمود يتصدره الشكل)؛ وإلا أخذ الشكل موضعه المعتاد. ولا تنتقل بهذه الطريقة أبدًا الأشكال المدوّرة ولا أشكال العمود الجانبي ولا بقية جدول مقسوم بين الصفحات. الافتراضي: `defaultPlacement` للنوع، ثم `layout.floatsAtCitingPage`. منذ postext 1.25. |

يذهب العنصر العائم إلى **أول موضع شاغر بعد إحالته الأولى**، بترتيب القراءة: أسفل العمود الذي تقع فيه الإحالة، ثم أعلى العمود الفارغ التالي في الصفحة نفسها وأسفله، ثم أشرطة الصفحة التالية التي يفتحها التدفق (العنصر العائم بعرض الصفحة يأخذ أسفل الصفحة حين يبقى في كل عمود متسع له، وإلا فشريطًا في الصفحة التالية). والصفحة التي يفتحها شكل أو جدول مضمّن داخل التدفق تُحتسب أيضًا: العنصر العائم الذي ينتظر تلك الصفحة يأخذ رأسها، فوق الشكل أو الجدول، حين يتسع لهما معًا؛ وإن لم يتسع، احتفظ الشكل أو الجدول بالصفحة وانتظر العنصر العائم الصفحة التالية. وحتى postext 1.4 كانت هذه الصفحة تُتخطّى، فينتظر العنصر العائم الصفحة التي بعدها حتى لو اتسعت لهما. ويُصفّ العنصر العائم بحجمه ما لم يسمح له `shrink` بالتصغير إلى حيّز موضع (انظر الجدول أعلاه)، ولا يستقر أبدًا قبل إحالته. وتظهر العناصر العائمة من سلسلة ترقيم واحدة بترتيب إحالاتها: الشكل الذي لا يجد مكانًا في صفحة يؤخّر الأشكال التي خلفه (والجدول المنتظر لا يؤخّر شكلًا، ولا العكس)، فلا يظهر الشكل 12 أبدًا قبل الشكل 11. أما الجدول الذي كان سينتظر فيُقطع بدلًا من ذلك: إذا عُرض عليه رأس عمود فارغ، أخذ الصفوف التي تتسع واستُؤنف في الموضع التالي، العمود المجاور أو الصفحة التالية، مع تكرار صفوف ترويسته (انظر `tableStyle.overflow`). ويمكن للشكل العائم `top` أو `auto` الذي فُعّل فيه `citingPage` أن يتصدر بدلًا من ذلك الصفحة (أو العمود) حيث يقع سطر الإحالة، فينزل النص الذي فوق الإحالة تحته: يُرسم حينئذ فوق إحالته في الصفحة نفسها، ولا يكون أبدًا في صفحة سابقة، ويُقرأ بعدها في ملف PDF الموسوم وفي HTML. يحسم المحرك ذلك في بضع تمريرات إضافية، ولا يبقيه إلا ما دام سطر الإحالة في تلك الصفحة.

لا تخرج العناصر العائمة أبدًا من فصلها: عند صفحة افتتاح فصل (مستوى عنوان فيه `breakBefore` أو `span: 'page'`)، وعند `:::part`، وعند نمط إطار فيه `floatBarrier: true` (إطار «النقاط الرئيسية» الذي يختم الفصل)، وفي نهاية المستند، يوضع أولًا كل عنصر عائم لا يزال معلّقًا، في المواضع الشاغرة من الصفحة أو في صفحات تُفتح قبل الحدّ. والعنصر العائم الذي يحيل إليه الافتتاح نفسه أولًا (عنوان فصل يسمّي شكله)، أو الكتلة الأولى بعد `:::part`، ينتمي إلى الفصل الجديد: يستقر بعد ذلك السطر كأي عنصر آخر. وقد يأخذ عندئذ الشكل أو الجدول الذي طلب رأس صفحة أسفلَ الصفحة الختامية للفصل، تحت أعمدتها المتوازنة، بدل صفحة مستقلة. أما `:::pagebreak` فيرسل العناصر العائمة المعلّقة إلى الصفحة التي تليه ببساطة.

تحت افتتاح بعرض الصفحة مضبوط فوق عمودين من النص أو أكثر، يُعدّ عمود الافتتاح نفسه فارغًا عند رأسه ما دام لا شيء يتبع الافتتاح فيه: الإطار العائم الموضوع بعد الافتتاح مباشرة، أو المورد المضمَّن هناك بـ `::resource`، يأخذ رأس العمود الأول، تحت الافتتاح وعلى مستوى رؤوس الأعمدة الأخرى (وعلى عدة أعمدة ابتداءً منه مع `columns`)، ويبدأ نص العمود تحته. أما العنصر العائم المُحال إليه في النص فيبقى بعد السطر الذي يشير إليه. حتى postext 1.24 لم يكن العمود الأول يتيح هذا الموضع فكان العنصر العائم يقع ابتداءً من العمود الثاني؛ و`layout.floatsUnderOpener: false` تُبقي على ذلك (انظر [الإعدادات › التخطيط](https://postext.dev/ar/docs/configuration-page-layout.md#التخطيط)).

والإطارات الجانبية (`span="side"`) لا تخرج من فصلها كذلك. الإطار الذي لا يتسع له العمود الجانبي لصفحته يأخذ العمود الجانبي للصفحة التالية؛ وإذا انتهى الفصل، أو المستند، قبل ذلك، وُضع كل إطار ما زال ينتظر في العمود الجانبي لصفحة تُفتح بعد النص، بترتيب أسيجتها، ووقف خلفها الشكل الجانبي المُحال إليه بعدها. هذه الصفحة لا نص فيها، فينبّه البناء إلى كل إطار وشكل فيها (`afterText`). والإطار الأطول من عمود جانبي فارغ يوضع على أي حال ويُنبَّه إليه (`calloutOverflow`)، وما لا يجد صفحة بعد ذلك يُنبَّه إليه أيضًا (`unplaced`) بدل أن يسقط. حتى postext 1.24 لم تكن تُفتح إلا أولى هذه الصفحات وتضيع الإطارات الباقية بلا تنبيه.

تُصحَّح أشرطة العناصر العائمة وفق شبكة خطوط الأساس كي يحافظ النص المحيط على الإيقاع الرأسي على امتداد الصفحة. فالشريط **العلوي** يزيد هامشه السفلي حتى خط الشبكة التالي، فيبقى النص تحت العنصر العائم محاذيًا للأعمدة المجاورة وللصفحة المقابلة. والعنصر العائم **السفلي** يُثبَّت بحيث يشترك السطر الأخير من تعليقه في خط أساس واحد مع آخر سطر نص في الأعمدة الأخرى (والمحتوى الذي لا تعليق له يحاذي حافته السفلى مع آخر موضع في الشبكة)، فتنتهي الصفحات الممتلئة عند الارتفاع نفسه عبر الأعمدة وعبر الصفحتين المتقابلتين.

في الصفحة الختامية للفصل، وللمستند، لا يلي الأشكالَ والجداول بعرض الصفحة المنضّدة تحت آخر شريط نص شيءٌ، فترتفع لتقع على بُعد فجوة عنصر عائم واحدة تحته، متراصّة بترتيبها، بدل أن تترك بياضًا بين النص وشكل في أسفل الصفحة. ويسري ذلك على العنصر العائم ذي `position: 'bottom'` أيضًا. لإبقائها في أسفل الصفحة، كما في كل صفحة أخرى، اضبط `layout.hugClosingFloats: false` (انظر [الإعدادات › التخطيط](https://postext.dev/ar/docs/configuration-page-layout.md#التخطيط)). ولا تحرّكها أبدًا الصفحات التي فيها عمود جانبي.

ترسم الموارد المُخرِجات الثلاثة كلها: معاينة Canvas، وعارض HTML، ومخرجات PDF. وفي مُخرِج HTML تقيم بيانات الصور خارج المستند، فيوفّرها المضيف عبر خيار المُحلِّل `resourceImageUrl(fileId)`؛ وحين يغيب المُحلِّل (أو لا يعيد شيئًا لملف ما)، يُعرض المورد مربعًا محايدًا بديلًا كي يبقى التخطيط ثابتًا. ويأتي ملف الفيديو نفسه عبر `resourceVideoUrl(fileId)` بالطريقة نفسها (انظر [مقاطع الفيديو](https://postext.dev/ar/docs/document-format-resources.md#مقاطع-الفيديو)).

#### أين يمكن أن يستقر العنصر العائم

تُحسب قاعدة «أبدًا قبل إحالته» من السطر الذي يحيل إلى العنصر العائم: ينتظر العنصر العائم حتى يُنضَّد ذلك السطر، ويأخذ أول موضع شاغر بعده بترتيب القراءة، ورأس الصفحة التي يُنضَّد فيها السطر يقع قبله. والاستثناء هو العنصر العائم الجانبي (`span: 'side'`، في العمود الجانبي المخصص للعناصر العائمة في تخطيط العمود ونصف): يتراصّ في العمود الجانبي بجانب النص الذي يحيل إليه، وقد يقع أعلى في الصفحة من سطر الإحالة. لشكل يُحال إليه في الصفحة 5:

| الموضع | في الصفحة 5 | وإلا |
| --- | --- | --- |
| `top`، `span: 'page'` | أبدًا: الشريط الذي في رأس الصفحة يقع فوق سطر الإحالة. | الشريط العلوي في الصفحة 6. |
| `top`، `span: 'column'` | رأس عمود لاحق لا يزال فارغًا؛ فإذا أُحيل إليه في الأول من عمودين، أمكنه أن يفتتح الثاني. | رأس عمود في الصفحة 6. |
| `auto` أو `bottom`، `span: 'page'` | الشريط السفلي في الصفحة 5، حين يبقى في كل عمود متسع له. | شريط في الصفحة 6. |
| `auto` أو `bottom`، `span: 'column'` | أسفل عمود الإحالة؛ ثم أسفل (كلاهما) أو رأس (`auto` فقط) عمود فارغ لاحق. | الصفحة 6. |

- تتبع صفحة افتتاح الفصل القواعد نفسها: العنصر العائم بعرض الصفحة من نوع `auto` أو `bottom` الذي يُحال إليه في الفقرة الأولى من الافتتاح يمكنه أن يأخذ الشريط السفلي لتلك الصفحة، تحت نصها؛ أما عنصر `top` فيفتتح الصفحة التالية. ولكي تكون الصورة في الصفحة التي تحيل إليها، استعمل `auto` أو `bottom`، أو ارسمها عنصر صورة في تصميم الافتتاح.
- عنصران عائمان بعرض عمود يُحال إليهما في الفقرة نفسها يأخذان الموضعين التاليين: عادةً يأخذ الأول أسفل عمود الإحالة، والثاني رأس العمود الفارغ التالي، فيتجاوران في الصفحة.
- في التخطيط ذي العمود الواحد يكون العنصر العائم بعرض الصفحة عنصرًا عائمًا بعرض عمود، وتسري القواعد نفسها: عنصر `top` يُحال إليه في صفحة يستقر في رأس الصفحة التالية.
- الفقرة التي تمتد من صفحة إلى التالية تُحسب كذلك من سطر الإحالة فيها. حين تبدأ الفقرة في أسفل الصفحة 5 وتقع الإحالة في الصفحة 6، أو تنتقل الفقرة كلها إلى الصفحة 6 لأن ما يتسع من أسطرها في أسفل الصفحة 5 لا يكفي، تكون الإحالة في الصفحة 6: عنصر `top` يفتتح الصفحة 7، وعنصر `auto` يأخذ أسفل الصفحة 6 حين يتسع له. ويسري الأمر نفسه بين أعمدة الصفحة الواحدة، وعلى الإطار المقسوم على عدة صفحات: الشكل الذي يحيل إليه جزؤه الثاني ينتظر ذلك الجزء.
- **تغيّر في postext 1.5.** حتى postext 1.4 كان العنصر العائم يُدرج في قائمة الانتظار حين يصل التخطيط إلى الفقرة التي تحيل إليه، فكانت الصفحة التي تمتد إليها هذه الفقرة (أو تنتقل إليها) قد تُفتتح بالعنصر العائم، فوق السطر الذي يحمل الإحالة. أما الآن فيستقر هذا الشكل بعد صفحة، أو في أسفل الصفحة حين يطلب `auto`؛ وقد يترتب على ذلك تغيّر في عدد الصفحات.

### التفاف النص

يمكن لصورة أو جدول أو صندوق أضيق من عموده أن يقف في أحد جانبيه والنص يُصفّ بجانبه، كما في المجلات والنشرات. أعطِ موضعه جانبًا في `wrap`، وإن شئت `width`:

```json
{ "id": "bed", "typeId": "figure", "kind": "svg", "caption": "حوض الزراعة الجديد.",
  "placement": { "position": "here", "wrap": "right", "width": 0.4 } }
```

- **داخل النص (`"here"`).** يوضع المورد في جانبه من العمود، وأعلاه بمحاذاة أعلى السطر التالي لسطر `::resource`، وتُصفّ الفقرات والاقتباسات وعناصر القوائم التي تليه بجانبه بالعرض المتبقي، ثم تحته بالعرض الكامل. الفقرة التي تبدأ بجانبه وتنتهي تحته تبقى فقرة واحدة: لا انقطاع فيها ولا مسافة زائدة عند أسفل الصورة. تبقى كل الأسطر على شبكة خطوط الأساس؛ والمسافة تحت الصورة هي مسافة الالتفاف مقرّبة إلى أعلى إلى أسطر كاملة من الشبكة.
- **عنصر عائم في عمود.** العنصر العائم `span: "column"` بعرض عمود واحد، في أعلى عمود (`"top"`، أو `"auto"` في أعلى عمود) أو أسفله (`"bottom"`، `"auto"`)، يوضع في شريطه كأي عنصر عائم، ثم تُصفّ أسطر العمود الأولى أو الأخيرة بجانبه. في صفحة من عمودين ينتمي العنصر العائم إلى عموده، ويجري العمود الآخر بعرضه الكامل.
- **صندوق.** يقبل `:::callout` الإعدادات نفسها سماتٍ: `:::callout{wrap="right" width=0.4}` يضع اقتباسًا بارزًا أو إطارًا جانبيًا حيث يرد، والنص الذي يليه بجانبه، و`placement="top"` أو `"bottom"` مع `wrap` يجعله يعوم إلى أعلى العمود أو أسفله. يُصفّ الصندوق الملتف كاملًا ولا يُقسَم أبدًا.
- **ما ينزل تحته.** العنوان والصيغة المستقلة والشكل أو الجدول والصندوق والقصيدة لا تُصفّ بجانب عنصر ملتف: تنزل تحته، ويبقى البياض بجانبه فوقها فارغًا. مغادرة العمود (أسفله، أو `:::columnbreak`، أو فاصل صفحة) تُنهي الالتفاف هناك: العنصر ينتمي إلى عموده. وحين لا يمكن للكتلة التي تلي المورد داخل النص مباشرةً أن تُصفّ بجانبه، يأخذ المورد شريطه كما بلا `wrap`.
- **المسافة والحدود.** `wrapGap` (وإلا `layout.wrap.gap`، وإلا سطر واحد من المتن) تفصل العنصر، مع تعليقه، عن النص المجاور وعن النص تحته. إذا كان النص المجاور سيصبح أضيق من `layout.wrap.minTextWidth` (12 em من المتن)، أو كان العنصر أقصر من `layout.wrap.minLinesBeside` سطرًا (2)، يأخذ الشريط كله ويُصدر تحذير `textWrap`. والعنصر داخل النص الأطول من المساحة المتبقية في عموده ينتقل إلى العمود التالي مع مرساته، بالتحذير نفسه.
- **الجانبان.** `left` و`right` جانبا تدفق النص، كما في `align`: في كتاب من اليمين إلى اليسار `left` هو يمين الورقة. و`start` و`end` يسمّيان الجانبين نفسيهما.
- **المخرجات.** تصفّ اللوحة وعارض HTML وملف PDF وEPUB ذو التخطيط الثابت الأسطر كما خُطّطت؛ ويقرأ PDF الموسوم الصورة أو الصندوق قبل الفقرة المجاورة. أما EPUB القابل لإعادة التدفق فيجعله يعوم إلى جانبه بـCSS، بالحصة نفسها من عرض النص.
- **ليس بعد.** النص على جانبي الصورة، والالتفاف حول الحواف، والالتفاف داخل محتوى صندوق، والالتفاف في الكتابة العمودية (يحتفظ العنصر بشريطه مع تحذير). الأعمدة التي فيها عنصر ملتف تُستثنى من موازنة الأعمدة.

### مقاس الصورة النقطية

تصرّح الصورة النقطية ببكسلاتها: `bitmap.width` و`bitmap.height` عددا بكسلات الملف، لا مقاس طباعة. وعدد ما يدخل منها في البوصة هو ما يقرّر المقاس الذي تُصفّ به الصورة قبل أن تحدّها خانتها. وثمة ثلاث طرق لتحديد مقاسها:

- **بكسلاتها بدقة الصفحة** (الافتراضي). من غير دقة، كل بكسل من الصورة بكسلٌ من الإخراج (`page.dpi`، وهي 300 ما لم تُضبط): فالصورة الفوتوغرافية ذات 2400 px عرضها 8 بوصات (203.2 mm) في صفحة بدقة 300 dpi، وضعف ذلك في صفحة بدقة 150.
- **دقة.** `bitmap.resolution` هي دقة الصورة بالـppi بمقاس طباعتها الطبيعي، فعرضها الطبيعي `width × page.dpi / resolution` في صفحة بأي دقة: 2400 px مع `resolution: 300` عرضها 203.2 mm في صفحة مُخرَجة بدقة 150 dpi أو 300. ويعطي `layout.bitmapResolution` دقةً لكل صورة نقطية ليست لها دقة خاصة بها: رقمًا (`300`)، أو `'file'`، أي الدقة التي يذكرها ملفها (`bitmap.fileResolution`: الحقل `pHYs` في PNG، وكثافة JFIF أو EXIF في JPEG، وEXIF في WebP؛ وفي الصورة المستوردة من Word، المقاس الذي كان Word يطبعها به). وكثيرًا ما تذكر الكاميرات ولقطات الشاشة وملفات التصدير للويب دقة 72 أو 96 ppi وهي لا تعرف شيئًا عن مقاس الطباعة، لذا تُعدّ هاتان القيمتان تحت `'file'` غير محددتين، وتبقى الصورة ببكسلاتها بدقة الصفحة؛ أما 72 المصرَّح بها في المورد نفسه فتؤخذ كما كُتبت. و`'document'`، الافتراضي، هي الطريقة الأولى.
- **حصة من العمود.** يضيّق `placement.width` العنصر العائم أو الإدراج المضمّن إلى كسر من عموده (أو صفحته)، والصورة الأكبر من تلك الحصة تُصغَّر إليها أيًّا كانت بكسلاتها (انظر [الموضع](https://postext.dev/ar/docs/document-format-resources.md#الموضع)).

وفي كل الحالات تحدّ الخانةُ الصورةَ مع الحفاظ على تناسبها، ولا تُكبَّر الصورة الأصغر أبدًا. والمقاس الطبيعي نفسه ينطبق على الصورة في خلية جدول وعلى عنصر `image` في التصميم بمقاس `'auto'`. ويضمّن PDF الملف كما هو بالمقاس الذي وُضع به. ويتحقق [الفحص قبل الطباعة](https://postext.dev/ar/docs/configuration-fonts-colors-viewers.md#الفحص-قبل-الطباعة) من الدقة التي تُطبع بها كل صورة، وتعرضها [لوحة الموارد](https://postext.dev/ar/docs/sandbox.md#لوحة-الموارد) في Sandbox لكل صورة. منذ postext 1.24.

```json
{ "id": "harbour", "typeId": "figure", "kind": "bitmap", "caption": "The harbour at dawn.",
  "bitmap": { "fileId": "harbour.jpg", "format": "jpeg", "width": 2400, "height": 1600, "resolution": 300 } }
```

يقرأ `bitmapInfo(bytes)` (من `postext` و`postext/bundle`) بكسلات الملف والدقة التي يذكرها، `{ width, height, resolution?: { x, y, source } }`؛ والحزمة التي تُفتح تحت `'file'` تملأ `fileResolution` بهذه الدقة، ويحتفظ بها Sandbox لكل صورة تُرفع إليه.

### المنطقة الآمنة

يمكن لمورد من نوع bitmap أو SVG أن يحدّد **منطقة آمنة**: المستطيل من الصورة الذي يحمل ما يهمّ (شخص وشريط من المنظر من حوله، الجزء المرسوم من مخطط بياني) ويظهر دائمًا. وهي الحقل `safeArea` في المورد، أربعة كسور (من 0 إلى 1) من الحجم الأصلي للصورة تُقاس من زاويتها العليا اليسرى: `x` و`width` كسران من عرضها، و`y` و`height` كسران من ارتفاعها. الاسم يقول ما يجب أن يبقى؛ أما صندوق القصّ فيقول أين يُقطع.

```ts
const harbour: Resource = {
  id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'الميناء عند الفجر.',
  createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 },
  // the boats and the quay: 18–68 % of the width, 25–85 % of the height
  safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 },
};
```

لا تُقصّ إلا الصورة التي لها منطقة آمنة. وعندئذ يجوز للمحرّك أن يعرضها بأي نسبة أبعاد بين الصورة كاملة والمنطقة الآمنة: أطول من نسبتها الأصلية بقصّ جانبيها، إلى عرض المنطقة الآمنة على الأكثر، أو أقصر بقصّ أعلاها وأسفلها، إلى ارتفاع المنطقة الآمنة على الأكثر. ولا يتغيّر عرض الشكل أبدًا، بل ارتفاعه وحده. وما يقع خارج المنطقة الآمنة يُقصّ من كل جانب بنسبة الهامش الذي فيه، فيبقى الموضوع الواقع يسار المركز يسار المركز. إذا نُضّدت صورة الميناء أعلاه بعرض 60 مم كان ارتفاعها كاملة 40 مم، ويمكن عرضها بأي ارتفاع بين 24 مم (بقصّ الأعلى والأسفل حتى 60% من الارتفاع) و80 مم (بقصّ الجانبين حتى نصف العرض). والقيم التي تتجاوز حواف الصورة تُردّ إليها؛ أما المنطقة التي فيها قيمة ليست عددًا، أو ضلع أقل من 2% من الصورة، أو التي تغطي الصورة كلها، فتُهمَل، وكذلك يُهمَل الحقل في الجدول. ومن دون منطقة آمنة تُعرض الصورة كاملة دائمًا، كما كانت من قبل.

يستعمل المحرّك هذا الهامش في أربعة مواضع:

- **المتسع الباقي في العمود.** الصورة المضمّنة داخل التدفق (`position: 'here'`) التي تزيد قليلًا على المتسع الباقي في عمودها، ومنها الصورة التي سيتجاوز تعليقها أسفل الصفحة، تُقصّ داخل منطقتها الآمنة لتبقى في مكانها، بدل أن تنتقل إلى العمود أو الصفحة التالية وتترك هذا العمود قصيرًا.
- **صفحات أقصر من الشكل.** مع `layout.fitFiguresToPage` تُقصّ الصورة الأطول من الصفحة أولًا داخل منطقتها الآمنة، مع الحفاظ على عرضها، ولا تُصغَّر إلا إذا بقيت أطول مما ينبغي (انظر [الإعدادات › التخطيط](https://postext.dev/ar/docs/configuration-page-layout.md#التخطيط)).
- **أشرطة أقصر من الشكل.** العنصر العائم الذي يصغّره `placement.shrink` إلى حيّز موضعه يُقصّ أولًا داخل منطقته الآمنة، محتفظًا بعرضه، ثم يُصغَّر بعد ذلك فقط؛ ولا تُطيله رافعة `flexFigure` أدناه أبدًا إلى ما بعد ذلك الحيّز.
- **موازنة الأعمدة.** الصورة ذات المنطقة الآمنة المضمّنة في عمود قصير، أو العائمة في رأس ذلك العمود أو أسفله وفوقه وحده، تطول بأسطر كاملة من شبكة خطوط الأساس حتى تملأ الأسطر الفارغة في العمود. والصورة الأطول لا تترك فجوة ظاهرة، ولذلك تُجرَّب هذه الأداة، `flexFigure`، بعد الإطار الذي يختم العمود مباشرة وقبل إضافة أي مسافة فوق العناوين أو بعد القوائم. أما العنصر العائم في رأس عمود من الصفحة الختامية لفصل، أو من شريط ختامي، فلا يطول، لأن رؤوس الأعمدة هناك تبقى متساوية (انظر [الإعدادات › موازنة الأعمدة](https://postext.dev/ar/docs/configuration-page-flow.md#موازنة-الأعمدة)).

تسجّل شجرة VDT القصّ على كتلة المورد: `bodySource` هو الجزء الظاهر من الصورة داخل `bodyRect`، بالكسور نفسها (ويغيب حين تظهر الصورة كاملة)، و`bodyFlex` يعطي عدد px التي لا يزال جسم الصورة يستطيع أن يقصر أو يطول بها، وعدد px التي غيّرته بها الأدوات (`{ shrink, grow, delta }`). معاينة Canvas وملف PDF يقصّان الرسم إلى جسم الصورة ويرسمان الصورة كاملة بحجمها غير المقصوص؛ وعارض HTML وEPUB ذو التخطيط الثابت يضعان الصورة بـ`object-fit: cover` مع `object-position` المطابق؛ أما EPUB المرن، الذي لا صفحة فيه تُملأ، فيعرض الصورة كاملة. والمضيف الذي يرسم الصور بنفسه يجد الدوال التي يصدّرها `postext`: `resourceSafeArea` و`normalizeSafeArea` (المنطقة كما يقرؤها المحرّك، أو `undefined`)، و`safeAreaHeightRange` (أقصر جسم وأطوله عند عرض معيّن)، و`safeAreaSource` (الجزء الظاهر عند ارتفاع معيّن)، و`uncroppedPictureBox` (أين تُرسم الصورة كاملة قبل القصّ)، مع النوع `ResourceSafeArea`. وفي Sandbox يحمل الحقل اسم **المنطقة الآمنة**، في صورة من [لوحة الموارد](https://postext.dev/ar/docs/sandbox.md#لوحة-الموارد).

تنضد الوصفة رقم 116 في دليل الوصفات، [صور تطول لتملأ العمود القصير](https://postext.dev/ar/cookbook/photos-fill-short-columns.md)، تحقيقَ مجلة بعمودين مرتين، بلا مناطق آمنة ومعها، لتقارن الصفحات جنبًا إلى جنب.

### نقاط ارتكاز المتحدثين ومناطق التجنب

يمكن للصورة التي تكون رسمًا لإطار في قصة مصورة أن تحدد أيضًا مواضع أشخاصها، لتستعملها كتابة الحوار (انظر [القصص المصورة](https://postext.dev/ar/docs/document-format-directives.md#القصص-المصورة)). يسرد `anchors` نقطة لكل متحدث، ويسرد `avoid` المناطق التي لا تغطيها أي فقاعة، وكلاهما بكسور من الصورة كالمنطقة الآمنة:

```ts
const radio: Resource = {
  id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 },
  safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 },
  anchors: [
    // حارس المنارة: الفم، والرأس (لفقاعات التفكير)، والوجه
    { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } },
  ],
  avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // المذياع
};
```

`id` في نقطة الارتكاز هو مفتاح المتحدث في السيناريو (`tomas: …`)، أو `sfx` للنقطة التي تجتمع عندها المؤثرات الصوتية في الإطار؛ و`x` و`y` هما الفم الذي يتجه إليه ذيل فقاعة الكلام، و`head` النقطة التي تتجه إليها فقاعات ذيل فقاعة التفكير (الفم إن لم تُحدَّد)، و`face` مستطيل لا تغطيه أي فقاعة. ويحوّل المحرّك كل نقطة عبر قصّ الإطار وانعكاسه، فيبقى الذيل على متحدثه أيًا كان الشكل الذي يأخذه الإطار؛ ونقطة الارتكاز الواقعة خارج المنطقة الآمنة تطلق `comicAnchorOutsideSafeArea`، لأن القصّ قد يُخرجها. وهناك قائمة ثالثة، `faces`، تحفظ وجوه من لا يتكلمون، مستطيلات مثل مستطيلات `avoid`: لا تغطيها أي فقاعة، أما منطقة التجنّب فتتنازل حين لا يبقى في الإطار مكان آخر. ونقاط الارتكاز جزء من الصورة، وتخدم كل ترجمات القصة. ولا تقرؤها إلا إطارات القصص المصورة؛ أما الشكل فيتجاهلها. وفي Sandbox تُعلَّم في نافذة **المنطقة الآمنة وكتابة الحوار** في [لوحة الموارد](https://postext.dev/ar/docs/sandbox.md#لوحة-الموارد).

### مقاطع الفيديو

مورد **الفيديو** (`kind: 'video'`) مقطع على يوتيوب أو فيميو، أو فيديو خاص بك: ملف محفوظ في الكتاب (MP4 أو WebM)، أو فيديو على عنوان ويب، ملفًّا على خادم أو **بثًّا بصيغة HLS** (قائمة تشغيل `.m3u8`). يُوضع ويُعلَّق عليه ويُعوَّم ويُحال إليه كما تُعامَل الصورة، ويُرقَّم في تسلسل خاص به: يطبع النوع المدمج `video` *فيديو 1-1* و*فيديو 1-2*… بجانب *شكل 1-1* و*جدول 1-1* (انظر [الإعدادات › أنواع الموارد](https://postext.dev/ar/docs/configuration-resources.md#أنواع-الموارد)). ويعرضه كل مُخرَج بما يستطيع:

| المُخرَج | ما يعرضه |
| --- | --- |
| Canvas وPDF | **الغلاف**، وهو إطار من الفيديو، وعليه علامة تشغيل ورمز QR يفتح الفيديو ([الإعدادات › نمط الفيديو](https://postext.dev/ar/docs/configuration-resources.md#نمط-الفيديو)). وفي PDF يكون الغلاف أيضًا رابطًا إلى الفيديو. |
| Folio | الغلاف كما يُطبع. والنقر عليه يشغّل الفيديو **على الصفحة نفسها**، ويستمر تشغيله والورقة تنقلب (انظر [مقاطع الفيديو على صفحات Folio](https://postext.dev/ar/docs/document-format-resources.md#مقاطع-الفيديو-على-صفحات-folio) أدناه). أما مقاطع يوتيوب وفيميو فتبقى أغلفة. |
| عارض HTML | **مشغّل** الفيديو: مشغّل يوتيوب أو فيميو، أو مشغّل HTML5 في المتصفح للملف أو للعنوان. ويُشغَّل بثّ HLS مباشرةً في Safari وفي الإصدارات الحديثة من Chrome؛ وفي غيرهما يربط المضيف به مشغّلًا مثل hls.js، كما يفعل Sandbox. ومع `videoStyle.html: 'poster'` يعرض الغلاف المطبوع بدلًا منه. |
| EPUB | يُشغَّل الملف في مشغّل نظام القراءة نفسه، محزومًا في الكتاب أو مقروءًا من عنوان نشره. أما فيديو يوتيوب أو فيميو فيظهر غلافُه مربوطًا بالفيديو، لأن EPUB لا يجوز له أن يضمّن مشغّل صفحة ويب. وبثّ HLS كذلك يظهر غلافًا مربوطًا بالفيديو، لأن قائمة تشغيل HLS ليست من أنواع الوسائط التي يجوز لـ EPUB تشغيلها. وإذا كان نظام القراءة يشغّل النصوص البرمجية التزمت ملفات الصفحة الواحدة أو الفصل الواحد بـ `player.exclusive`: تشغيل أحدها يوقف مؤقتًا ما لا يعمل إلى جانبه. |

```ts
const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'الحارس يشرح المصباح.',
  altText: 'حارس منارة بجانب المصباح',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // plays from 0:30; the printed link starts there too
  },
};
```

يحيل النص إلى الفيديو كما يحيل إلى الشكل: `:ref{id="keeper-talk"}` يطبع *فيديو 1-1* ويعوّم الغلاف إلى أول موضع شاغر بعد الإحالة، و`::resource{id="keeper-talk"}` مع `placement.position: 'here'` يضعه داخل التدفق. وهذه حقول `Resource.video` (`ResourceVideo`):

| الحقل | النوع | المعنى |
| --- | --- | --- |
| `source` | `'youtube'` · `'vimeo'` · `'file'` | مصدر تشغيل الفيديو: صفحة على يوتيوب أو فيميو، أو فيديو خاص بك (`'file'`)، مرفوعًا أو على عنوان. |
| `url` | `string` | يوتيوب أو فيميو: عنوان الفيديو بأي صيغة (صفحة مشاهدة، أو `youtu.be`، أو Shorts، أو رابط تضمين، أو `youtube-nocookie.com`؛ أو صفحة على فيميو، أو صفحة قناة، أو رابط غير مُدرج مع رمز التجزئة الخاص به). الملف: **عنوان نشره**، أي المكان الذي سيجده فيه الكتاب المنشور. والفيديو الخاص بك الذي لا ملف له يُشغَّل من هذا العنوان: ملف MP4 أو WebM على خادم، أو بثّ HLS (`…/master.m3u8`). |
| `fileId`، `format` | `string` | الملف: الفيديو المرفوع، مخزّنًا خارج المستند كالصورة النقطية، وصيغته: `'mp4'` أو `'webm'` أو `'ogv'` أو `'mov'`، أو `'hls'` لبثّ HLS. وحين لا تُذكر الصيغة يدلّ عليها امتداد العنوان (`.m3u8` تعني `'hls'`)، وإلا فهي `'mp4'`. |
| `poster` | `{ fileId, format, width, height }` | إطار الغلاف، وهو صورة نقطية. |
| `width`، `height`، `duration` | `number` | حجم إطار الفيديو بـ px (ومنه نسبة أبعاده حين لا يكون له غلاف) وطوله بالثواني. |
| `posterTime` | `number` | الثانية التي أُخذ منها إطار الغلاف في الملف، تُحفظ ليمكن اختياره من جديد. |
| `start`، `end` | `number` | يُشغَّل من الثانية `start` إلى الثانية `end`. ويبدأ رمز QR ورابط PDF من `start` أيضًا. |
| `player` | `VideoPlayerOptions` | خيارات مشغّل هذا الفيديو، تُطبَّق فوق `videoStyle.player`. |

**الغلاف.** يُنضَّد بعرض موضعه (أو بالكسر `placement.width` منه)، بنسبة أبعاده، أيًّا كان حجمه بالبكسل: فالإطار بحجم الشاشة يُكبَّر بدل أن يُطبع صغيرًا. ويمكن أن يحمل، كالصورة النقطية، [منطقة آمنة](https://postext.dev/ar/docs/document-format-resources.md#المنطقة-الآمنة) وأن يتبع `placement.align`. والفيديو الذي بلا غلاف يُطبع مربعًا داكنًا بنسبة أبعاد الفيديو (16:9 حين لا يُعرف غيرها) وعليه علامة التشغيل ورمز QR، ويُطلق تحذير المحتوى `videoWithoutPoster`. وفي Sandbox يُجلب غلاف فيديو يوتيوب أو فيميو من المنصة عند إدخال عنوانه، أما غلاف الملف فإطار تختاره من الفيديو.

**العنوان.** يفتح رمز QR ورابط PDF صفحة الفيديو، `https://youtu.be/<id>` أو `https://vimeo.com/<id>`، بدءًا من `start`. أما الملف فلا صفحة له، فيفتحان عنوان نشره، وهو أيضًا المكان الذي يُشغَّل منه الفيديو الذي لا ملف له (ملف MP4 على خادم، أو بثّ HLS). ومن دون هذا العنوان لا يحمل المطبوع رمز QR ولا رابطًا (`videoWithoutUrl`)، ويعرض مُخرَج HTML أو EPUB الذي لا يحمل الملفَ الغلافَ. والعنوان على يوتيوب أو فيميو الذي لا يسمّي فيديو من تلك المنصة يُطلق `videoUrlInvalid`، ويُعرض الغلاف مكان المشغّل.

**المشغّلات.** تُضبط خيارات المشغّل (أدوات التحكم، وزر التنزيل، وملء الشاشة، وقائمة السرعة، وصورة داخل صورة، والإرسال إلى شاشة، والتشغيل التلقائي، والبدء دون صوت، والتكرار، والتحميل المسبق، والتضمين مع خصوصية معزَّزة) للكتاب كله في `videoStyle.player`، ولفيديو واحد في `video.player`؛ ويراعي كل مشغّل ما يستطيع منها (انظر [الإعدادات › نمط الفيديو](https://postext.dev/ar/docs/configuration-resources.md#نمط-الفيديو)). ويتلقى مُخرِج HTML عنوان URL القابل للتشغيل لكل ملف عبر الخيار `resourceVideoUrl(fileId)`، كما يتلقى الصور عبر `resourceImageUrl`، ويعود إلى عنوان النشر حين لا يجده. ويختار خياره `videos: { files, streams, hls }` بين المشغّل والغلاف لكل مصدر، متقدّمًا على `videoStyle.html` (و`hls`، أي الفيديو المُشغَّل من عنوان HLS، يتبع `files` ما لم يُضبط)؛ ويستعمله كاتب EPUB. ويحمل عنصر `<video>` الذي يشغّل عنوان HLS السمة `data-pt-hls`، ليستطيع المضيف أن يعطيه مشغّلًا في المتصفحات التي لا تدعم HLS بنفسها (أما Safari والإصدارات الحديثة من Chrome فتشغّله كما هو). وفي كتاب يُقرأ من اليمين إلى اليسار لا يُعكس المشغّل ولا ما يُطبع فوق الغلاف، كما لا تُعكس الصورة، فيبقى رمز QR مقروءًا.

**في VDT.** لكتلة مورد الفيديو `kind: 'video'`، وغلافها في `fileId` / `format` (يُرسم كالصورة النقطية)، و`video` (`VDTResourceVideo`): الرابط `link` الذي يُرسَل إليه القارئ، و`embedUrl` ليوتيوب أو فيميو بعد تطبيق خيارات المشغّل، و`fileId` للملف، و`mimeType` للفيديو الخاص بك (لملفه أو لعنوانه وحده، و`application/vnd.apple.mpegurl` لبثّ HLS)، والمجال `start` / `end`، و`player` المحسوم، و`linkPoster`، و`html`، والطبقتان `playMark` و`qr` (وحدات رمز QR صفوفًا من `'0'` / `'1'`)، بمستطيلات تُقاس من الزاوية العليا اليسرى لجسم المورد. والمضيف الذي يرسم مقاطع الفيديو بنفسه يجد الدوال التي يصدّرها `postext`: `parseVideoUrl` و`videoWatchUrl` و`resourceVideoLink` و`videoEmbedUrl` و`videoEmbedAllow` و`videoElementAttributes` و`mediaFragment` و`videoMimeType` و`videoFormatOfUrl` و`resourceVideoFormat` و`isHlsMimeType` و`HLS_MIME_TYPE` و`youtubePosterUrls` و`encodeQr` و`layoutVideo` و`playMarkTriangle` و`qrModuleRuns`.

**في الحزمة.** يحمل ملف `.postext` ملفَّ الفيديو (`resources/<id>.mp4`) والغلاف (`resources/<id>.poster.jpg`): يسمّيهما مدخل البيان (manifest) في `file` و`poster`، ويعطي حجم الغلاف في `width` / `height`، ويحفظ الباقي في `video` بلا معرّفات ملفات. و`bundleVideoUrl(bundle)` هي دالة الحلّ `resourceVideoUrl` على ملفات الحزمة. والفيديو المُشغَّل من عنوان وحده لا يحمل ملفًّا: ليس في مدخله إلا الغلاف. وفي الحزمة ثنائية اللغة يمكن أن تعطي لغةٌ الفيديو غلافها `poster` وفيديوها `video` الخاصّين بها (نسخة أخرى من المقطع، على عنوانها الخاص) في `localized[…].resources`.

#### مقاطع الفيديو على صفحات Folio

في [الكتاب ثلاثي الأبعاد](https://postext.dev/ar/docs/configuration-html-folio-epub.md#كتاب-ثلاثي-الأبعاد-postext-folio) يُشغَّل الفيديو الخاص بك على الصفحة المطبوع عليها. ويبدأ النقر على الغلاف تشغيله هناك، أيًّا كان ما يفعله المؤشر على الكتاب (قلب الصفحات، أو تدوير المنظر، أو تحديد النص): يرسم مظلِّل (shader) الصفحة إطارات الفيديو فوق الغلاف، فتنثني الصورة وتلتفّ مع الورق حين تُقلب الورقة، ويستمر التشغيل أثناء القلب. والنقر على فيديو يعمل يوقفه مؤقتًا، والنقر على فيديو متوقف يستأنفه، ويفعل مفتاح المسافة أو Enter الشيء نفسه لأول فيديو في الصفحتين المفتوحتين. وتشغيل فيديو آخر يوقف الفيديو العامل (فيعود إلى غلافه)، ويتوقف الفيديو حين يستقر الكتاب على صفحتين متقابلتين لم تعودا تعرضانه، أو عند بلوغه `end`. ويصير المؤشر يدًا فوق فيديو يمكنه تشغيله؛ والسحب الذي يبدأ عليه يقلب الصفحة أو يدير المنظر مع ذلك. والفيديو المضبوط ليبدأ وحده (`video.player.autoplay`) يبدأ تشغيله تلقائيًا أول مرة يستقر فيها الكتاب على صفحتيه، بعد أن يهدأ الكتاب (ويدخل في ذلك المضيف الذي يُخرجه على مراحل)، ولا يبدأ وحده بعدها أبدًا في أداة العرض تلك.

الفيديو الذي يعمل إلى جانب غيره (`video.player.exclusive: false`، منذ postext 1.18) يغيّر القاعدتين. تشغيله لا يوقف إلا المقاطع الحصرية، فتعمل عدة مقاطع من هذا النوع معًا؛ وتشغيل فيديو حصري يوقفه هو أيضًا. ومع `autoplay` يبدأ صامتًا كلما استقر الكتاب على صفحتيه المتقابلتين، ويتوقف حين تُقلبان: فتعمل المقاطع الصامتة المتكررة (`loop`) في الصفحة معًا كلما وصل إليها القارئ.

- **ما يُشغَّل.** الملف (يحوّل المضيف `fileId` الخاص به إلى عنوان URL بالخيار `videoUrl`، وهو في Sandbox عنوان كائن object URL)، أو عنوانه إن لم يكن له ملف: MP4 أو WebM أو بثّ HLS. ويُشغَّل بثّ HLS عبر [hls.js](https://github.com/video-dev/hls.js) حيثما توفرت في المتصفح امتدادات مصدر الوسائط (Media Source Extensions)، ويُحمَّل عند أول تشغيل (وهو تبعية نظيرة اختيارية لـ `postext-folio`)، مقصورًا على النسخة الأقرب إلى حجم الصورة على الشاشة، فلا تجلب صورة لا يتجاوز ارتفاعها بضع مئات من البكسلات نسخةً بدقة 4K؛ ويبقى دعم HLS المدمج في المتصفح بديلًا احتياطيًا. وتحمل طلباته معامل استعلام خاصًّا بها، `pt-cors`، فلا تعطيها ذاكرة التخزين المؤقت في المتصفح نسخة جلبها مشغّل آخر دون CORS. أما يوتيوب وفيميو فيُشغَّلان في إطارات iframe لا يستطيع WebGL رسمها: فالنقر على غلافهما يقلب الصفحة كما في أي موضع آخر.
- **القراءة من مصدر آخر.** لا يرسم WebGL الفيديو إلا حين يسمح خادمه بقراءته (CORS، `Access-Control-Allow-Origin`). والفيديو الذي لا تمكن قراءته يبقى غلافًا، ويتلقّى `onVideo` الحالة `error`.
- **الصوت.** يسمح النقر بتشغيل الفيديو بصوته؛ والمتصفح الذي يرفض ذلك مع هذا يشغّله دون صوت. والفيديو الذي يبدأ وحده يكون بصوته متى نقر القارئ على الصفحة أو كتب فيها (والانتقال إليها بالقلب يُحتسب)؛ وقبل ذلك يبدأ دون صوت، والنقر عليه يعيد إليه صوته قبل أن توقفه النقرة التالية مؤقتًا. ويبدأ `video.player.muted` التشغيل دون صوت، ويعيده `loop` من أوله، ويحدّد `start` / `end` الجزء الذي يُشغَّل.
- **على كل صفحة.** تُرسم الصورة حيث يضعها الإخراج: مُدارةً مع المورد المُدار، وقائمةً على الصفحة العمودية، وغير معكوسة في الكتاب الذي يُقرأ من اليمين إلى اليسار، كالغلاف تمامًا. والغلاف المقصوص داخل [منطقته الآمنة](https://postext.dev/ar/docs/document-format-resources.md#المنطقة-الآمنة) يُقصّ الفيديو بالطريقة نفسها.
- **دون WebGL2**، أو مع تقليل الحركة، يُشغَّل الفيديو في عنصر HTML `<video>` موضوع فوق الصفحة.

```ts
const book = createFolioFromDocument(container, doc, {
  // An uploaded video's playable URL (an object URL over its bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();
```

ويعطّل `videos: false` هذه الميزة. وتفعل `toggleVideoAt({ page, x, y })` ما تفعله النقرة في ذلك الموضع، وتسرد `pageVideoSpots(page, doc)` مواضع مقاطع الفيديو في الصفحة، للمضيف الذي يرسم أدوات تحكّمه بنفسه.

وصفتان في دليل الوصفات تضعان مقاطع فيديو: الوصفة رقم 131، [برنامج نادٍ سينمائي برموز QR على الأغلفة](https://postext.dev/ar/cookbook/film-club-video-qr.md)، تطبع كل فيلم بطاقةَ عنوان عليها علامة التشغيل ورمز QR، والوصفة رقم 132، [ورقة تجربة تُعرض مقاطعها على الشاشة وفي EPUB](https://postext.dev/ar/cookbook/pendulum-lab-video-players.md)، تضبط خيارات المشغّل في نسخة HTML وتحزم مقاطعها في EPUB ثابت التخطيط.