الوسائط المتعددة: العرض، ومقطع الوسائط، ومعاملات الشاشة

نظرة سريعة

تُنمذج وحدة الوسائط المتعددة عرض تنسيق المستندات المحمولة (⁨PDF⁩) ومعاملات الوسائط الخاصة به بوصفها كائنات قيمة غير قابلة للتغيير. يتحقق كل كائن من ثوابت ⁨ISO 32000-2⁩ الخاصة به داخل المُنشئ، ثم يسلْسل نفسه إلى قاموس ⁨PDF⁩ المطابق. يشير إجراء العرض في وحدة التنقل إلى ذلك القاموس.

النطاق: نموذج كائن العرض فقط

توفّر هذه الوحدة نموذج كائن العرض: المُرمِّز مضبوط النوع لقواميس Rendition / MediaClip / معاملات الوسائط في ⁨ISO 32000-2⁩ §13.2. أما إجراء العرض الكامل لتعليق الشاشة (الواجهة في §12.5.6.18 / §13 التي تربط العرض بتعليق شاشة للتشغيل) فهو غير مدعوم أو متحقَّق منه بعد في هذا الإصدار. كما أن أنواع تعليقات الوسائط المهملة (3⁨D⁩ و⁨RichMedia⁩ و⁨Sound⁩ و⁨Movie⁩؛ انظر ⁨ISO 32000-2⁩ §12.5.2) خارج النطاق أيضًا. استخدم الكائنات الهيكلية أدناه لوصف النموذج وبنائه؛ ولا تعتمد على إجراء تعليق شاشة قابل للتشغيل.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية عامة

يصف عرض ⁨PDF⁩ وسائط قابلة للتشغيل، مثل الصوت أو الفيديو أو مقطع تفاعلي، والشروط التي يشغّل العارض الوسائط ضمنها. يعرّف ⁨ISO 32000-2⁩ §13.2 نموذج العرض وكائن الوسائط. هذه الوحدة هي المُرمِّز مضبوط النوع والمتحقِّق لذلك النموذج. كل صنف هو كائن قيمة final readonly: يقبل المُدخلات في المُنشئ، ويفرض القواعد الهيكلية للمواصفة هناك، ويُصدر سلسلة قاموس ⁨PDF⁩ من toDictionary(). لا يشغّل الوسائط ولا يضمّن بيانات الملفات. وينتج عنه القاموس الذي يسلْسله ⁨Writer⁩.

Rendition هو الجذر. يحمل عرض الوسائط (/MR) MediaClip ومعاملات تشغيل وشاشة اختيارية. ويحمل عرض المُحدِّد (/SR) قائمة مرتَّبة من مراجع العرض الاحتياطية. يفرض المُنشئ الاستبعادات المتبادلة في المواصفة: يتطلب /MR مقطعًا ويرفض مراجع المُحدِّد، بينما يرفض /SR مُدخلات المقطع والتشغيل والشاشة. ونتيجة لذلك، لا يمكن إنشاء عرض غير صالح.

يمثّل MediaClip بيانات الوسائط أو قسمًا منها. يتيح النوع الفرعي للقسم للعرض تشغيل نطاق فرعي دون نسخ البيانات. يحمل MediaPlayInfo وMediaScreenInfo معاملات التشغيل (/P) وعرض الشاشة (/SP). ويكشف كلاهما عن isEmpty() حتى تتمكن من حذف المُدخل عندما توصي المواصفة بالحذف بدلًا من قاموس فارغ. يحمل MediaCriteria مجموعتَي المتطلبات الواجب احترامها (/MH) وأفضل جهد ممكن (/BE)، مع منفذ هروب extras للمُدخلات التي لا تنمذجها الواجهة مضبوطة النوع. الوحدة بأكملها @since 2.3.0.

واجهة ⁨API⁩

الصنف	الأعضاء الرئيسيون	الدور
Rendition	__construct(...)، toDictionary()، SUBTYPE_MEDIA، SUBTYPE_SELECTOR	كائن عرض /MR أو /SR (@since 2.3.0)
MediaClip	__construct(...)، toDictionary()، SUBTYPE_DATA، SUBTYPE_SECTION	كائن بيانات / قسم مقطع الوسائط (@since 2.3.0)
MediaPlayInfo	toDictionary()، isEmpty()	معاملات التشغيل /P (@since 2.3.0)
MediaScreenInfo	toDictionary()، isEmpty()	معاملات الشاشة /SP (@since 2.3.0)
MediaCriteria	toDictionary()، isEmpty()	مجموعتا المتطلبات /MH و/BE (@since 2.3.0)

شغّل composer docs:generate-api-php -- --module=Multimedia لإنشاء جدول ⁨PHPDoc⁩ الكامل.

عينة شيفرة — بداية سريعة

أنشئ عرض وسائط لمقطع فيديو مضمَّن.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Multimedia\MediaClip;
use NextPDF\Multimedia\Rendition;

$clip = new MediaClip(
    subtype: MediaClip::SUBTYPE_DATA,
    dataRef: 42, // indirect object number of the embedded file specification
);

$rendition = new Rendition(
    subtype: Rendition::SUBTYPE_MEDIA,
    name: 'Intro Video',
    clip: $clip,
);

$dictionary = $rendition->toDictionary();

عينة شيفرة — الإنتاج

أنشئ عرض مُحدِّدًا يتبع سلسلة احتياطية مرتَّبة ويفصل صراحةً بين معايير الواجب احترامها وأفضل جهد ممكن.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Multimedia\MediaCriteria;
use NextPDF\Multimedia\Rendition;

// Preferred rendition first, degraded fallback second.
$selector = new Rendition(
    subtype: Rendition::SUBTYPE_SELECTOR,
    name: 'Adaptive Media',
    mustHonour: new MediaCriteria(/* strict /MH requirements */),
    bestEffort: new MediaCriteria(/* soft /BE requirements */),
    selectorRefs: [51, 52], // indirect rendition object numbers, in evaluation order
);

$dictionary = $selector->toDictionary();

الحالات الحدية والمزالق

• يطرح عرض /MR دون MediaClip استثناءً في المُنشئ. هذه قاعدة من المواصفة، وليست تحذيرًا في وقت التشغيل. أنشئه مع المقطع.
• يرفض عرض /SR مُدخلات المقطع والتشغيل والشاشة. إن خلط شكلَي العرض خطأ برمجي يُكتشف عند الإنشاء.
• استخدم MediaPlayInfo::isEmpty() وMediaScreenInfo::isEmpty() لحذف /P أو /SP الفارغ. إن إصدار قاموس فارغ في موضع توصي فيه المواصفة بالحذف صالح هيكليًا لكنه مُهدِر؛ تحقق من isEmpty().
• يجب ألا يحتوي اسم العرض /N على بايت ⁨NUL.⁩ يرفضه المُنشئ.
• selectorRefs هي أرقام كائنات غير مباشرة، كل منها >= 1. تُصدر الوحدة المراجع؛ أما تحويلها إلى كائنات حيّة فهو من مهمة ⁨Writer.⁩

الأداء

يبني كل استدعاء لـ toDictionary() سلسلة خطيًا من مجموعة ثابتة من المُدخلات. يعمل على مقياس الميكروثانية ولا يجري أي عمليات ⁨input/output⁩ (⁨I/O⁩). ملف تعريف قابلية إعادة الإنتاج هو bitwise: يُصدر كائن القيمة نفسه دائمًا بايتات القاموس نفسها. يبقى عبء العمل المرجعي الافتراضي ضمن ميزانية الـ 1500 ⁨ms⁩ للزمن الجداري / 64 ⁨MB⁩ للذروة بهامش جيد. قواميس الوسائط المتعددة صغيرة مقارنةً بالوسائط المضمَّنة التي تشير إليها.

ملاحظات أمنية

تُصدر هذه الوحدة بنية القاموس؛ ولا تضمّن بيانات الوسائط أو تنقلها. تنتج واجهة إرفاق الملفات في وحدة التنقل مواصفة الملف المضمَّن التي يشير إليها MediaClip، وهي تحدّ البايتات المضمَّنة وتتحقق منها. تعامل مع أي اسم ملف وسائط أو اسم عرض وارد من مُدخلات المستخدم كنص غير موثوق. يرفض المُنشئ بايتات ⁨NUL⁩ لكنه لا يدقق المحتوى الدلالي لسلسلة صالحة. انظر نموذج تهديد المحرك في /modules/core/security/.

المطابقة

تتبع القواميس التي تُصدرها هذه الوحدة نموذج العرض وكائن الوسائط في ⁨ISO 32000-2⁩ §13.2، بما في ذلك مُدخلات بيانات مقطع الوسائط والقسم. إن تعيينات المُدخلات لكل جدول موثَّقة ضمنيًا في src/Multimedia/ مقابل أرقام جداول §13.2 ومُغطّاة بـ tests/Unit/Multimedia/ (RenditionTest، MediaClipTest، MediaCriteriaTest، MediaPlayInfoTest، MediaScreenInfoTest). هذه حقائق تنفيذ، وليست إقرارًا بمطابقة ⁨PDF 2.0⁩ الكاملة؛ إذ تتحقق المجموعات المرجعية (⁨oracle⁩) والذهبية الموصوفة في /modules/core/conformance/ من مطابقة المستند الكامل.

انظر أيضًا

• وحدة التنقل — إجراء العرض الذي سيشير إلى هذه الكائنات. إجراء العرض لتعليق الشاشة غير مدعوم بعد؛ انظر ملاحظة النطاق أعلاه.
• وحدة ⁨Writer⁩ — تحوّل القواميس المُصدَرة تسلسليًا.
• نظرة عامة على المطابقة
• نموذج أمان المحرك