Pro الإصدار

المحوّل — مرجع متعمّق

لمحة سريعة

يُصدِّر NextPDF\Pro\Converter ملفّ ⁨PDF⁩ موجودًا إلى ⁨HTML⁩ ذي تموضع، أو ⁨SVG⁩ مبسّط، أو نص عادي، ويقطّع محتوى المستند إلى مناطق بنيوية مُصنّفة. يُعدّد هذا المرجع المعمّق سطح واجهة ⁨API⁩ العامة، ومصفوفة تغطية العوامل، وعقد السلوك، وأنماط الفشل. إنه مُصدِّر لاستخراج المحتوى، لا مُصيّرًا بدقّة البكسل.

التوفّر والترخيص

تُشحَن هذه القدرة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل بمظروف ترخيص من فئة ⁨Pro⁩. والنشر بلا ذلك الاستحقاق لا يُحمّل فئات القدرة. قارن الإصدارات واحصل على ترخيص.

لا توجد راية قدرة زمن-تشغيل تحجب هذه الوحدة. تُحلّ فئات المحوّل كلما كانت حزمة ⁨Pro⁩ مثبَّتة ومرخَّصة.

سطح واجهة ⁨API⁩ العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	يُصدِّر كل صفحة حاملة للنص إلى مستند ⁨HTML5⁩ واحد مكتفٍ ذاتيًّا	`ConversionResult` (الهدف `Html5`)	`InvalidArgumentException` عندما يكون `$pdfData` فارغًا	تتخذ التهيئة الفارغة القيمة الافتراضية `ConversionTarget::Html5`
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	يُصدِّر صفحة واحدة إلى مستند ⁨SVG⁩ مستقل	`ConversionResult` (الهدف `Svg`؛ ‏`pageCount` دائمًا 1)	`InvalidArgumentException` عندما يكون `$pdfData` فارغًا	يُنتج `$pageIndex` خارج النطاق ملفَّ ⁨SVG⁩ يحوي الخلفية فقط
`PdfToTextConverter::convert()`	`string $pdfData`	يستخرج النص المفكوك من كل الصفحات، مفصولًا بعلامة فاصل صفحات	`ConversionResult` (الهدف `PlainText`)	`InvalidArgumentException` عندما يكون `$pdfData` فارغًا	هذا الهدف وحده يفكّ ترميز هروب السلاسل الحرفية
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	يستخرج النص المفكوك لصفحة واحدة بترقيم يبدأ من الصفر	`string`	لا يرمي؛ يُعيد `''` لصفحة مفقودة أو إدخال فارغ	بخلاف `convert()`، لا حارس لإدخال فارغ
`DocumentSegmentationEngine::segment()`	`string $pdfData`	يصنّف محتوى الصفحة إلى مقاطع بنيوية مُصنّفة باستخدام استدلالات مكانية وخطّية	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException` عندما يكون الإدخال فارغًا أو يتعذّر تحليل بنية الـ ⁨PDF⁩	قائم على القواعد؛ لا يُجري أي استدلال ⁨AI⁩
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	إعدادات تحويل غير قابلة للتغيير	`ConversionConfig`	—	`embedFonts` و`embedImages` مقبولان لكن غير مُستهلكَين في 3.1.0
`ConversionResult::size()`	—	طول المخرجات المُنتَجة بالبايت	`int`	—	حقول readonly عامة: `output`، `target`، `pageCount`، `processingTimeMs`
`ConversionResult::isValid()`	—	يُبلّغ عمّا إذا كانت المخرجات غير فارغة	`bool`	—	أغلفة مستندات ⁨HTML⁩ و⁨SVG⁩ ليست فارغة أبدًا؛ تحقّق من `pageCount` بدلًا من ذلك
`ConversionTarget`	حالات مدعومة بسلسلة `Html5`، `Svg`، `PlainText`	يختار هدف التصدير	`mimeType(): string`، `fileExtension(): string`	—	`fileExtension()` يقابل `html`، `svg`، `txt`

توقيعات نقاط الدخول:

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

عقد السلوك

المدخلات بايتات ⁨PDF⁩ خام؛ والمخرجات كائن قيمة ConversionResult. تشترك محوّلات التصدير الثلاثة في نموذج مسح: تحديد حدود stream/endstream، وعزل كتل النص BT/ET، وتحليل عوامل إظهار النص. ولا تحلّل جدول الإحالات المتبادلة ولا تفكّ ضغط التدفّقات المضغوطة. أما DocumentSegmentationEngine فيختلف: فهو يحلّ المُذيَّل والفهرس وشجرة الصفحات، ويفكّ ضغط محتوى صفحات ⁨FlateDecode⁩ قبل التصنيف.

تغطية العوامل:

عامل ⁨PDF⁩	HTML	SVG	نص
`Tj` (إظهار سلسلة)	نعم	نعم	نعم
`TJ` (إظهار مصفوفة)	نعم	نعم	نعم
`'` (نقل + إظهار)	لا	لا	نعم
`Td` / `Tm` (تموضع)	نعم	نعم	غير منطبق
`Tf` (حجم الخط)	نعم	نعم	غير منطبق
`re` (مستطيل)	لا	نعم	لا
`m` / `l` (خط)	لا	نعم	لا
`RG` (حدّ ⁨RGB⁩)	لا	نعم (يُطبَّق على حدّ المستطيل/الخط)	لا
المنحنيات، التظليل، القصّ، الصور	لا	لا	لا

التموضع. تحلّ كل كتلة BT/ET موضعًا واحدًا من أول تطابق Td أو Tm فيها؛ ويُقدَّم Tm عند ظهورهما معًا. ويُقلَب محور ⁨Y⁩ من فضاء مستخدم ⁨PDF⁩ إلى فضاء المخرجات في الأعلى-اليسار. ويتخذ حجم الخط القيمة الافتراضية ⁨12 pt⁩ عند غياب Tf.
هندسة الصفحة. يفترض ⁨HTML⁩ و⁨SVG⁩ صندوق صفحة ⁨A4⁩ (⁨595 x 842 pt⁩) مضروبًا في scaleFactor. ويحمل جذر ⁨SVG⁩ سمات viewBox والعرض والارتفاع المتطابقة فوق مستطيل خلفية أبيض.
لون الحدّ. تُحلّ عوامل RG وفق الموضع، لذا فإن تدفّقًا يغيّر لون الحدّ أكثر من مرة يلوّن كل مستطيل وخط بأحدث عامل سابق له. وتُقصَر المكوّنات على النطاق ⁨0..1⁩ قبل التحويل إلى النظام الستّ عشري. وتعبئة المستطيل سوداء دائمًا؛ ولا يُقيَّم عامل التعبئة rg.
فكّ ترميز السلاسل. يفكّ الهدف النصّي هروب السلاسل الحرفية وفق ⁨ISO 32000-2:2020 §7.3.4.2⁩: الهروب المُسمّى، وأكواد \ddd الثمانية المُقنَّعة إلى بايت واحد، واستمرار الأسطر بالشرطة المائلة العكسية، وإزالة الشرطة المائلة العكسية المنفردة. أما هدفا ⁨HTML⁩ و⁨SVG⁩ فيُصدِران البايتات الخام بين القوسين بعد هروب ⁨HTML⁩ أو ⁨XML⁩؛ ولا يفكّان الهروب.
تجميع المخرجات. يصل الهدف النصّي نصوص الكتل بمسافة، ويصل الصفحات بـ --- Page Break --- مؤطَّرة بأسطر فارغة. ويُصدِر هدف ⁨HTML⁩ عنصر <div> واحدًا بتموضع مطلق لكل كتلة نص داخل حاوية لكل صفحة تحمل فئة الـ ⁨CSS⁩ المُهيّأة وسمة data-page.
الحتمية. لإدخال وتهيئة متطابقين، تكون بايتات ⁨HTML⁩ أو ⁨SVG⁩ أو النص المُنتَجة مستقرّة. وprocessingTimeMs قياس زمن حائطي ومُستبعَد من السطح الحتمي.

الحالات الحدّية وأنماط الفشل

الإدخال الفارغ: تُطلق كل نقطة دخول convert() وsegment() استثناء InvalidArgumentException (“⁨PDF⁩ data must not be empty”). ولا تُنتَج مخرجات جزئية. وextractPage() هي الاستثناء: فهي تُعيد '' دون رمي.
تتخطّى محوّلات ⁨HTML⁩ والنص التدفّقات الخالية من BT/ET. وملفّ ⁨PDF⁩ لا يحوي إلا مثل هذه التدفّقات يُنتج pageCount صفريًّا مع مخرجات نص فارغة أو غلاف ⁨HTML⁩ خالٍ من الصفحات.
يتحقّق isValid() فقط من كون المخرجات غير فارغة. ويُصدِر محوّلا ⁨HTML⁩ و⁨SVG⁩ غلاف مستند دائمًا، لذا يبقى isValid() بقيمة true حتى عند عدم العثور على نص؛ فاستخدم pageCount (لـ ⁨HTML⁩ والنص) لاكتشاف الاستخراج الفارغ.
لا تفكّ محوّلات التصدير الثلاثة ضغط محتوى ⁨FlateDecode⁩. وملفّات ⁨PDF⁩ المضغوطة فقط تُصدّر عبرها محتوى قليلًا أو معدومًا. أما segment() فيفكّ ضغط تدفّقات صفحات ⁨FlateDecode⁩.
يحدّ segment() فكّ الضغط بحجم كل تدفّق ونسبة الضغط وميزانية تراكمية. والتدفّق الذي يتجاوز سقفًا يتدهور إلى محتوى صفحة فارغ بدلًا من استنفاد الذاكرة؛ ولا يرمي.
يُطلق segment() استثناء InvalidArgumentException عندما يتعذّر حلّ المُذيَّل، أو إزاحة الإحالات المتبادلة، أو فهرس المستند، أو شجرة الصفحات.
يختلف ترقيم الصفحات باختلاف المحوّل. يعدّ محوّلا ⁨HTML⁩ والنص التدفّقات الحاملة للنص فقط؛ بينما يعدّ محوّل ⁨SVG⁩ التدفّقات المحتوية على أي عامل رسوميات أو نص معروف. لذا قد يشير $pageIndex نفسه إلى تدفّقات مختلفة.
تُهمَل تعديلات التقنين العددية لـ TJ؛ وتُوصَل سلاسل المصفوفة دون تباعد بين المحارف.
لا يُطبَّق تخطيط المحرف إلى ⁨Unicode⁩. والنص المكتوب بخطوط ذات ترميزات مخصّصة يُصدَّر كتسلسل بايتات خام.
يُقارَب النص المُدوَّر والتحويلات غير النصّية وتدفّق الأعمدة بتموضع أول تطابق، وقد لا يعيد إنتاج التخطيط الأصلي.
لا تجري أي عملية تعمية في هذه الوحدة، لذا ليس لوضع ⁨FIPS⁩ سلوك خاص بالوحدة.

المطابقة

يوثّق ⁨NextPDF⁩ القدرة مقابل البنود المُستشهَد بها. تصف بيانات الدعم السلوك المُنفَّذ؛ وهي ليست نتائج اختبار مطابقة ولا شهادات، ولا يحمل ⁨NextPDF⁩ أي شهادة.

الادّعاء	بند المواصفة	الحالة
تحليل عامل إظهار النص `Tj`	ISO 32000-2:2020 §9.4	مُتحقَّق منه (مجموعة اختبارات الوحدة)
تحليل عامل إظهار النص المصفوفي `TJ`	ISO 32000-2:2020 §9.4	مُتحقَّق منه (مجموعة اختبارات الوحدة)
تحليل عامل النقل-والإظهار `'` (الهدف النصّي فقط)	ISO 32000-2:2020 §9.4	مُتحقَّق منه (مجموعة اختبارات الوحدة)
فكّ ترميز هروب السلاسل الحرفية (الهدف النصّي فقط)	ISO 32000-2:2020 §7.3.4.2	مُنفَّذ؛ تُعاد البايتات كما هي، وتفسير مجموعة المحارف يتم لاحقًا
التعرّف على إنشاء المسار `re`، `m`، `l` (هدف ⁨SVG⁩)	ISO 32000-2:2020 §8.5.2	جزئي: مجموعة فرعية دون منحنيات أو إغلاق أو تقييم وضع الرسم
آلة حالة النص الكاملة وعرض الصفحة	—	غير مدعوم (خارج النطاق)

يحلّل المحوّل عوامل إظهار النص لاسترجاع المحتوى؛ ولا يُنفّذ آلة حالة النص الكاملة، لذا يكون تموضع المحارف تقريبيًّا لا مطابقًا للمواصفة تمامًا.

ملاحظات التطوير

التحليل خطّي بطول بايتات ⁨PDF⁩. وتتتبّع الذاكرة الإدخال إضافةً إلى سلسلة المخرجات المُنتَجة. والبيانات الأمامية performance_budget هي المرجع لكل استدعاء لمستند مكتبي نموذجي.
تحلّل المحوّلات بايتات ⁨PDF⁩ غير الموثوقة بمسح محدود strpos/substr. ولا تنفّذ أي ⁨JavaScript⁩ مُضمَّن ولا تتبع أي إحالات خارجية. عامِل ⁨HTML⁩ المُصدَّر بوصفه محتوى غير موثوق واهرب أحرفه لوجهته.
تُهرَّب مخرجات ⁨HTML⁩ بـ htmlspecialchars (⁨ENT_QUOTES, HTML5⁩)؛ ويُهرَّب نص ⁨SVG⁩ بترميز ⁨XML⁩. ويُهرَّب cssClass المُهيّأ قبل الإصدار.
استهلاك التهيئة: يُطبَّق scaleFactor على هدفي ⁨HTML⁩ و⁨SVG⁩؛ ويُطبَّق cssClass على ⁨HTML⁩ فقط؛ وembedFonts وembedImages محجوزان وغير مستخدمَين حاليًّا؛ ولا يتجاوز حقل target تنسيق مخرجات المحوّل نفسه.
تُشحَن محوّلات التصدير منذ ⁨1.9.0⁩؛ ويُشحَن DocumentSegmentationEngine منذ ⁨2.1.0⁩ ويدعم أداة segment_document الخاصة بـ ⁨Pro MCP⁩ وعقد التقطيع في ⁨Interop⁩.
‏PdfPageExtractor وPdfPageData في المساحة نفسها داخليان لمحرّك التقطيع وليسا واجهة ⁨API⁩ عامة.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًّا وسطح واجهة ⁨API⁩ العامة المدعوم فقط. أما مسارات المساحات الداخلية، والفئات المساعدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر فهي خارج النطاق.