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

#الموارد

لا تُكتب الصور ورسوم SVG والجداول ومقاطع الفيديو داخل النص. تُعرَّف مرة واحدة بوصفها موارد (تديرها لوحة الموارد في Sandbox، وفيها رفع الصور وملفات SVG، ومحرّر جداول تفاعلي، ومقاطع يوتيوب وفيميو والفيديو المرفوع، وتحرير التعليقات والمواضع)، ثم تُربط بنصّك عبر معرّفها. تكفي الإحالة إلى المورد لإدراجه: تذكره مرة واحدة بإحالة داخل السطر :ref{id="…"}، فيُعوِّم المحرّك الشكل أو الجدول إلى أول موضع شاغر بعد تلك الإحالة، كأسفل العمود الذي ذكرته فيه، أو أعلى العمود التالي، أو شريط في الصفحة التالية، كما يفعل المنضّد في المطبعة. ولا تضعه مرة ثانية.

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

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

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

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. ويطفو الرسم نفسه إلى أقرب موضع شاغر بعد الجملة (أسفل هذا العمود، أو أعلى العمود التالي، أو شريط في الصفحة التالية)، بينما تتدفق هذه الجملة والنص الذي يليها دون انقطاع.

لا ينقطع النص الجاري أبدًا عند نقطة الإحالة. أما المكان الذي يستقر فيه المورد (أول موضع شاغر، أو موضع علوي أو سفلي فقط؛ داخل عمود واحد أو بعرض الصفحة كله) فيحكمه موضعه (انظر الموضع أدناه)، ويحكمه كذلك المكان الذي تذكره فيه: يبدأ البحث مباشرة بعد الإحالة.

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

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

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. وتحكم تنسيقه الإعدادات › نمط التعليق: تتشارك التسمية والوصف خطًا واحدًا وحجمًا واحدًا، بينما تحتفظ التسمية بإعدادات مستقلة للعريض والمائل واللون؛ والفجوة فوق التعليق 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 كانت الشرطتان تُطبعان، ولم يكن التعليق أو الملاحظة ينكسر إلا حيث ينتهي عرض السطر.)

ترسم موارد الجداول شبكتها الخاصة، وتُنسَّق عبر الإعدادات › نمط الجدول: لخلايا المتن وخلايا الترويسة تنسيق مستقل تمامًا، وخلفية الترويسة #f0f0f0 افتراضيًا، والحدود 0.75pt، وcellPadding قيمته 0.375em؛ وكل حقل لم يُضبط يرث من نص المتن. عروض الأعمدة جزء من الجدول نفسه: يحمل TableModel.columnWidths وزنًا نسبيًا واحدًا لكل عمود ([2, 1, 1] يمنح العمود الأول نصف العرض)؛ وإذا لم يُضبط، تقاسمت الأعمدة العرض بالتساوي. ويمكن أيضًا تنضيد الجدول بنمط مسمّى: يختار table.styleId واحدًا من tableStyles في المستند (انظر الإعدادات › أنماط الجداول المسمّاة)، وترث حقوله غير المضبوطة من 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() أيضًا، فيكون لتعبئة الخلية الشفافة مفتاح شفاف مطابق (انظر الإعدادات › الشفافية).

ويمكن كذلك إعادة تلوين موارد SVG للطباعة بلون موضعي واحد عبر diagramStyle.singleInk (القيمة الافتراضية false). عند تفعيله، يُعاد تعيين كل لون في رسم SVG إلى درجة من diagramStyle.inkColor بحسب سطوعه (وقيمته الافتراضية لون لوحة الألوان الرئيسي، #295AA3)، فيصير الأبيض لون الورق والأسود الحبر كاملًا، فتُطبع الأشكال بأمانة حين يُطبع المستند بلون موضعي واحد. انظر الإعدادات › نمط الرسوم التخطيطية.

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

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

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

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

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

الترقيم خاص بكل نوع مورد، ويراعي نطاق إعادة الضبط وصيغة العدّاد لكل نوع؛ انظر الإعدادات › أنواع الموارد لرموز القالب ({h1}، {n})، وresetOn، وcounterFormat.

لا يُعدّ إلا ما يحيل إليه النص: المورد الذي لا يرسمه إلا التصميم (عنصر صورة في صفحة افتتاح الفصل مثلًا) لا يأخذ رقمًا ويترك العدّاد على حاله. ويعدّ {h1} كل عنوان من المستوى 1 لا يكون نمطه numbered: false، حتى لو كان numberingTemplate فيه فارغًا، فالمقالة التي عنوانها هو عنوانها الوحيد من المستوى الأول ترقّم أشكالها 1.1، 1.2… افتراضيًا. وفي الإعدادات › ما الذي يُرقَّم القاعدتان كلتاهما والإعدادات اللازمة لـ Figure 1، 2….

#الموضع

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

يذهب العنصر العائم إلى أول موضع شاغر بعد إحالته الأولى، بترتيب القراءة: أسفل العمود الذي تقع فيه الإحالة، ثم أعلى العمود الفارغ التالي في الصفحة نفسها وأسفله، ثم أشرطة الصفحة التالية التي يفتحها التدفق (العنصر العائم بعرض الصفحة يأخذ أسفل الصفحة حين يبقى في كل عمود متسع له، وإلا فشريطًا في الصفحة التالية). والصفحة التي يفتحها شكل أو جدول مضمّن داخل التدفق تُحتسب أيضًا: العنصر العائم الذي ينتظر تلك الصفحة يأخذ رأسها، فوق الشكل أو الجدول، حين يتسع لهما معًا؛ وإن لم يتسع، احتفظ الشكل أو الجدول بالصفحة وانتظر العنصر العائم الصفحة التالية. وحتى 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 تُبقي على ذلك (انظر الإعدادات › التخطيط).

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

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

في الصفحة الختامية للفصل، وللمستند، لا يلي الأشكالَ والجداول بعرض الصفحة المنضّدة تحت آخر شريط نص شيءٌ، فترتفع لتقع على بُعد فجوة عنصر عائم واحدة تحته، متراصّة بترتيبها، بدل أن تترك بياضًا بين النص وشكل في أسفل الصفحة. ويسري ذلك على العنصر العائم ذي position: 'bottom' أيضًا. لإبقائها في أسفل الصفحة، كما في كل صفحة أخرى، اضبط layout.hugClosingFloats: false (انظر الإعدادات › التخطيط). ولا تحرّكها أبدًا الصفحات التي فيها عمود جانبي.

ترسم الموارد المُخرِجات الثلاثة كلها: معاينة Canvas، وعارض HTML، ومخرجات PDF. وفي مُخرِج HTML تقيم بيانات الصور خارج المستند، فيوفّرها المضيف عبر خيار المُحلِّل resourceImageUrl(fileId)؛ وحين يغيب المُحلِّل (أو لا يعيد شيئًا لملف ما)، يُعرض المورد مربعًا محايدًا بديلًا كي يبقى التخطيط ثابتًا. ويأتي ملف الفيديو نفسه عبر resourceVideoUrl(fileId) بالطريقة نفسها (انظر مقاطع الفيديو).

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

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

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

#التفاف النص

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

{ "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 العنصر العائم أو الإدراج المضمّن إلى كسر من عموده (أو صفحته)، والصورة الأكبر من تلك الحصة تُصغَّر إليها أيًّا كانت بكسلاتها (انظر الموضع).

وفي كل الحالات تحدّ الخانةُ الصورةَ مع الحفاظ على تناسبها، ولا تُكبَّر الصورة الأصغر أبدًا. والمقاس الطبيعي نفسه ينطبق على الصورة في خلية جدول وعلى عنصر image في التصميم بمقاس 'auto'. ويضمّن PDF الملف كما هو بالمقاس الذي وُضع به. ويتحقق الفحص قبل الطباعة من الدقة التي تُطبع بها كل صورة، وتعرضها لوحة الموارد في Sandbox لكل صورة. منذ postext 1.24.

{ "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 كسران من ارتفاعها. الاسم يقول ما يجب أن يبقى؛ أما صندوق القصّ فيقول أين يُقطع.

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 تُقصّ الصورة الأطول من الصفحة أولًا داخل منطقتها الآمنة، مع الحفاظ على عرضها، ولا تُصغَّر إلا إذا بقيت أطول مما ينبغي (انظر الإعدادات › التخطيط).
• أشرطة أقصر من الشكل. العنصر العائم الذي يصغّره placement.shrink إلى حيّز موضعه يُقصّ أولًا داخل منطقته الآمنة، محتفظًا بعرضه، ثم يُصغَّر بعد ذلك فقط؛ ولا تُطيله رافعة flexFigure أدناه أبدًا إلى ما بعد ذلك الحيّز.
• موازنة الأعمدة. الصورة ذات المنطقة الآمنة المضمّنة في عمود قصير، أو العائمة في رأس ذلك العمود أو أسفله وفوقه وحده، تطول بأسطر كاملة من شبكة خطوط الأساس حتى تملأ الأسطر الفارغة في العمود. والصورة الأطول لا تترك فجوة ظاهرة، ولذلك تُجرَّب هذه الأداة، flexFigure، بعد الإطار الذي يختم العمود مباشرة وقبل إضافة أي مسافة فوق العناوين أو بعد القوائم. أما العنصر العائم في رأس عمود من الصفحة الختامية لفصل، أو من شريط ختامي، فلا يطول، لأن رؤوس الأعمدة هناك تبقى متساوية (انظر الإعدادات › موازنة الأعمدة).

تسجّل شجرة 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 يحمل الحقل اسم المنطقة الآمنة، في صورة من لوحة الموارد.

تنضد الوصفة رقم 116 في دليل الوصفات، صور تطول لتملأ العمود القصير، تحقيقَ مجلة بعمودين مرتين، بلا مناطق آمنة ومعها، لتقارن الصفحات جنبًا إلى جنب.

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

يمكن للصورة التي تكون رسمًا لإطار في قصة مصورة أن تحدد أيضًا مواضع أشخاصها، لتستعملها كتابة الحوار (انظر القصص المصورة). يسرد anchors نقطة لكل متحدث، ويسرد avoid المناطق التي لا تغطيها أي فقاعة، وكلاهما بكسور من الصورة كالمنطقة الآمنة:

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 تُعلَّم في نافذة المنطقة الآمنة وكتابة الحوار في لوحة الموارد.

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

مورد الفيديو (kind: 'video') مقطع على يوتيوب أو فيميو، أو فيديو خاص بك: ملف محفوظ في الكتاب (MP4 أو WebM)، أو فيديو على عنوان ويب، ملفًّا على خادم أو بثًّا بصيغة HLS (قائمة تشغيل .m3u8). يُوضع ويُعلَّق عليه ويُعوَّم ويُحال إليه كما تُعامَل الصورة، ويُرقَّم في تسلسل خاص به: يطبع النوع المدمج video فيديو 1-1 وفيديو 1-2… بجانب شكل 1-1 وجدول 1-1 (انظر الإعدادات › أنواع الموارد). ويعرضه كل مُخرَج بما يستطيع:

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):

الغلاف. يُنضَّد بعرض موضعه (أو بالكسر placement.width منه)، بنسبة أبعاده، أيًّا كان حجمه بالبكسل: فالإطار بحجم الشاشة يُكبَّر بدل أن يُطبع صغيرًا. ويمكن أن يحمل، كالصورة النقطية، منطقة آمنة وأن يتبع 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؛ ويراعي كل مشغّل ما يستطيع منها (انظر الإعدادات › نمط الفيديو). ويتلقى مُخرِج 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

في الكتاب ثلاثي الأبعاد يُشغَّل الفيديو الخاص بك على الصفحة المطبوع عليها. ويبدأ النقر على الغلاف تشغيله هناك، أيًّا كان ما يفعله المؤشر على الكتاب (قلب الصفحات، أو تدوير المنظر، أو تحديد النص): يرسم مظلِّل (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 حيثما توفرت في المتصفح امتدادات مصدر الوسائط (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 الجزء الذي يُشغَّل.
• على كل صفحة. تُرسم الصورة حيث يضعها الإخراج: مُدارةً مع المورد المُدار، وقائمةً على الصفحة العمودية، وغير معكوسة في الكتاب الذي يُقرأ من اليمين إلى اليسار، كالغلاف تمامًا. والغلاف المقصوص داخل منطقته الآمنة يُقصّ الفيديو بالطريقة نفسها.
• دون WebGL2، أو مع تقليل الحركة، يُشغَّل الفيديو في عنصر HTML <video> موضوع فوق الصفحة.

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 على الأغلفة، تطبع كل فيلم بطاقةَ عنوان عليها علامة التشغيل ورمز QR، والوصفة رقم 132، ورقة تجربة تُعرض مقاطعها على الشاشة وفي EPUB، تضبط خيارات المشغّل في نسخة HTML وتحزم مقاطعها في EPUB ثابت التخطيط.