کلاس‌های ابزار و کمکی

کلاس‌های ابزار و کمکی

این راهنما نشان می‌دهد چگونه از کلاس‌های کمکی کوچک و متمرکز که Aspose.PDF FOSS برای .NET فراهم می‌کند، برای وظایف سطح پایین رایج استفاده شود: ریاضیات صحیح که توسط primitiveهای امنیتی استفاده می‌شود، پیکربندی جستجوی regex، ارزیابی تابع PostScript، کشف قلم‌های خارجی، استخراج زیرمسیرهای برداری، اندازه‌گیری فیزیکی متن، ویرایش‌های بافر شده جریان محتوا، جریان‌های بزرگ در حافظه، و گزارش نسخه کتابخانه. این کلاس‌ها به تنهایی نقطه ورودی نیستند، اما پشتیبان عملیات‌های سطح بالاتر سند، متن و رندرینگ در سراسر API هستند.

کمک‌کننده‌های ریاضیات صحیح

MathExtensions یک کمک‌کنندهٔ کوچک و ایستا است که به‌صورت داخلی توسط primitiveهای امنیتی کتابخانه استفاده می‌شود، اما برای استفادهٔ عمومی در دسترس است هر زمان که به عملیاتی مدولوی نیاز داشته باشید که همیشه یک نتیجهٔ غیرمنفی برگرداند.

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

پیکربندی جستجوی Regex

RegexManager یک کلاس ایستا است که موتور عبارات منظم را که توسط عملیات‌های جستجوی متن مانند TextFragmentAbsorber استفاده می‌شود، پیکربندی می‌کند. مقدار MatchTimeout را تنظیم کنید تا محدود کنید یک الگو تا چه مدت می‌تواند اجرا شود، و NonBacktracking را فعال کنید تا از موتور regex بدون بازگشت برای جستجوهای حساس به کارایی استفاده شود.

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 یک کلاس استاتیک است که توابع نوع4PDF (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 یک جریان درون‌حافظه‌ای قابل رشد است که می‌تواند محدودیت تک‌آرایه ۲GB MemoryStream را با ذخیره‌سازی داده‌ها در تکه‌های ثابت-اندازه عبور کند. این جریان از Stream ارث می‌برد، بنابراین از عملیات‌های معمول خواندن، نوشتن و seek پشتیبانی می‌کند.

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 ترجیح دهید.
• همیشه یک دسته از ویرایش‌های ContentsAppender را با UpdateData() تمام کنید — عملگرهای بافر شده تا آن زمان به جریان محتوا متعهد نمی‌شوند.
• GraphicsAbsorber.Elements ممکن است نمونه‌های GraphicElement غیر از SubPath را شامل شود؛ قبل از تبدیل نوع، نوع را بررسی کنید.

مشکلات رایج

FAQ

چرا MathExtensions.Mod با عملگر % C# متفاوت است؟

MathExtensions.Mod همیشه باقی‌مانده‌ای غیرمنفی برمی‌گرداند، در حالی که عملگر داخلی % می‌تواند زمانی که عدد تقسیم‌شونده منفی باشد، مقدار منفی برگرداند.

چگونه می‌توانم جستجوی متنی مبتنی بر regex را از اجرا شدن بیش از حد زمان جلوگیری کنم؟

قبل از ساخت یا اجرای TextFragmentAbsorber که از الگوی regex استفاده می‌کند، RegexManager.MatchTimeout را به یک TimeSpan تنظیم کنید.

آیا SetFontsFolders مسیرهای جستجوی موجود را جایگزین می‌کند یا به آن‌ها اضافه می‌شود؟

این بستگی به آرگومان reset دارد: برای جایگزینی فهرست پوشه‌های فعلی، true را ارسال کنید، یا برای افزودن پوشه‌های جدید به آن، false را استفاده کنید.

در واقع GraphicsAbsorber چه چیزی را استخراج می‌کند؟

این زیرمسیرهای برداری رنگ‌شده یک صفحه را به عنوان عناصر SubPath استخراج می‌کند، که هر کدام دارای یک Rectangle محدود کننده در فضای صفحه هستند، از طریق GraphicsAbsorber.Visit.

چه زمانی باید به جای MemoryStream از OptimizedMemoryStream استفاده کنم؟

زمانی که داده‌های بافر شده ممکن است به ۲ گیگابایت نزدیک شوند یا از آن عبور کنند، چون MemoryStream توسط یک آرایهٔ تک با این محدودیت سخت پشتیبانی می‌شود.

API Reference خلاصه

همچنین ببینید:

• متادیتا و ابزارها
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation