Pro الإصدار

‏⁨Document⁩ — مرجع متعمّق

لمحة سريعة

توفّر وحدة ⁨Document⁩ ثلاث بدائيات تجميع في ⁨Pro⁩: تقسيم نطاقات الصفحات، ودمج مستندات متعددة، وبناء قاموس ⁨PDF Portfolio⁩ (‏⁨Collection⁩). يستخرج PdfSplitter نطاقات الصفحات إلى ملفات ⁨PDF⁩ قائمة بذاتها ومطابِقة بنيويًا، ويدمج مستندات كاملة في ملف واحد مُعاد الترقيم. ويبني PdfPortfolio قاموس ⁨Collection⁩ الذي يعرض الملفات المُضمَّنة بأعمدة مُخطَّط قابلة للفرز. ويحدّ كل نقطة دخول من حجم المدخل وأعداد الكائنات في مواجهة المدخل العدائي.

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

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

سطح واجهة برمجة التطبيقات العامة

تعيش كل أنواع الوحدة في فضاء الأسماء NextPDF\Pro\Document. وPageRange وMergeResult كائنا قيمة في ⁨Core⁩ من NextPDF\Document.

الرمز	المعاملات	السلوك الافتراضي	المُرجَع	يرمي أو يفشل بـ	ملاحظات
`PdfSplitter::split()`	`string $pdfData`، `list<PageRange> $ranges`، `int $maxBytes = 100_000_000`، `int $maxRanges = 1000`	يبني مقطع ⁨PDF⁩ قائمًا بذاته واحدًا لكل نطاق	`SplitResult`	`InvalidArgumentException` عند غياب ترويسة `%PDF`؛ `OverflowException` عند حارس الحجم أو عدد النطاقات أو الإغلاق	تعمل الحرّاس قبل أي تحليل
`PdfSplitter::splitEvery()`	`string $pdfData`، `int $pagesPerSegment`	يشتقّ نطاقات متجاورة من ⁨N⁩ صفحة؛ وقد يكون المقطع الأخير أقصر	`SplitResult`	`InvalidArgumentException` عندما `$pagesPerSegment < 1` أو عند غياب الترويسة	يفوّض إلى `split()` بالسقوف الافتراضية
`PdfSplitter::extractPages()`	`string $pdfData`، `PageRange $range`	يُرجِع نطاقًا واحدًا بايتات ⁨PDF⁩ قائمة بذاتها	`string`	`InvalidArgumentException` عند غياب الترويسة؛ `OverflowException` عند حارس الإغلاق	لا معاملات سقف على هذا المسار
`PdfSplitter::mergeDocuments()`	`list<string> $pdfs`، `int $maxInputs = 100`، `int $maxBytesEach = 100_000_000`	يدمج المدخلات بالترتيب في ⁨PDF⁩ واحد مُعاد الترقيم	`MergeResult`	`InvalidArgumentException` عند قائمة فارغة أو مدخل غير ⁨PDF⁩؛ `OverflowException` عند العدد أو حجم كل مدخل أو حارس الإغلاق	منذ 3.1.0؛ أعلى إصدار مدخل يحدّد ترويسة المخرَج
`SplitResult`	‏⁨readonly⁩ `$segments`، `$ranges`، `$totalPages`	يحمل بايتات المقاطع الخام مع بيانات وصفية للمصدر	—	—	كائن قيمة `final readonly`
`SplitResult::count()`	—	يعدّ المقاطع المُنتَجة	`int`	—	—
`SplitResult::segment()`	`int $index`	يُرجِع بايتات مقطع واحد	`string`	`OutOfRangeException` عند فهرس خارج الحدود	فهرس يبدأ من صفر
`PdfPortfolio::__construct()`	`string $viewMode = 'tile'`	يتحقّق من وضع العرض عند الإنشاء	—	`InvalidArgumentException` عند وضع غير `tile` أو `detail` أو `hidden`	—
`PdfPortfolio::addSchema()`	`PortfolioField $field`	يُلحِق عمود مُخطَّط	`self`	—	سلِس
`PdfPortfolio::addEntry()`	`PortfolioEntry $entry`	يُلحِق مُدخَلة ملف	`self`	—	سلِس
`PdfPortfolio::getSchema()`	—	يُرجِع حقول المُخطَّط المتراكمة	`list<PortfolioField>`	—	—
`PdfPortfolio::getEntries()`	—	يُرجِع مُدخَلات الملفات المتراكمة	`list<PortfolioEntry>`	—	—
`PdfPortfolio::count()`	—	يعدّ مُدخَلات الملفات	`int`	—	—
`PdfPortfolio::generateCollectionDictionary()`	—	يُصدِر سلسلة قاموس ⁨Collection⁩	`string`	—	لا تظهر كتلتا المُخطَّط والفرز إلا عند وجود حقول
`PortfolioEntry`	`$filename`، `$data`، `$description = ''`، `$mimeType = 'application/octet-stream'`، `$customFields = []`	كائن قيمة غير قابل للتغيير لمُدخَلة ملف	—	—	`size()` يُرجِع طول البيانات بالبايت
`PortfolioField`	`$name`، `PortfolioFieldType $type`، `$displayName = ''`، `$order = 0`، `$visible = true`	كائن قيمة غير قابل للتغيير لعمود مُخطَّط	—	—	`effectiveDisplayName()` يرجع إلى `$name` احتياطيًا
`PortfolioFieldType`	تعداد نصي: `Text`، `Date`، `Number`، `FileName`، `Description`، `Size`، `ModDate`، `CreationDate`	يربط كل حالة بـ`/Subtype` في ⁨PDF⁩ عبر `pdfSubtype()`	`string` (`S`، `D`، `N`، `F`، `Desc`)	—	الحالات الشبيهة بالتاريخ تتشارك النوع الفرعي `D`؛ والحالات العددية تتشارك `N`

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

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

عقد السلوك

يتشارك التقسيم والدمج خط أنابيب رسم كائنات واحدًا:

يجب أن يبدأ المدخل بترويسة %PDF. وتعمل حرّاس الحجم والعدد قبل التحليل وترفع OverflowException عند الاختراق.
تُكتشَف الصفحات الورقية بفحص علامات كائنات الصفحات؛ وتُستبعَد عُقَد شجرة الصفحات من العدّ.
يفهرس المحلّل كل كائن غير مباشر غير مضغوط بفحص منتهٍ واعٍ بالتدفّق. وتفوز أول ظهور لمُعرِّف الكائن، فلا تُطبَّق تجاوزات التحديث التزايدي.
تُجسَّد سمات شجرة الصفحات القابلة للوراثة (/Resources، /MediaBox، /CropBox، /Rotate) على كل صفحة مُستخرَجة بالسير عبر سلسلة /Parent الخاصة بها، فتكون المقاطع قائمة بذاتها.
يُجمَع الإغلاق التعدّي للمراجع غير المباشرة لكل صفحة، باستثناء الحافة الخلفية /Parent، ويُعاد ترقيمه في فضاء مُعرِّفات متجاور جديد.
يُصدِر المُسلسِل الترويسة، و⁨Catalog⁩، وشجرة ⁨Pages⁩، وكائنات الصفحات، وكائنات الإغلاق، ثم جدول مرجع متقاطع بإزاحات دقيقة بالبايت وstartxref يشير إلى الكلمة المفتاحية xref.
يكرّر mergeDocuments خط الأنابيب لكل مدخل في فضاء مُعرِّفات مشترك واحد. وأعلى إصدار ⁨PDF⁩ في المدخلات يحدّد ترويسة المخرَج. وهو البديل المطابِق للدامج المُعطَّل في ⁨Core⁩، الذي يبقى مغلقًا عند الفشل.
المخرَج حتمي. ولا تُصدَر أي طوابع زمنية أو مُعرِّفات عشوائية، فالمدخل المتطابق يُنتِج بايتات متطابقة.

تجميع ⁨Portfolio⁩:

يتحقّق المُنشئ من وضع العرض. ورمز /View المُصدَر هو /T أو /D أو /H لـ⁨tile⁩ و⁨detail⁩ و⁨hidden⁩ على التوالي.
يُصدِر generateCollectionDictionary() قيمة /Type /Collection، ورمز /View، وكتلة /Schema عند وجود حقول، وتوجيه /Sort على أول حقل مُخطَّط تصاعديًا.
يُصدِر كل حقل مُخطَّط /Subtype (من pdfSubtype())، و/N (اسم عرض مُهرَّب)، و/O (الترتيب)، و/V (الظهور).
تُنقَّى أسماء الحقول إلى رموز أسماء ⁨PDF⁩ صالحة؛ وتتحوّل الأحرف غير الكلمية إلى شُرَط سفلية. وتُهرَّب القيم النصية بوصفها سلاسل حرفية في ⁨PDF⁩.
تُكشَف مُدخَلات الملفات عبر getEntries() كي تُضمِّنها طبقة الكتابة. وقاموس ⁨Collection⁩ نفسه لا يحمل سوى العرض والمُخطَّط والفرز.

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

النطاق الذي لا يطابق أي صفحة يُنتِج مقطعًا أدنى من صفحة واحدة (‏⁨MediaBox⁩ بقياس 612 x 792)، لا خطأ.
المستند الذي لا توجد فيه علامات صفحات قابلة للاكتشاف يُعَدّ صفحة واحدة.
الصفحات المُخزَّنة داخل تدفّقات الكائنات لا تُكتشَف؛ ولا يشارك في الاستخراج سوى الكائنات غير المباشرة غير المضغوطة.
عند وجود مُعرِّفات كائنات مكرّرة، تُستخدَم المراجعة ذات الإزاحة الأدنى؛ وتُتجاهَل مراجعات التحديث التزايدي اللاحقة.
يُحَدّ إغلاق المراجع لكل مقطع بسقف 50,000 كائن؛ والرسم البياني ذاتي المرجعية أو المتفرّع بخبث يرفع OverflowException.
السقوف الافتراضية: 100 ميغابايت للمدخل، و1,000 نطاق، و100 مدخل دمج. وكلها قابلة للضبط من المُستدعِي لكل استدعاء.
يرفض splitEvery() حجم مقطع أقل من 1 بـInvalidArgumentException.
يرفض SplitResult::segment() فهرسًا خارج الحدود بـOutOfRangeException.
اسما حقلي مُخطَّط لا يختلفان إلا في علامات الترقيم يُنقَّيان إلى المفتاح نفسه في القاموس؛ والحقل اللاحق يحجب السابق بصمت في المُخطَّط المُصدَر.
لا تُجري هذه الوحدة أي عمليات تشفير؛ ووضع ⁨FIPS⁩ لا يغيّر سلوكها.

المطابقة

يتبع مخرَج المقاطع والدمج نموذج كائن الصفحة في ⁨ISO 32000-2⁩؛ ويُعلِّق المصدر على البنود ذات الصلة. مزاعم قابلة للفحص خارجيًا:

تخطيط المُذيَّل، وإزاحة startxref بالبايت، ومُنهي %%EOF تتبع ⁨ISO 32000-2:2020⁩، §⁨7.5.5⁩ — المرجع ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
قيم /View في قاموس ⁨Collection⁩ (/T، /D، /H) تتبع ⁨ISO 32000-2:2020⁩، §⁨12.3.5⁩ — المرجع 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
مُدخَلات /Subtype و/N و/O و/V لحقل ⁨Collection⁩ تتبع ⁨ISO 32000-2:2020⁩، §⁨12.3.5⁩ (قاموس حقل المجموعة) — المرجع 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

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

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

كل أصناف الوحدة final؛ وأنواع النتيجة وكائنات القيمة readonly. وترجع أنواع المُقسِّم و⁨Portfolio⁩ إلى ⁨1.9.0⁩؛ وأُضيف mergeDocuments() في 3.1.0.
PageRange وMergeResult نوعان في ⁨Core⁩، فتبقى مواضع الاستدعاء قابلة للنقل بين الإصدارات.
لا تحمل مُذيَّلات المقاطع سوى /Size و/Root؛ ولا يُصدَر أي مُعرِّف ملف /ID ولا قاموس /Info.
لسير عمل التحديث التزايدي أو التوقيع، سلِّم بايتات المقاطع إلى وحدة ⁨Writer⁩ بدل تحريرها لاحقًا في مكانها.
لا تُسجِّل الوحدة أي محتوى للمستند.

حدود النشر

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