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

لمحة سريعة

• يُولّد أختام ترقيم ⁨Bates⁩ التسلسلية على هيئة أجزاء من تدفّق محتوى ⁨PDF⁩ لكل صفحة.
• ثلاثة أنواع عامة: BatesNumberConfig (تهيئة غير قابلة للتغيير)، وBatesNumberer (المحرّك)، وBatesPosition (تعداد موضع بستّ حالات).
• كل جزء قائم بذاته. تُحفَظ حالة الرسوميات وتُستعاد، فالإلحاق لا يُخلّ أبدًا بمحتوى الصفحة القائم.
• المُخرَج حتمي: الجزء دالة خالصة من التهيئة، ونصّ الختم، وحجم الصفحة.
• لا تطرح الوحدة أي استثناءات. والمدخلات خارج النطاق تتدهور وفق قواعد الاحتياط الموثّقة.

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

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

لا توجد علامة ترخيص لكل ميزة. هذه قدرة من إصدار ⁨Pro⁩.

composer require nextpdf/pro:^3

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

الرمز	المعطيات	السلوك الافتراضي	يُرجِع	يطرح أو يفشل بـ	ملاحظات
BatesNumberConfig::__construct	string $prefix = ''، string $suffix = ''، int $startNumber = 1، int $padding = 5، BatesPosition $position = BatesPosition::BottomRight، float $fontSize = 9.0، string $fontFamily = 'Courier'، float $opacity = 1.0، bool $useLayer = true، string $layerName = 'Bates Numbers'، float $inset = 15.0	تهيئة مظهر وترقيم غير قابلة للتغيير	BatesNumberConfig	—	كل الخصائص الإحدى عشرة عامة وللقراءة فقط.
BatesNumberConfig::formatNumber	int $pageIndex ‏(يبدأ من 0)	prefix + مُبطَّن بالأصفار (startNumber + pageIndex) + suffix	string	—	الرقم الأعرض من padding لا يُقتطع.
BatesNumberConfig::getRange	int $pageCount	أول وآخر ختمين مُنسّقين للتشغيلة	array{first: string, last: string}	—	يفترض pageCount >= 1؛ وعددٌ يساوي 0 يُنسّق فهرس الصفحة ‏-1.
BatesNumberer::__construct	BatesNumberConfig $config	يربط التهيئة	BatesNumberer	—	الصنف نهائي وللقراءة فقط.
BatesNumberer::generate	int $pageCount، array $pageSizes، string $prefix = ''، int $startFrom = 1	مسار سريع ثابت بالمظهر الافتراضي	list<string>	—	تبقى اللاحقة، والموضع، والخطّ، والعتامة، والطبقة على قيمها الافتراضية.
BatesNumberer::generateStreams	int $pageCount، list<array{width: float, height: float}> $pageSizes	جزء واحد قائم بذاته لكل صفحة	list<string>	لا يطرح أبدًا؛ ومدخل حجم مفقود يرتدّ إلى ⁨A4⁩ عمودي	عدد الأجزاء يساوي pageCount؛ وتُتجاهَل مدخلات الأحجام الزائدة.
BatesNumberer::buildPageStream	string $text، float $pageWidth، float $pageHeight	يبني جزء ختم صفحة واحدة	string	—	مُغلَّف بـq/Q؛ ونصّ الختم مُهرَّب لصياغة السلسلة الحرفية.
BatesNumberer::getConfig	—	يُرجِع التهيئة المربوطة	BatesNumberConfig	—	—
BatesPosition	حالات التعداد BottomLeft، BottomCenter، BottomRight، TopLeft، TopCenter، TopRight	مفردات موضع مدعومة بسلاسل نصية	—	—	القيم الداعمة بصيغة ⁨kebab-case⁩ (مثل bottom-right).
BatesPosition::coordinates	float $pageWidth، float $pageHeight، float $textWidth، float $inset = 15.0	إحداثيا ⁨X/Y⁩ لخطّ أساس الختم في فضاء ⁨PDF⁩ الأصلي	array{x: float, y: float}	—	الأصل أسفل اليسار؛ والصفوف العلوية تضع خطّ الأساس على بُعد inset من الحافّة العلوية.

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

public function __construct(
    public string $prefix = '',
    public string $suffix = '',
    public int $startNumber = 1,
    public int $padding = 5,
    public BatesPosition $position = BatesPosition::BottomRight,
    public float $fontSize = 9.0,
    public string $fontFamily = 'Courier',
    public float $opacity = 1.0,
    public bool $useLayer = true,
    public string $layerName = 'Bates Numbers',
    public float $inset = 15.0,
) {}

public static function generate(
    int $pageCount,
    array $pageSizes,
    string $prefix = '',
    int $startFrom = 1,
): array
public function generateStreams(int $pageCount, array $pageSizes): array
public function buildPageStream(string $text, float $pageWidth, float $pageHeight): string

public function coordinates(
    float $pageWidth,
    float $pageHeight,
    float $textWidth,
    float $inset = 15.0,
): array

عقد السلوك

الترقيم

يحسب BatesNumberConfig::formatNumber قيمة startNumber + pageIndex، ويُبطِّن الرقم من اليسار بالأصفار إلى padding خانة، ويُحيطه بـprefix وsuffix. ويُرجِع getRange أول وآخر ختمين مُنسّقين لعدد صفحات. استخدمه لتسلسل ترقيم متواصل عبر عمليات الإنتاج.

تشريح الجزء

كل جزء يتكوّن، بالترتيب، من: حفظ لحالة الرسوميات (q)، ومُشغِّل لون تعبئة، وبداية محتوى مُعلَّم اختيارية، وكتلة نصّ تُموضِع الختم وتعرضه، ونهاية محتوى مُعلَّم اختيارية، واستعادة (Q). وتُسلسَل الإحداثيات وحجم الخطّ بستّ منازل عشرية، فالمدخلات المتطابقة تُنتج بايتات متطابقة. ويُهرِّب نصّ الختم المحارف \ و( و) قبل دخوله السلسلة الحرفية.

ربط الخطّ

تختار كتلة النصّ اسم مورد الخطّ الثابت /BatesFont. ويجب أن يربط قاموس موارد الصفحة المُضمِّنة ذلك الاسم بخطّ يطابق fontFamily المُهيَّأ، ويجب أن تُحَلّ العائلة في سجلّ الخطوط. أمّا توليد الجزء نفسه فلا يستشير السجلّ أبدًا.

التموضع

يحسب BatesPosition::coordinates خطّ أساس الختم في فضاء ⁨PDF⁩ الأصلي؛ والأصل أسفل اليسار. ويطرح التموضع الأوسط والأيمن عرضًا نصيًا مُقدَّرًا: طول البايتات مضروبًا في ⁨0.6⁩ مضروبًا في حجم الخطّ، وهو تقريب أحادي التباعد. والخطوط المتناسبة والنصّ متعدّد البايتات يزيحان ذلك التقدير. أمّا التموضع الأيسر فلا يعتمد عليه.

الطبقات

عند تفعيل useLayer (وهو الافتراضي)، يُحيط الجزء النصّ بين مُشغِّلَي المحتوى المُعلَّم BDC وEMC. ويأخذ اسم المحتوى المُعلَّم الصيغة /Lyr_<name>، المُشتقّة من layerName مع استبدال المحارف غير الكلمية بشُرَط سفلية. والإحاطة على مستوى الجزء فقط: أمّا تسجيل مجموعة المحتوى الاختيارية المقابلة في المستند — وهي الخطوة التي تجعل الطبقة قابلة للتبديل في العارض — فهو من شأن الكاتب المُضمِّن.

العتامة

تُصدَر opacity أقل من ⁨1.0⁩ على هيئة تعبئة رمادية أفتح. أمّا الختم المُعتِم تمامًا فيُعرَض أسود.

النطاق

يطبّق المحرّك ترقيم ⁨Bates⁩ تمامًا كما هو مُهيَّأ. وهو لا يؤكّد أنّ مستندًا مُرقَّمًا مقبول في المحكمة أو صالح قانونيًا. ويبقى مخطّط الترقيم، والاحتفاظ، والتعامل الإثباتي مسؤولية العميل؛ استشِر فريقَيك القانوني والامتثالي بشأن الكفاية الإجرائية.

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

• لا يطرح generateStreams أبدًا عند عدم تطابق pageSizes. والمدخل المفقود يرتدّ إلى ⁨A4⁩ عمودي، 595.276 في 841.890 نقطة؛ وتُتجاهَل المدخلات الزائدة.
• عدد الأجزاء يساوي دائمًا pageCount.
• الرقم الأعرض من padding لا يُقتطع؛ بل يطول نصّ الختم فحسب.
• يفترض getRange أنّ pageCount >= 1. وعددٌ يساوي 0 يُنسّق فهرس الصفحة ‏-1، أي startNumber - 1.
• العتامة تفتيح رمادي لا شفافية ⁨ExtGState⁩؛ والمحتوى المتراكب أسفل الختم لا يُمزَج.
• بايتات الختم عدا \ و( و) تمرّ دون ترميز. وصحّة الترميز للنصّ غير ⁨ASCII⁩ تعتمد على الخطّ المربوط.
• علامات ⁨Bates⁩ محتوى متراكب. وهي لا تحجب ولا تُزيل ولا تُشفّر أي شيء في الصفحة.
• لا تجري الوحدة أي عمليات تشفير؛ ولا يغيّر وضع ⁨FIPS⁩ سلوكها.

المطابقة

السلوك	المرجع	الحالة
إحاطة الطبقة عبر مُشغِّلَي المحتوى المُعلَّم BDC/EMC	ISO 32000-2:2020 §8.11.3.2	جزئي — يُصدر الجزء الإحاطة؛ أمّا تسجيل مجموعة المحتوى الاختيارية فهو خطوة الكاتب المُضمِّن

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

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

• الأجزاء قيم سلسلة نصية خالصة. اختبرها بمقارنة البايتات المباشرة؛ ولا حاجة إلى سياق مستند.
• ‏buildPageStream عامّ وقابل للاختبار الوحدوي منعزلًا: مرِّر نصًا مُنسّقًا مسبقًا وأبعاد صفحة صريحة.
• لترقيم متواصل عبر عمليات الإنتاج، ابذُر startNumber من التشغيلة السابقة وسجِّل مُخرَج getRange في سجلّ الإنتاج لديك.
• تُنقَّى أسماء الطبقات إلى محارف كلمية. فضِّل أسماء طبقات ⁨ASCII⁩ ليبقى اسم المحتوى المُعلَّم مقروءًا في أدوات الفحص.

حدود النشر

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

انظر أيضًا

• نظرة عامة على قدرة ⁨Legal⁩
• ‏⁨Merge⁩ — مرجع متعمّق
• ‏⁨Security⁩ — مرجع متعمّق