מחלקות כלי ועזר

מחלקות שירות ועזר

מדריך זה מראה כיצד להשתמש במחלקות העזר הקטנות והממוקדות ש-Aspose.PDF FOSS עבור .NET מספקות למשימות ברמת-הנמוך השכיחות: חשבון שלמים המשמש את פרימיטיבות האבטחה, תצורת חיפוש regex, הערכת פונקציות PostScript, גילוי גופנים חיצוניים, חילוץ תתי-נתיב של וקטורים, מדידת טקסט פיזית, עריכות זרים של זרמי תוכן עם חוצץ, זרמים גדולים בזיכרון, ודיווח גרסת הספרייה. מחלקות אלו אינן נקודות כניסה בפני עצמן, אך הן תומכות בפעולות מסמכים, טקסט והצגה ברמה גבוהה לאורך כל API.

מחלקות עזר לחישוב שלמים

MathExtensions היא מחלקת עזר סטטית קטנה המשמשת פנימית בפרימיטיבות האבטחה של הספרייה, אך היא זמינה לשימוש כללי מתי שאתה צריך פעולה מודולו שתמיד מחזירה תוצאה לא שלילית.

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

תצורת חיפוש Regex

RegexManager היא מחלקה סטטית שמגדירה את מנוע הביטויים הרגולריים המשמש בפעולות חיפוש טקסט כגון TextFragmentAbsorber. הגדר את MatchTimeout כדי להגביל את משך זמן הריצה המותר לתבנית, והפעל את NonBacktracking כדי להשתמש במנוע regex ללא חזרה (non-backtracking) לחיפושים רגישים לביצועים.

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 הוא זרם בזיכרון שניתן להרחבה שיכול לחרוג ממגבלת 2GB של מערך יחיד של 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 לפני הרצת חיפושים על תבניות לא מהימנות או שסופקו על-ידי המשתמש כדי למנוע backtracking קטסטרופלי.
• קרא ל-ExternalFontCache.SetFontsFolders עם reset: true כאשר ברצונך להחליף לחלוטין את נתיבי החיפוש ברירת המחדל במקום להוסיף אליהם.
• העדף את OptimizedMemoryStream על פני MemoryStream כאשר מאגרים במטמון מסמכים גדולים מאוד או נתוני תמונה שעשויים לחרוג מ-2GB.
• תמיד סיים אצווה של עריכות 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?

כאשר הנתונים המואגרים עלולים להתקרב או לחרוג מ-2GB, מכיוון ש-MemoryStream מגובה במערך יחיד עם מגבלה קשיחה כזו.

API Reference סיכום

ראה גם

• מטא-דטה וכלים
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation