أخطاء العرض والإدخال/الإخراج

النطاق

تغطي هذه المداخل استثناءات العرض والإدخال/الإخراج (⁨I/O⁩) المُطلَقة بينما يخطّط خط أنابيب ⁨HTML⁩ المحتوى، ويُسنِد مُحلِّل الوسائط المقسّمة على صفحات هندسة الصفحة، ويعالج مُشكِّل النص النصوص المعقّدة، وتكسر مرحلة الطباعة الأسطر، ويُسلسِل الكاتب مستندًا، ويُحلّل القارئ ملف ⁨PDF⁩ قائمًا، وتقرأ مرحلة البيانات الوصفية حزمة منصّة البيانات الوصفية القابلة للتوسعة (⁨XMP⁩).

يظهر هرمان أساسيان أدناه، ويحكم الفرق بينهما البيانات التشخيصية التي يمكنك قراءتها بعد catch:

• NextPdfException تطبّق ContextAwareExceptionInterface::getContext(): array. ويُرجع التطبيق الأساسي مصفوفة فارغة؛ ولا تحمل الفئة الفرعية مفاتيح مُنظَّمة إلا حين تتجاوز getContext(). أما الفئات الفرعية التي لا تتجاوزه فتكشف بياناتها عبر خصائص public readonly.
• تمدّد عدة فئات هنا فئة ⁨PHP⁩ المسماة RuntimeException مباشرةً. وهي ليست مُدركة للسياق وليس لها طريقة getContext()؛ اقرأ بدلًا من ذلك getMessage() وأي خصائص عامة لها.

يذكر كل مدخل الفئة بالضبط، وشرط الإطلاق، ومفاتيح السياق أو الخصائص العامة التي يحملها، ومسار التعافي.

تخطيط ⁨HTML⁩ والوسائط المقسّمة على صفحات

UnsplittableContentException

• متى يُطلَق. يُطلقه محرك تخطيط ⁨HTML⁩ عندما يكون لمحتوى مُعلَّم بـbreak-inside: avoid (خلية جدول قيد كسرها Avoid) ارتفاع مُقاس يتجاوز الارتفاع القابل للاستعمال لصفحة واحدة. لا يستطيع المحرك أن يستوفي قيد تجنّب الكسر وحدّ الصفحة معًا، فيُخفق بدلًا من أن يفيض بصمت.
• البيانات المحمولة. يمدّد NextPdfException لكنه لا يتجاوز getContext()، لذا يُرجع getContext() مصفوفة فارغة. والبيانات التشخيصية على خصائص public readonly: gridRow (int)، وgridCol (int)، وcontentHeight (float، بالنقاط)، وpageHeight (float، بالنقاط). وتذكر الرسالة إحداثيات الخلية وكلا الارتفاعين.
• التعافي. أزِل قيد break-inside: avoid على الخلية المُخالفة، أو قلّل محتوى الخلية ليتسع لصفحة واحدة، أو كبّر حجم الصفحة أو قلّل هوامشها حتى يستوعب الارتفاع القابل للاستعمال المحتوى.

BudgetExceededException

• متى يُطلَق. تُطلقه عناصر التخطيط الأولية في الوضع المُحتفَظ به عند خرق إحدى مراتب ميزانية الموارد الأربع المُعرَّفة في سجل قرار البنية ⁨ADR-020⁩ واختيار المُستدعي للإخفاق الصارم بدلًا من الاحتياط اللطيف. لا يُطلق المسار الافتراضي شيئًا: يُرجع ContainerLayout::acceptChild() القيمة false، فيسقط المُستدعي احتياطيًا إلى تخطيط الكتلة، ويُصدَر تحذير. ويُحجَز الاستثناء للتحقق وقت الإعداد وللاختبارات التي تؤكد رباعية الخرق بالضبط. والمراتب هي per-child (دفق ابن مُلتقَط يتجاوز سقفه)، وper-container (ميزانية عدّ العُقد للمرتبة 1)، وper-document (ميزانية تمريرة التخطيط أو عمق التداخل)، وglobal (سقف الذروة لحجم المجموعة المقيمة على مستوى ⁨SDK⁩ البالغ 256 ميجابايت).
• البيانات المحمولة. يتجاوز getContext()، الذي يُرجع شكلًا ثابتًا من ثمانية مفاتيح تستهلكه أدوات مراقبة أداء التطبيق (⁨APM⁩): budgetTier، وexceededValue، وbudgetLimit، وcontainerType، وphase، وbreachOrigin، وcaptureSize، وprocessedItemCount. والمفاتيح الأربعة الأولى هي مجموعة الإصدار ⁨v1.0.0⁩ الأصلية وتُملأ دائمًا؛ أما الأربعة الأخيرة فقيمتها الافتراضية null أو 0 حين يُستدعى المُنشئ من دونها. ويربط getCausalWarningCode() رباعية (المرتبة، نوع الحاوية) بـWarningCode الذي كان مسار الاحتياط اللطيف سيُصدره.
• التعافي. لخرق إعداد، اخفض القيمة المطلوبة لتعود إلى الحدّ المُوثَّق (على سبيل المثال، تقبل ميزانية العُقد المُحتفَظ بها من 5,000 إلى 100,000 عبر Config::withRetainedNodeBudget()). ولخرق محتوى، قلّل تداخل الحاويات أو عدد العُقد، أو اعتمد على الاحتياط اللطيف الافتراضي إلى تخطيط الكتلة بدلًا من اختيار سطح الإخفاق الصارم.

UnsupportedNamedPageException

• متى يُطلَق. تُطلقه مرحلة الوسائط المقسّمة على صفحات، بإخفاق آمن، عندما يُصرّح مستند بقاعدة صفحة مسماة @page <ident> { … } (مربوطة بالمحتوى عبر الخاصية page: <ident>). تُحلَّل الصفحات المسماة من ⁨CSS Paged Media Level 3 §3.4⁩ و⁨Level 4 §3.2⁩ — بما في ذلك الأصناف الزائفة :first و:left و:right و:blank وتجاوزات size: وrotate: المسماة — لكن لا يستهلكها أي مسار تخطيط إنتاجي. يرفض المحرك بدلًا من أن يُصدر الترقيم الافتراضي للصفحات الخاطئ بصمت الذي كان تجاهل القاعدة سيُنتجه.
• البيانات المحمولة. يتجاوز getContext()، الذي يُرجع page_names (قائمة بالمُعرِّفات المتمايزة التي أطلقت الإخفاق، بترتيب المصدر)، وhas_size_override (bool)، وhas_rotate_override (bool)، وhas_pseudo_classes (bool). وتُكشَف القيم نفسها على الخصائص العامة pageNames وhasSizeOverride وhasRotateOverride وhasPseudoClasses.
• التعافي. أزِل قواعد @page <ident> المسماة وأي روابط page: <ident>، وعبّر عن الهندسة المقصودة عبر قاعدة @page { … } غير المسماة المدعومة وأشكال أصنافها الزائفة. أو بدلًا من ذلك، ثبّت على إصدار مستقبلي يُنزِل دعم تخطيط الصفحات المسماة كاملًا.

الطباعة وتشكيل النص

IcuRequirementException

• متى يُطلَق. تُطلقه تجزئة النص عندما يحتاج إلى مُكرِّر كسر الأسطر لمكوّنات اليونيكود الدولية (⁨ICU⁩) بينما تكون سياسة اشتراط ⁨ICU⁩ نشطة (NEXTPDF_REQUIRE_ICU=1) ولا يتوفّر امتداد ext-intl وIntlBreakIterator.
• البيانات المحمولة. يمدّد RuntimeException مباشرةً، لذا فهو ليس مُدركًا للسياق وليس له getContext(). وهو تنقيح صارم للاستثناء العام الذي كان مسار الشفرة نفسه يُطلقه سابقًا، لذا تبقى مُعالِجات catch (\RuntimeException) القائمة تعمل.
• التعافي. ثبّت ext-intl وفعّله حتى يتوفّر مُكرِّر كسر ⁨ICU⁩، أو ألغِ ضبط NEXTPDF_REQUIRE_ICU للسقوط احتياطيًا إلى المُجزِّئ غير المعتمد على ⁨ICU⁩ حيث لا تكون سياسة اشتراط ⁨ICU⁩ إلزامية.

ScriptShaperException

• متى يُطلَق. هذا هو الاستثناء الأساسي لواجهة مزوّد خدمة تشكيل النصوص (⁨SPI⁩). وهو لا يُطلَق مباشرةً اليوم؛ بل تُطلَق أنواع فرعية فعلية بدلًا منه. اعترض هذا النوع لمعالجة أي إخفاق تشكيل في مكان واحد.
• البيانات المحمولة. يمدّد RuntimeException مباشرةً؛ ليس مُدركًا للسياق، ولا له getContext().
• التعافي. تفرّع بحسب النوع الفرعي الفعلي. انظر NotYetImplementedException أدناه لأجل النوع الفرعي الوحيد المشحون في الإصدار الحالي.

NotYetImplementedException

• متى يُطلَق. يُطلق كل مُشكِّل نصوص نائب هذا من جسم shape() الخاص به للنصوص التي يُؤجَّل تشكيلها الفعلي (المنغولية والتبتية). وحدّ واجهة ⁨SPI⁩ للتشكيل جاهز بنيويًا، لكن التشكيل الفعلي مُعلَّق بانتظار تثبيت يتحقّق منه ناطق أصلي. وإطلاق استثناء بدلًا من عدم تنفيذ صامت يُظهِر الربط الإنتاجي العَرَضي في وقت التشغيل بدلًا من إصدار نص غير مُشكَّل في ملف ⁨PDF⁩ يدّعي إمكانية وصول مُوسَّمة.
• البيانات المحمولة. يمدّد ScriptShaperException (ومن ثمّ RuntimeException)، لذا فهو ليس مُدركًا للسياق وليس له getContext(). والبيانات التشخيصية على خصائصه public readonly: bcp47LanguageTag (وسم ⁨BCP-47⁩ للمقطع، مثل mn-Mong أو bo-Tibt) وmissingCapability (القدرة الفعلية التي يفتقدها التنفيذ). وتتضمن الرسالة كليهما.
• التعافي. لا توجّه المقاطع في النصوص غير المُنفَّذة عبر المُشكِّل في الإنتاج. اكتشف وسم اللغة في المنبع واسقط احتياطيًا إلى مسار عرض مختلف أو ثبّت على إصدار مستقبلي يُنزِل التشكيل للنص المتأثر.

ملفات تعريف خرج الكاتب والتشفير

Pdf14FeatureRejectedException

• متى يُطلَق. يُطلقه الكاتب عندما يحتوي مستند ميزةً ممنوعة ضمن ملف تعريف الخرج ⁨PDF 1.4⁩ (⁨ISO 19005-1:2005⁩ / ⁨PDF/A-1⁩)، الذي يمنع البِنى المُدخَلة في إصدارات ⁨PDF⁩ اللاحقة.
• البيانات المحمولة. يمدّد NextPdfException لكنه لا يتجاوز getContext()، لذا يُرجع getContext() مصفوفة فارغة. والبيانات التشخيصية على خصائصه public readonly: feature (اسم الميزة المرفوضة)، وreason (سبب منعها)، وisoClause (مرجع بند ⁨ISO⁩). وتجمع الرسالة الثلاثة كلها.
• التعافي. أزِل الميزة المرفوضة أو استبدلها بمكافئ متوافق مع ⁨PDF 1.4⁩، أو استهدف ملف تعريف خرج أعلى يسمح بالميزة.

Pdf20FeatureRejectedException

• متى يُطلَق. يُطلقه الكاتب عندما يحتوي مستند ميزةً ممنوعة ضمن ملف تعريف الخرج ⁨PDF 2.0⁩ الصارم. يُهمل ⁨ISO 32000-2:2020⁩ بِنى كان ⁨PDF 1.7⁩ لا يزال يسمح بها — أبرزها خطوط ⁨Standard 14 Type 1⁩ (§⁨9.6.2⁩)، التي يجب تضمينها في مستند ⁨PDF 2.0⁩ مطابق.
• البيانات المحمولة. الشكل نفسه لـPdf14FeatureRejectedException: يمدّد NextPdfException، ولا يتجاوز getContext() (يُرجع مصفوفة فارغة)، ويكشف feature وreason وisoClause بوصفها خصائص public readonly.
• التعافي. عالِج الميزة المرفوضة — على سبيل المثال، ضمّن الخطوط الأساسية الـ14 — أو خذ بمخرج الهروب المُوثَّق حيث وُجِد (للخطوط الأساسية الـ14 غير المُضمَّنة، Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• متى يُطلَق. يُطلقه PdfWriter::build() عند نقطة الدخول عندما يكون encryptionMode للمستند هو pubkey (قائمة مستلِمين بالمفتاح العام) قبل ربط إرسال تشفير جسم الدفق بالمفتاح العام على جانب الكاتب. ويمنع الرفض المُسبَق إصدار ⁨PDF⁩ غير مُشفَّر بصمت ظنّ المُستدعي أنه مُشفَّر.
• البيانات المحمولة. يمدّد RuntimeException مباشرةً، لذا فهو ليس مُدركًا للسياق وليس له getContext(). وهو تنقيح صارم للاستثناء العام الذي كان الموضع نفسه يُطلقه سابقًا، لذا تبقى مُعالِجات catch (\RuntimeException) القائمة تعمل.
• التعافي. استخدم وضع تشفير مدعومًا (التشفير المعتمد على كلمة مرور) بدلًا من قائمة المستلِمين بالمفتاح العام، أو ثبّت على إصدار يُنزِل دعم التشفير بالمفتاح العام. لا تعامل الخرج بوصفه مُشفَّرًا عند إطلاق هذا.

إدخال القارئ والبيانات الوصفية

UnsupportedPdfStructureException

• متى يُطلَق. يُطلقه قارئ مخطط الكائنات، بإخفاق آمن، عندما يقع ملف ⁨PDF⁩ مُدخَل خارج حدّه المدعوم. يدعم القارئ جداول المراجع المتقاطعة الكلاسيكية (⁨ISO 32000-2:2020 §7.5.4⁩)، ودفوق المراجع المتقاطعة (§⁨7.5.8⁩)، والكائنات المضغوطة في دفق الكائنات (§⁨7.5.7⁩)، وسلاسل /Prev متعددة المراجعات (§⁨7.5.6⁩)، والملفات هجينة المرجع عبر /XRefStm (§7.5.8.4). وأي شيء خارج هذا الحدّ يُظهِر هذا الاستثناء بدلًا من تحليل جزئي أو مُخمَّن. وتربط المُنشئات المسماة حالات السبب: encrypted()، وdamagedCrossReference()، وcyclicReferenceChain()، وnonConformantObjectStream()، وirresolvableObjectCollision()، وtruncatedFile()، وcrossReferenceOffsetOutOfBounds().
• البيانات المحمولة. يمدّد RuntimeException مباشرةً، لذا فهو ليس مُدركًا للسياق وليس له getContext(). ويكشف خاصية public readonly اسمها reason من النوع UnsupportedPdfStructureReason (تعداد) حتى يتفرّع المُستدعون بحسب الفئة الدقيقة من دون تحليل الرسالة؛ وقد يُضيف نصّ detail اختياري وقابل للإطلاق previous سياقًا محدودًا غير حساس. والرسالة الافتراضية هي الملخّص غير المُسرِّب للسبب.
• التعافي. تفرّع بحسب reason. بالنسبة إلى EncryptedDocument، شغّل خطوة فكّ تشفير قبل القراءة، لأن فكّ التشفير خارج نطاق القارئ. وبالنسبة إلى DamagedCrossReference أو TruncatedFile أو CrossReferenceOffsetOutOfBounds، عامِل الملف بوصفه مُشوَّهًا أو ناقصًا وأعد الحصول على المصدر أو إصلاحه. وبالنسبة إلى CyclicReferenceChain أو NonConformantObjectStream أو IrresolvableObjectCollision، فالمُدخَل ينتهك النموذج البنيوي ولا يمكن قراءته كما هو.

PacketTooLargeException

• متى يُطلَق. يُطلقه قارئ بيانات ⁨XMP⁩ الوصفية التدفّقي عندما تتجاوز حزمة ⁨XMP⁩ مُضمَّنة سقف البايت المُهيّأ. وهو حارس دفاعي ضدّ المُدخَلات بنمط توسّع الكيانات والانفجار التربيعي (سقف ذروة 128 ميجابايت مقابل ⁨XMP⁩ مُضمَّن بحجم جيجابايت).
• البيانات المحمولة. يمدّد NextPdfException لكنه لا يتجاوز getContext()، لذا يُرجع getContext() مصفوفة فارغة. والبيانات التشخيصية على خصائصه public readonly: byteCount (عدد البايتات المُلاحَظ) وcap (السقف المُهيّأ بالبايتات). وتُبلّغ الرسالة عنهما معًا.
• التعافي. ارفض البيانات الوصفية مُفرِطة الحجم أو تخطّاها بوصفها خبيثة أو مُشوَّهة. وإن كان مستند مشروع يحتاج فعلًا إلى حزمة أكبر، فارفع السقف المُهيّأ عن قصد، موازنًا خطر استنزاف الذاكرة الذي وُجِد الحارس لمنعه.

انظر أيضًا

• فهرس مرجع الأخطاء
• استكشاف أخطاء الخطوط والوسم وإصلاحها — لأعراض NotYetImplementedException وScriptShaperException وIcuRequirementException.
• استكشاف أخطاء التحقق من ⁨PDF⁩/A و ⁨PDF⁩/UA وإصلاحها — لأعراض Pdf14FeatureRejectedException وPdf20FeatureRejectedException.
• استكشاف أخطاء التشفير والأذونات وإصلاحها — لأجل PublicKeyEncryptionUnsupportedException وسبب القارئ EncryptedDocument.