الدمج — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لوحدة الدمج في ⁨NextPDF Pro⁩، وهي NextPDF\Pro\Merge. تُجمّع SmartMerger عدّة مستندات مُدخَلة في مستند واحد وتطبّق تحسينات ⁨Pro⁩: شجرة إشارات مرجعية مُدمَجة من تسميات كل مُدخَل، وإزالة التكرار على مستوى المستند بالكامل، وتحديد نطاق الصفحات لكل مُدخَل، واكتشاف الروابط الداخلية. وSemanticSplitter هي نقطة دخول التقسيم المُدرِكة للبنية المُصاحِبة. تُبيّن هذه الصفحة الواجهة البرمجية العامة، وعقد السلوك القابل للملاحظة، وحدود الموارد، وأنماط الفشل. أمّا الإعداد الموجَّه للمهام والعيّنات فتوجد في صفحة قدرة الدمج.

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

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

لا توجد راية قدرة زمن تشغيل تحكم هذه الوحدة. وأصناف الدمج قابلة للاستخدام متى ما كان nextpdf/pro مُثبَّتًا ومُرخَّصًا.

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

الرمز	المعاملات	السلوك الافتراضي	يُرجِع	يطرح أو يفشل بـ	ملاحظات
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	يقبل الدامج الأساسي القديم ويتجاهله؛ ووسيط null للمُقسِّم يُنشئ مُقسِّم ⁨Pro⁩ الافتراضي	—	—	يُحتفَظ بـ$coreMerger للإنشاء المتوافق مع الإصدارات السابقة فقط
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	يختزل نطاقات الصفحات، ويزيل تكرار المُدخَلات الكاملة، ويفوّض التجميع الأساسي، ثم يحقن الإشارات المرجعية ويعدّ الروابط وفق الإعداد	SmartMergeResult	InvalidArgumentException عند قائمة مُدخَلات فارغة؛ وOverflowException عندما يتجاوز عدد المُدخَلات maxInputs أو يتجاوز أحد المُدخَلات maxBytesPerInput	نقطة دخول الدمج الوحيدة
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	كائن قيمة؛ و$pageRanges الفارغ يختار جميع الصفحات	—	—	للقراءة فقط
MergeInput::hasPageRanges()	—	صحيح عندما يحمل المُدخَل نطاق صفحات واحدًا على الأقل	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	كائن قيمة يحمل مفاتيح تبديل التحسينات وحدود الموارد	—	—	للقراءة فقط؛ وإزالة التكرار اختيارية بالاشتراك
SmartMergeConfig::default()	—	الإشارات المرجعية ومسح الروابط مُفعَّلان، وإزالة التكرار مُعطَّلة	self	—	مصنع ثابت
SmartMergeConfig::basic()	—	جميع التحسينات مُعطَّلة؛ التسلسل الأساسي فقط	self	—	مصنع ثابت
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	حامل للقراءة فقط للبايتات المُدمَجة وإحصاءات الدمج	—	—	للقراءة فقط
SmartMergeResult::isValid()	—	صحيح عندما يبدأ الناتج بترويسة %PDF	bool	—	فحص الترويسة فقط
SmartMergeResult::hasOptimizations()	—	صحيح عند إزالة أي تكرار أو عدّ أي رابط	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	وسيط null يُنشئ مُقسِّم ⁨Pro⁩ الافتراضي	—	—	حقن عبر المُنشئ لأغراض الاختبار
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	يكتشف مُعامِلات Tf بحجم العناوين بوصفها بدايات أقسام ويقسّم عند تلك الحدود؛ وعند عدم اكتشاف أي بنية يُرجِع قسمًا واحدًا للمستند بالكامل	SplitResult	InvalidArgumentException عندما يكون المخزن المؤقت فارغًا أو يفتقر إلى ترويسة %PDF؛ وOverflowException عندما يتجاوز المُدخَل 100 MB	يعود احتياطيًا إلى تقسيم نطاق الصفحات في ⁨Core⁩

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

public function __construct(
    ?PdfMerger $coreMerger = null,
    ?PdfSplitter $splitter = null,
)

public function merge(
    array $inputs,
    SmartMergeConfig $config = new SmartMergeConfig(),
): SmartMergeResult

public function __construct(
    public string $pdfData,
    public array $pageRanges = [],
    public string $label = '',
)

public function hasPageRanges(): bool

public function __construct(
    public bool $consolidateBookmarks = true,
    public bool $deduplicatePages = false,
    public bool $rewriteLinks = true,
    public int $maxInputs = 100,
    public int $maxBytesPerInput = 100_000_000,
)

public static function default(): self

public static function basic(): self

public function isValid(): bool

public function hasOptimizations(): bool

public function __construct(?PdfSplitter $splitter = null)

public function splitByStructure(
    string $pdfData,
    float $headingFontThreshold = 14.0,
): SplitResult

عقد السلوك

مسار الدمج

تُشغّل SmartMerger::merge() مسارًا ثابتًا، يُلاحَظ خارجيًا كما يلي.

1. تُثير قائمة المُدخَلات الفارغة InvalidArgumentException. ثم يُقيَّد عدد المُدخَلات بـmaxInputs؛ وأي تجاوز يُثير OverflowException.
2. يُفحَص حجم كل مُدخَل مقابل maxBytesPerInput قبل الاستخدام. وعندما يُعلن المُدخَل نطاقات صفحات، يُختزَل أولًا إلى الصفحات المُختارة عبر مُقسِّم ⁨Pro⁩، ثم يُسهم بتلك الصفحات فقط.
3. عند تفعيل deduplicatePages، تُبصَم سلسلة البايتات الكاملة لكل مستند مُدخَل بالدالة غير التشفيرية xxh128. ويُسقَط أي مُدخَل تتطابق بايتاته تمامًا مع مُدخَل سابق. وإزالة التكرار تكون على مستوى المستند بالكامل وبتطابق بايتي دقيق.
4. يفوّض التجميع الأساسي إلى محرك ⁨Pro⁩ PdfSplitter::mergeDocuments()، الذي يعيد ترقيم كل مُدخَل ضمن فضاء كائنات متّصل واحد ويُصدِر جدول إحالات مرجعية حقيقيًا.
5. يُطبَّق دمج الإشارات المرجعية عند تفعيل consolidateBookmarks وحمل مُدخَل واحد على الأقل تسمية غير فارغة. ويُدرَج قاموس /Outlines مُصغَّر، مرتبط من كتالوج المستند، مع إدخال مخطط واحد لكل مُدخَل بترتيب الدمج.
6. عند تفعيل rewriteLinks، يُمسَح الناتج المُدمَج بحثًا عن إجراءات /S /GoTo ويُبلَّغ عن عددها.

إحصاءات النتيجة

تُبلِّغ SmartMergeResult عن البايتات المُدمَجة إضافةً إلى الإحصاءات. تأتي totalPages من الدمج الأساسي. وsourceCount هو عدد المُدخَلات الأصلي، مأخوذًا قبل إزالة التكرار. وmergedSize هو طول الناتج بالبايت. وتَعُدّ bookmarksAdded المُدخَلات التي قدّمت تسمية غير فارغة فقط. وتَعُدّ duplicatesRemoved المُدخَلات الكاملة المُسقَطة. وlinksRewritten هو عدد GoTo المُكتشَف. وتسرد inputLabels التسميات المُحلّاة بترتيب الدمج. وتفحص isValid() ترويسة %PDF؛ وتكون hasOptimizations() صحيحة عند إزالة تكرار أو عدّ رابط.

عناوين الإشارات المرجعية

يحمل كل إدخال مخطط تسمية المُدخَل بوصفها /Title، مهروبةً كسلسلة ⁨PDF⁩ حرفية وفق ⁨ISO 32000-2⁩:2020 §7.3.4.2. تُضاعَف الشرطة المائلة العكسية أولًا، وتُهرَّب الأقواس، وتستخدم بايتات التحكّم المُسمّاة تسلسلاتها المُعرَّفة، ويصبح أي بايت غير قابل للطباعة يتبقّى هروبًا ثُمانيًا من ثلاث خانات. ومن ثمّ لا يمكن لتسمية عدائية أن تُخِلّ بتزامن محدّد السلسلة الحرفية أو أن تحقن بنية كائنات. وتتلقّى المُدخَلات ذات التسمية الفارغة عنوانًا نائبًا Document N، مُفهرَسًا من واحد.

التجميع الأساسي

الدالة PdfMerger::merge() القديمة في ⁨Core⁩ هي كعب فاشل-مغلق متعمَّد في هذا الإصدار؛ ولا تستدعيها SmartMerger أبدًا. وبدلًا من ذلك يجري الدمج الأساسي عبر PdfSplitter::mergeDocuments() في ⁨Pro⁩، فيحمل الملف المُدمَج جدول إحالات مرجعية دقيقًا بالبايت بإدخال واحد لكل كائن غير مباشر وفق ⁨ISO 32000-2⁩:2020 §7.5.4. وتتبع الحتمية الملف الموصَّف لمُقسِّم ⁨Pro⁩: تُنتِج المُدخَلات والإعداد المتطابقة تدفّق بايتات مستقرًا.

التقسيم المُدرِك للبنية

تمسح SemanticSplitter::splitByStructure() تدفّقات محتوى الصفحات بحثًا عن مُعامِلات ضبط الخط Tf عند headingFontThreshold (الافتراضي 14.0) أو أعلى منه وتعامل كل صفحة كهذه كبداية قسم. وتُحوَّل الحدود إلى نطاقات صفحات وتُفوَّض إلى PdfSplitter::split() في ⁨Pro⁩. وعند عدم اكتشاف أي حدّ، يُرجَع المستند بالكامل كقسم واحد. ويجب أن يبدأ المُدخَل بـ%PDF وأن يبقى ضمن حدّ 100 MB.

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

• تفشل قائمة المُدخَلات الفارغة بـInvalidArgumentException قبل أي تجميع.
• يفشل عددُ مُدخَلات يفوق maxInputs (الافتراضي 100)، أو أي مُدخَل يفوق maxBytesPerInput (الافتراضي 100 MB)، بـOverflowException. وكلا الحدّين رفضٌ فاشل-مغلق متعمَّد، وليسا خطأين عابرين.
• إزالة التكرار على مستوى المستند بالكامل وبتطابق بايتي دقيق. ويُحتفَظ بمُدخَلين يُعرَضان بشكل متطابق لكنهما يختلفان في أي بايت كليهما، وتَعُدّ duplicatesRemoved المُدخَلات الكاملة المُسقَطة رغم اسم deduplicatePages الموجَّه نحو الصفحات.
• تعكس sourceCount عدد المُدخَلات الأصلي، لا عدد المستندات بعد إزالة التكرار.
• لا يُطلَق دمج الإشارات المرجعية إلا عندما يكون لمُدخَل واحد على الأقل تسمية غير فارغة. ومع كون consolidateBookmarks صحيحة لكن كل تسمية فارغة، لا يُكتَب أي كائن /Outlines.
• تحمل إدخالات المخطط المحقونة عناوين وروابط الشجرة /Parent و/Prev و/Next؛ لكنها لا تُضمِّن وجهات /Dest صريحة في هذا الإصدار.
• تَعُدّ إعادة كتابة الروابط إجراءات /S /GoTo فقط؛ ولا تعيد توجيه الوجهات عبر الكائنات المُعاد ترقيمها. عامِل linksRewritten كعدد اكتشاف.
• اكتشاف SemanticSplitter معجميّ. فهو يعتمد على مُعامِلات حجم الخط Tf، لذا لا تُنتِج الصفحات ذات الصور فقط أو المُرمَّزة بشكل غير اعتيادي أي حدود وتُرجِع قسمًا واحدًا للمستند بالكامل.

سلوك وضع ⁨FIPS⁩

لا تجري أي عملية تشفيرية في هذه الوحدة، لذا لا يوجد سلوك خاص بوضع FIPS. وبصمة المحتوى xxh128 المستخدمة لإزالة التكرار هي تجزئة غير تشفيرية لاكتشاف التغيير ولا تحمل أي وزن سلامة أو إثبات.

المطابقة

الادّعاء	المعيار	البند
إشارات مرجعية مُدمَجة مكتوبة كقاموس /Outlines مرتبط من كتالوج المستند	ISO 32000-2:2020	§7.7.2
الدمج الأساسي يُصدِر جدول إحالات مرجعية دقيقًا بالبايت لكل كائن غير مباشر	ISO 32000-2:2020	§7.5.4
عناوين إدخالات المخطط مهروبة كسلاسل ⁨PDF⁩ حرفية، مع معالجة الشرطة المائلة العكسية والأقواس	ISO 32000-2:2020	§7.3.4.2
إعادة حلّ الروابط الكاملة عبر المستندات	—	غير مدعوم (اكتشاف GoTo فقط)
وجهات مخطط صريحة لكل قسم	—	غير مُصدَرة في هذا الإصدار

جميع البنود مُعاد صياغتها؛ ولا تعيد ⁨NextPDF⁩ إنتاج النص المعياري. وهذه بيانات قدرات، لا شهادات؛ ولا تحمل ⁨NextPDF⁩ أي شهادة ولا تمنح أيًّا منها.

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

• التوفّر ضمن حزمة ⁨Pro⁩: SmartMerger وMergeInput وSmartMergeConfig وSmartMergeResult وSemanticSplitter منذ 2.2.0. وكلها حاليّة في nextpdf/pro 3.1.0.
• يفوّض الدمج الأساسي إلى PdfSplitter::mergeDocuments() في ⁨Pro⁩. والدالة PdfMerger::merge() القديمة في ⁨Core⁩ هي كعب فاشل-مغلق في هذا الإصدار ولا تُستدعى أبدًا.
• فعِّل deduplicatePages فقط عندما يُحتمَل أن تكون المُدخَلات مستندات كاملة متطابقة بايتيًا؛ فهو لا يطوي النسخ شبه المُكرَّرة أو المُعاد ترميزها.
• استخدم SmartMergeConfig::basic() للتسلسل الصافي و::default() للإشارات المرجعية إضافةً إلى مسح الروابط.
• التقط OverflowException عند دمج مُدخَلات غير موثوقة؛ فحدّا العدد والحجم رفضٌ متعمَّد.
• فضِّل استخدام PdfSplitter في ⁨Pro⁩ مباشرةً لتقسيم نطاق الصفحات البسيط؛ ولا تلجأ إلى SemanticSplitter إلا عند الحاجة إلى تقسيم مدفوع بالعناوين.

حدود النشر

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

انظر أيضًا

• الدمج (القدرة) — التثبيت، والبدء السريع، وعيّنات الإنتاج.
• Toc — مرجع متعمّق
• Diff — مرجع متعمّق
• Document — مرجع متعمّق — مُقسِّم ⁨Pro⁩ ومحرك الدمج الأساسي.