Các lớp tiện ích và trợ giúp

Các lớp Tiện ích và Trợ giúp

Hướng dẫn này chỉ ra cách sử dụng các lớp trợ giúp nhỏ, tập trung mà Aspose.PDF FOSS cho .NET cung cấp cho các nhiệm vụ cấp thấp phổ biến: toán học số nguyên được các primitive bảo mật sử dụng, cấu hình tìm kiếm regex, đánh giá hàm PostScript, khám phá phông chữ bên ngoài, trích xuất đường dẫn phụ của vector, đo lường văn bản vật lý, chỉnh sửa luồng nội dung được đệm, các luồng bộ nhớ lớn, và báo cáo phiên bản thư viện. Các lớp này không phải là điểm vào độc lập, nhưng chúng hỗ trợ các hoạt động tài liệu, văn bản và render ở mức cao hơn trên toàn bộ API.

Trợ giúp toán học số nguyên

MathExtensions là một trợ giúp tĩnh nhỏ được sử dụng nội bộ bởi các primitive bảo mật của thư viện, nhưng nó khả dụng cho việc sử dụng chung bất cứ khi nào bạn cần một phép modulo luôn trả về kết quả không âm.

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

Cấu hình tìm kiếm Regex

RegexManager là một lớp tĩnh cấu hình động cơ biểu thức chính quy được sử dụng trong các thao tác tìm kiếm văn bản như TextFragmentAbsorber. Đặt MatchTimeout để giới hạn thời gian một mẫu được phép chạy, và bật NonBacktracking để sử dụng động cơ regex không quay lại cho các tìm kiếm nhạy cảm về hiệu năng.

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);

Đánh giá các hàm PostScript

PostScriptEvaluator là một lớp tĩnh đánh giá các hàm PDF loại 4 (PDF32000 §7.10.5) — các chương trình máy tính PostScript được nhúng trong PDF, chẳng hạn như những chương trình được sử dụng trong một số định nghĩa không gian màu và độ bóng.

double[] inputs = { 0.5 };

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

Đường dẫn tìm kiếm phông chữ bên ngoài

ExternalFontCache quản lý các thư mục được tìm kiếm cho các phông chữ TrueType/OpenType bên ngoài (không nhúng) trong quá trình render và chuyển đổi. Sử dụng Instance để truy cập singleton, GetDefaultFontsFolders để kiểm tra các vị trí tìm kiếm tích hợp, và SetFontsFolders để thêm hoặc thay thế chúng.

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);

Trích xuất các đoạn con vectơ

GraphicsAbsorber duyệt một trang và trích xuất các sub-path vectơ đã được vẽ của nó dưới dạng các phần tử SubPath, mỗi phần tử mang khung giới hạn Rectangle trong không gian trang của riêng nó. Điều này hữu ích để kiểm tra hoặc đo lường tác phẩm vectơ mà không cần phân tích luồng nội dung bằng tay.

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}]");
    }
}

Đo lường đoạn văn bản vật lý

PhysicalTextSegment là phép chiếu trong không gian trang của một TextSegment đã được hấp thụ. Truy cập nó qua TextSegment.PhysicalSegment để đo một chuỗi ký tự hoặc đọc TextState đã được giải quyết của nó.

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;
    }
}

Đệm các chỉnh sửa luồng nội dung

ContentsAppender, được truy cập qua Page.ContentsAppender, lưu đệm các toán tử để chèn vào đầu hoặc cuối luồng nội dung của trang và cam kết chúng trong một lần với 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();

Luồng bộ nhớ lớn

OptimizedMemoryStream là một luồng bộ nhớ có thể mở rộng cho phép vượt qua giới hạn 2 GB một mảng duy nhất của MemoryStream bằng cách lưu trữ dữ liệu trong các khối kích thước cố định. Nó kế thừa từ Stream, vì vậy nó hỗ trợ các thao tác đọc, ghi và di chuyển con trỏ thông thường.

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();

Thông tin phiên bản thư viện

BuildVersionInfo là một lớp tĩnh cung cấp tên sản phẩm và số phiên bản của thư viện tại thời gian chạy — hữu ích cho việc chẩn đoán và yêu cầu hỗ trợ.

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

Mẹo và Thực hành Tốt nhất

• Đặt RegexManager.MatchTimeout trước khi thực hiện tìm kiếm trên các mẫu không tin cậy hoặc do người dùng cung cấp để tránh backtracking thảm khốc.
• Gọi ExternalFontCache.SetFontsFolders với reset: true khi bạn muốn thay thế hoàn toàn các đường dẫn tìm kiếm mặc định thay vì thêm vào chúng.
• Ưu tiên OptimizedMemoryStream hơn MemoryStream khi đệm các tài liệu rất lớn hoặc dữ liệu hình ảnh có thể vượt quá 2 GB.
• Luôn luôn hoàn thành một lô các chỉnh sửa ContentsAppender bằng UpdateData() — các toán tử được đệm sẽ không được cam kết vào luồng nội dung cho đến thời điểm đó.
• GraphicsAbsorber.Elements có thể chứa các thể hiện GraphicElement khác SubPath; hãy kiểm tra kiểu trước khi ép kiểu.

Các vấn đề thường gặp

FAQ

Tại sao MathExtensions.Mod lại khác với toán tử % của C#?

MathExtensions.Mod luôn trả về phần dư không âm, trong khi toán tử % tích hợp có thể trả về giá trị âm khi số chia là âm.

Làm thế nào để ngăn một tìm kiếm văn bản dựa trên regex chạy quá lâu?

Đặt RegexManager.MatchTimeout thành TimeSpan trước khi xây dựng hoặc chạy một TextFragmentAbsorber sử dụng mẫu regex.

Liệu SetFontsFolders có thay thế hay thêm vào các đường dẫn tìm kiếm hiện có không?

Điều này phụ thuộc vào đối số reset: truyền true để thay thế danh sách thư mục hiện tại, hoặc false để thêm các thư mục mới vào danh sách.

Thực tế GraphicsAbsorber trích xuất gì?

Nó trích xuất các sub-path vector được tô màu của một trang dưới dạng các phần tử SubPath, mỗi phần tử có một Rectangle bao quanh trong không gian trang, thông qua GraphicsAbsorber.Visit.

Khi nào tôi nên sử dụng OptimizedMemoryStream thay vì MemoryStream?

Khi dữ liệu được đệm có thể tiếp cận hoặc vượt quá 2 GB, vì MemoryStream được hỗ trợ bởi một mảng duy nhất với giới hạn cứng đó.

API Reference Tóm tắt

Xem thêm

• Siêu dữ liệu và Tiện ích
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation