คลาสยูทิลิตี้และคลาสช่วยเหลือ

คลาสยูทิลิตี้และช่วยเหลือ

คู่มือนี้แสดงวิธีการใช้คลาสช่วยเหลือขนาดเล็กและมุ่งเน้นที่ 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 เป็นคลาสสแตติกที่กำหนดค่าเอนจิน regular-expression ที่ใช้ในการดำเนินการค้นหาข้อความเช่น 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 เป็นคลาสแบบสถิตที่ประเมินฟังก์ชัน 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 เพื่อเข้าถึง singleton, 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, แต่ละองค์ประกอบมีการกำหนดขอบเขตใน page-space 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 เป็นการฉายภาพใน page-space ของ 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 GB ของอาร์เรย์เดี่ยวของ 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 GB.
• ควรจบชุดการแก้ไข 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 GB, เนื่องจาก MemoryStream ใช้แอเรย์เดียวที่มีขีดจำกัดคงที่นั้น.

API Reference สรุป

ดูเพิ่มเติม

• Metadata และ Utilities
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation