Enterprise الإصدار

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

في لمحة

هذه الصفحة هي المرجع المتعمّق لمساحة الأسماء NextPDF\Enterprise\Common. تشحن هذه المساحة رمزًا عامًّا واحدًا: كائن القيمة BoundingBox. وهو مستطيل غير قابل للتغيير ومُسوّى للتموضع المكاني المستقل عن الدقة على الصفحة. تستهلكه أسطح ⁨Enterprise Intelligence⁩ و⁨Privacy⁩ في هندسة خلايا الجداول، ومواقع الكيانات، ومناطق التنقيح. ولا تُجري الوحدة أي إدخال/إخراج، ولا تحمل أي محتوى مستند، ولا تمسّ أي تشفير. للإرشاد حول سير العمل، اقرأ صفحة قدرة ⁨Common⁩ أولًا.

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

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

لا تُجري البدائية نفسها أي حجب ترخيصي؛ إذ يحدث الحجب على أسطح ⁨Enterprise⁩ التي تستهلكها. ولا يوجد مكافئ لهذا الصنف في طبقة ⁨Core⁩ أو طبقة ⁨Pro⁩. تُشحَن في حزمة nextpdf/enterprise فقط، ولا تكرّر أنواع هندسة ⁨Core⁩ ولا تحلّ محلّها.

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

الرمز	المعاملات	السلوك الافتراضي	يُرجِع	يرفع أو يفشل بـ	ملاحظات
`BoundingBox::__construct`	`float $x`، `float $y`، `float $width`، `float $height`	يتحقّق من كل قيمة مقابل `[0.0, 1.0]`، ثم يتحقّق من مجموعَي الحافتين	`BoundingBox`	`InvalidArgumentException` عندما تكون قيمة خارج النطاق أو يتجاوز مجموع حافة `1.0 + 1e-9`	تصبح القيم الأربع كلها خصائص `public readonly`
`BoundingBox::area`	لا شيء	يضرب `width` في `height`	`float`	لا شيء مُعلَن	يُرجِع `0.0` للصناديق المتدهورة
`BoundingBox::contains`	`self $other`	يختبر ما إذا كان `$other` يقع بالكامل داخل هذا الصندوق	`bool`	لا شيء مُعلَن	تتسامح الحافتان اليمنى والسفلية مع `+1e-9`؛ وتُقارَن الحافتان اليسرى والعلوية بدقّة تامة
`BoundingBox::overlaps`	`self $other`	يختبر تقاطع مستطيل صارمًا	`bool`	لا شيء مُعلَن	المُعامَل ذو المساحة الصفرية على أي من الجانبين يُرجِع `false`

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

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

عقد السلوك

نموذج الإحداثيات

القيم الأربع كلها كسور من أبعاد الصفحة، مُسوّاة إلى النطاق [0.0, 1.0].
يحدّد x الحافة اليسرى ويحدّد y الحافة العلوية للصندوق. ويحدّ x + width وy + height الحافتين اليمنى والسفلية.
تجعل التسوية كل عملية مستقلة عن الدقة. فالصندوق نفسه يخاطب منطقة الصفحة نفسها عند أي حجم عرض أو ⁨DPI⁩.

الإنشاء

المُنشئ هو نقطة التحقّق الوحيدة. والإحداثي الخارج عن [0.0, 1.0] يرفع InvalidArgumentException؛ وتُسمّي الرسالة المكوّن المخالف والقيمة المُستقبَلة.
ومجموع الحافة الذي يفوق 1.0 + 1e-9 يرفع InvalidArgumentException؛ وتُبلِّغ الرسالة عن المُعامَلين ومجموعهما. ويمتصّ التفاوت 1e-9 تقريب الفاصلة العائمة الناتج عن حساب التسوية في المنبع.
والنسخة المُنشأة غير قابلة للتغيير. فالصنف final readonly، لذا تفشل كتابات الخصائص بخطأ Error في ⁨PHP⁩، ولا يمكن توسيع الصنف.

المسندات

يُرجِع area() القيمة width * height. وهو حساب نقي بلا آثار جانبية.
يُرجِع contains() القيمة true عندما يقع الصندوق الآخر بالكامل داخل هذا الصندوق. وتحمل مقارنتا الحافتين اليمنى والسفلية تفاوتًا يقارب +1e-9؛ أمّا مقارنتا الحافتين اليسرى والعلوية فدقيقتان تمامًا. وكل صندوق يحتوي نفسه، ويمكن احتواء صندوق ذي مساحة صفرية.
يُرجِع overlaps() القيمة true عند تقاطع مستطيل صارم. وجميع مقارنات الحواف الأربع صارمة بلا تفاوت. وإذا كان لأيٍّ من المُعامَلين مساحة صفرية، فالنتيجة false.
ولذلك لا يستلزم الاحتواء تداخلًا: فالصندوق المتدهور داخل صندوق آخر محتوًى لكنه لا يتداخل أبدًا.
ولا تُجري أي دالة إدخالًا/إخراجًا، ولا استمرارية، ولا وصولًا إلى الشبكة، ولا تسجيلًا، ولا تحمل أيٌّ منها محتوى مستند أو بيانات شخصية. ولا يوجد مورد يملكه المُشغِّل لهذا السطح.

المستهلِكون

تشترك وحدات ⁨Enterprise⁩ في هذه البدائية بدلًا من تعريف هندسة خاصة بكل وحدة. ففي ⁨Intelligence⁩، يحمل خرج TableExtractor هذه البدائية على قيم TableCell وKeyValuePair. وفي ⁨Privacy⁩، تحدّد PiiEntity وRedactionFinding وZoneRedaction موقع المحتوى بها، ويستهلك RedactionEngine تلك المواقع. وعقود تلك الأسطح مُوثَّقة في صفحات مرجعها الخاصة.

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

مكوّن خارج النطاق. أيٌّ من القيم الأربع دون 0.0 أو فوق 1.0 يرفع InvalidArgumentException عند الإنشاء. وتُرفَض INF و-INF بالحارس نفسه.
فيض مجموع الحافة. x + width أو y + height فوق 1.0 + 1e-9 يرفع InvalidArgumentException. ومجموع ضمن التفاوت 1e-9 يُنشأ بنجاح.
إدخال NAN. يستخدم حارس النطاق مقارنات مرتّبة، وكل مقارنة مرتّبة مع NAN خاطئة، لذا لا يُرفَض المكوّن NAN. وتُبلِّغ هذه النسخة عن مساحة NAN وتُرجِع false من كلا المسندين. نقِّ مصادر الأعداد العائمة في المنبع قبل الإنشاء.
الصناديق ذات المساحة الصفرية. الصندوق ذو العرض الصفري أو الارتفاع الصفري لا يتداخل مع أي شيء أبدًا، بما في ذلك نفسه. ومع ذلك يمكن احتواؤه في صندوق غير متدهور. احسب حساب هذا اللاتماثل في منطق التقاطع.
الصناديق المتلامسة عند الحواف. الصندوقان اللذان يتشاركان حافة أو ركنًا فقط لا يتداخلان؛ فاختبار التقاطع صارم.
لاتماثل تفاوت الاحتواء. الصندوق الداخلي الذي تقع حافته اليسرى أو العلوية خارج الصندوق الخارجي بأي مقدار يفشل في الاحتواء؛ فالحافتان اليمنى والسفلية وحدهما تنالان سماح 1e-9.
وضع ⁨FIPS⁩. لا تُجري هذه الوحدة أي عمليات تشفير؛ ولا يغيّر وضع ⁨FIPS⁩ سلوكها.

المطابقة

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

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

الصنف متوفّر منذ nextpdf/enterprise ⁨2.2.0⁩؛ وسطحه العام لم يتغيّر في 3.1.0.
حوّل إحداثيات فضاء الصفحة المطلقة إلى كسور نسبية إلى الصفحة قبل الإنشاء. فالصنف يتحقّق من النطاق لا من الدلالة؛ ولا يمكنه اكتشاف منطقة معقولة لكنها خاطئة.
النسخ كائنات قيمة بسيطة ورخيصة الإنشاء. لا تجمّعها ولا تخزّنها مؤقتًا.
نسختان بإحداثيات متطابقة تتساويان تحت المساواة الفضفاضة (==)؛ أمّا الهوية الصارمة (===) فتميّز بينهما. فضِّل مقارنة الإحداثيات في الاختبارات.
للهندسة التي تتجاوز المسندات المنطقية، اشتقّ الحواف من الخصائص العامة: الحافة اليمنى x + width، والحافة السفلية y + height.
عند اختبار حدود التفاوت، افحص جانبَي 1e-9 على حارس مجموع الحافة وعلى مقارنتَي الاحتواء اليمنى/السفلية.

حدود النشر

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