فئات الأدوات والفئات المساعدة

فئات الأدوات والمساعدين

يُظهر هذا الدليل كيفية استخدام الفئات المساعدة الصغيرة والمركّزة التي Aspose.PDF FOSS لـ .NET تُوفّر للمهام منخفضة المستوى الشائعة: حسابات الأعداد الصحيحة المستخدمة في البنى الأمنية، تكوين البحث باستخدام التعبيرات النمطية، تقييم وظائف PostScript، اكتشاف الخطوط الخارجية، استخراج مسار فرعي للمتجهات، قياس النص الفعلي، تحريرات تدفق المحتوى المؤقت، تدفقات الذاكرة الكبيرة، وتقرير إصدار المكتبة. هذه الفئات ليست نقاط دخول بحد ذاتها، لكنها تدعم عمليات الوثائق والنصوص والعرض عالية المستوى في جميع أنحاء API.

مساعدات حساب الأعداد الصحيحة

MathExtensions هي أداة مساعدة ثابتة صغيرة تُستخدم داخليًا بواسطة البنى الأمنية للمكتبة، لكنها متاحة للاستخدام العام كلما احتجت إلى عملية modulo تُعيد دائمًا نتيجة غير سالبة.

// Unlike the C# % operator, Mod never returns a negative value.
int wrapped = MathExtensions.Mod(-3, 5); // 2

تكوين البحث باستخدام التعبيرات النمطية

RegexManager هي فئة ثابتة تقوم بتكوين محرك التعبيرات النمطية المستخدم في عمليات البحث النصي مثل TextFragmentAbsorber. اضبط MatchTimeout لتحديد الحد الزمني المسموح به لتشغيل النمط، وفعل NonBacktracking لاستخدام محرك التعبيرات النمطية غير المتراجع لأداء بحث حساس للسرعة.

using var doc = Document.Open(pdfBytes);

// Guard against runaway regex patterns.
RegexManager.MatchTimeout = TimeSpan.FromSeconds(5);
RegexManager.NonBacktracking = true;

var absorber = new TextFragmentAbsorber(@"\d{3}-\d{4}", true);
doc.Pages[1].Accept(absorber);

تقييم دوال PostScript

PostScriptEvaluator هي فئة ثابتة تقوم بتقييم وظائف PDF من النوع 4 (PDF32000 §7.10.5) — برامج حاسبة PostScript المدمجة في ملف PDF، مثل تلك المستخدمة في بعض تعريفات فضاءات الألوان والتظليل.

double[] inputs = { 0.5 };

// Evaluate a PostScript calculator program against the input array.
var outputs = PostScriptEvaluator.Evaluate("{ 2 mul }", inputs);

مسارات البحث عن الخطوط الخارجية

ExternalFontCache يدير المجلدات التي يتم البحث فيها عن الوجوه الخارجية (غير المدمجة) TrueType/OpenType أثناء العرض والتحويل. استخدم Instance للوصول إلى الكائن الوحيد، وGetDefaultFontsFolders لفحص مواقع البحث المدمجة، وSetFontsFolders لإضافتها أو استبدالها.

var cache = ExternalFontCache.Instance;
var defaultFolders = cache.GetDefaultFontsFolders();

// reset: false appends to the existing search paths instead of replacing them.
cache.SetFontsFolders(new[] { @"C:\Fonts\Custom" }, reset: false);

استخراج مسارات فرعية متجهية

GraphicsAbsorber يزور صفحة ويستخرج مساراتها المتجهية الفرعية المرسومة كعناصر SubPath، يحمل كل منها حدوده الخاصة في مساحة الصفحة Rectangle. هذا مفيد لفحص أو قياس الأعمال المتجهية دون تحليل تدفق المحتوى يدوياً.

using var doc = Document.Open(pdfBytes);

var absorber = new GraphicsAbsorber();
absorber.Visit(doc.Pages[1]);

Console.WriteLine($"Elements found: {absorber.Elements.Count}");

foreach (var element in absorber.Elements)
{
    if (element is SubPath subPath)
    {
        Rectangle bounds = subPath.Rectangle;
        Console.WriteLine($"Sub-path bounds: [{bounds.LLX}, {bounds.LLY}, {bounds.URX}, {bounds.URY}]");
    }
}

قياس جزئية النص الفعلية

PhysicalTextSegment هو إسقاط مساحة الصفحة لـ TextSegment الممتص. وصل إليه عبر TextSegment.PhysicalSegment لقياس سلسلة من الأحرف أو قراءة TextState المُحَلَّة.

using var doc = Document.Open(pdfBytes);

var absorber = new TextFragmentAbsorber();
doc.Pages[1].Accept(absorber);

foreach (TextFragment fragment in absorber.TextFragments)
{
    foreach (TextSegment segment in fragment.Segments)
    {
        PhysicalTextSegment physical = segment.PhysicalSegment;
        var width = physical.MeasureSegment(segment.StartCharIndex, segment.EndCharIndex, true);
        TextState state = physical.TextState;
    }
}

تخزين تعديلات تدفق المحتوى في الذاكرة المؤقتة

ContentsAppender، يتم الوصول إليه عبر Page.ContentsAppender، يَخزّن المشغلات لإضافة أو إلحاق محتوى إلى تدفق محتوى الصفحة ويُنفّذها في خطوة واحدة باستخدام UpdateData.

using var doc = Document.Open(pdfBytes);

Page page = doc.Pages[1];
page.ContentsAppender.AppendToBegin(new GSave());
page.ContentsAppender.AppendToEnd(new GRestore());
page.ContentsAppender.UpdateData();

تدفقات كبيرة في الذاكرة

OptimizedMemoryStream هو تدفق في الذاكرة قابل للنمو يمكنه تجاوز حد الـ 2جيجابايت للمصفوفة الواحدة في MemoryStream عن طريق تخزين البيانات في قطع ذات حجم ثابت. هو مشتق من Stream، لذا يدعم عمليات القراءة والكتابة والتمرير المعتادة.

using var stream = new OptimizedMemoryStream();

byte[] buffer = System.Text.Encoding.UTF8.GetBytes("large payload");
stream.Write(buffer, 0, buffer.Length);

bool canSeek = stream.CanSeek;
byte[] allBytes = stream.ToArray();

معلومات إصدار المكتبة

BuildVersionInfo هي فئة ثابتة تعرض اسم المنتج وإصدارات المكتبة في وقت التشغيل — مفيدة للتشخيص وطلبات الدعم.

Console.WriteLine(BuildVersionInfo.Product);
Console.WriteLine(BuildVersionInfo.AssemblyVersion);
Console.WriteLine(BuildVersionInfo.FileVersion);

نصائح وأفضل الممارسات

• قم بتعيين RegexManager.MatchTimeout قبل تنفيذ عمليات البحث على أنماط غير موثوقة أو مقدمة من المستخدم لتجنب التراجع الكارثي.
• استدعِ ExternalFontCache.SetFontsFolders مع reset: true عندما تريد استبدال مسارات البحث الافتراضية بالكامل بدلاً من إلحاقها.
• يفضَّل OptimizedMemoryStream على MemoryStream عند تخزين مؤقت لمستندات أو بيانات صور كبيرة جدًا قد تتجاوز 2 جيجابايت.
• دائمًا أكمل دفعة من تعديلات ContentsAppender باستخدام UpdateData() — لا تُلتزم المشغّلات المخزنة مؤقتًا إلى تدفق المحتوى حتى ذلك الحين.
• قد يحتوي GraphicsAbsorber.Elements على حالات GraphicElement غير SubPath؛ تحقق من النوع قبل التحويل.

مشكلات شائعة

FAQ

لماذا يختلف MathExtensions.Mod عن عامل % في C#؟

يُعيد MathExtensions.Mod دائمًا باقيًا غير سالب، بينما يمكن لعامل % المدمج أن يُعيد قيمة سالبة عندما يكون المقسوم عليه سالبًا.

كيف يمكنني إيقاف عملية بحث نصية تعتمد على regex من العمل لفترة طويلة جدًا؟

قم بتعيين RegexManager.MatchTimeout إلى TimeSpan قبل إنشاء أو تشغيل TextFragmentAbsorber الذي يستخدم نمط regex.

هل SetFontsFolders يستبدل أو يضيف إلى مسارات البحث الحالية؟

يعتمد ذلك على معامل reset: مرّر true لاستبدال قائمة المجلدات الحالية، أو false لإلحاق المجلدات الجديدة بها.

ماذا يستخرج GraphicsAbsorber فعليًا؟

يقوم باستخراج مسارات فرعية للمتجه المرسوم للصفحة كعناصر SubPath، كل منها يحتوي على Rectangle يحد مساحة الصفحة، عبر GraphicsAbsorber.Visit.

متى يجب أن أستخدم OptimizedMemoryStream بدلاً من MemoryStream؟

عندما قد يقترب البيانات المؤقتة أو تتجاوز 2 جيجابايت، لأن MemoryStream مدعوم بمصفوفة واحدة لها هذا الحد الصارم.

API Reference ملخص

انظر أيضاً

• البيانات الوصفية والأدوات
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation