Kelas Utilitas dan Pembantu

Kelas Utilitas dan Pembantu

Panduan ini menunjukkan cara menggunakan kelas pembantu kecil dan terfokus yang Aspose.PDF FOSS untuk .NET sediakan untuk tugas-tugas tingkat rendah umum: matematika integer yang digunakan oleh primitif keamanan, konfigurasi pencarian regex, evaluasi fungsi PostScript, penemuan font eksternal, ekstraksi sub-jalur vektor, pengukuran teks fisik, penyuntingan aliran konten yang di-buffer, aliran memori besar, dan pelaporan versi perpustakaan. Kelas-kelas ini bukan titik masuk sendiri, tetapi mereka mendukung operasi dokumen, teks, dan rendering tingkat tinggi di seluruh API.

Pembantu Matematika Integer

MathExtensions adalah pembantu statis kecil yang digunakan secara internal oleh primitif keamanan perpustakaan, tetapi tersedia untuk penggunaan umum kapan pun Anda memerlukan operasi modulo yang selalu mengembalikan hasil non-negatif.

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

Konfigurasi Pencarian Regex

RegexManager adalah kelas statis yang mengkonfigurasi mesin ekspresi reguler yang digunakan oleh operasi pencarian teks seperti TextFragmentAbsorber. Atur MatchTimeout untuk membatasi berapa lama pola diizinkan berjalan, dan aktifkan NonBacktracking untuk menggunakan mesin regex non-backtracking pada pencarian yang sensitif terhadap kinerja.

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

Mengevaluasi fungsi PostScript

PostScriptEvaluator adalah kelas statis yang mengevaluasi fungsi PDF Tipe 4 (PDF32000 §7.10.5) — program kalkulator PostScript yang tertanam dalam PDF, seperti yang digunakan dalam beberapa definisi ruang warna dan shading.

double[] inputs = { 0.5 };

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

Jalur pencarian font eksternal

ExternalFontCache mengelola folder yang dicari untuk TrueType/OpenType faces eksternal (non-embedded) selama rendering dan konversi. Gunakan Instance untuk mengakses singleton, GetDefaultFontsFolders untuk memeriksa lokasi pencarian bawaan, dan SetFontsFolders untuk menambah atau menggantinya.

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

Mengekstrak sub-jalur vektor

GraphicsAbsorber mengunjungi sebuah halaman dan mengekstrak sub-jalur vektor yang dilukis sebagai elemen SubPath, masing-masing membawa Rectangle pembatas ruang-halaman mereka sendiri. Ini berguna untuk memeriksa atau mengukur karya vektor tanpa harus mem-parsing aliran konten secara manual.

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

Pengukuran segmen teks fisik

PhysicalTextSegment adalah proyeksi ruang-halaman dari TextSegment yang diserap. Akses melalui TextSegment.PhysicalSegment untuk mengukur rangkaian karakter atau membaca TextState yang telah diresolusikan.

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

Membuffer penyuntingan aliran-konten

ContentsAppender, yang diakses melalui Page.ContentsAppender, menampung operator untuk menambahkan di depan atau di belakang aliran konten halaman dan mengkomitnya dalam satu langkah dengan 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();

Aliran memori besar

OptimizedMemoryStream adalah aliran dalam memori yang dapat berkembang yang dapat melampaui batas 2GB satu array dari MemoryStream dengan menyimpan data dalam potongan berukuran tetap. Ia diturunkan dari Stream, sehingga mendukung operasi baca, tulis, dan seek yang biasanya.

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

Informasi versi perpustakaan

BuildVersionInfo adalah kelas statis yang menampilkan nama produk dan nomor versi perpustakaan pada waktu berjalan — berguna untuk diagnostik dan permintaan dukungan.

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

Tips dan Praktik Terbaik

• Setel RegexManager.MatchTimeout sebelum menjalankan pencarian pada pola yang tidak terpercaya atau disediakan pengguna untuk menghindari backtracking yang katastrofik.
• Panggil ExternalFontCache.SetFontsFolders dengan reset: true ketika Anda ingin sepenuhnya mengganti jalur pencarian default alih-alih menambahkannya.
• Lebih pilih OptimizedMemoryStream daripada MemoryStream saat melakukan buffering dokumen yang sangat besar atau data gambar yang mungkin melebihi 2GB.
• Selalu selesaikan satu batch edit ContentsAppender dengan UpdateData() — operator yang di-buffer tidak akan dikomit ke aliran konten sampai saat itu.
• GraphicsAbsorber.Elements mungkin berisi instance GraphicElement selain SubPath; periksa tipe sebelum melakukan casting.

Masalah Umum

FAQ

Mengapa MathExtensions.Mod berbeda dari operator C# %?

MathExtensions.Mod selalu mengembalikan sisa yang tidak negatif, sedangkan operator built-in % dapat mengembalikan nilai negatif ketika dividendnya negatif.

Bagaimana saya menghentikan pencarian teks berbasis regex agar tidak berjalan terlalu lama?

Setel RegexManager.MatchTimeout ke TimeSpan sebelum membangun atau menjalankan TextFragmentAbsorber yang menggunakan pola regex.

Apakah SetFontsFolders menggantikan atau menambah ke jalur pencarian yang ada?

Ini tergantung pada argumen reset: berikan true untuk mengganti daftar folder saat ini, atau false untuk menambahkan folder baru ke dalamnya.

Apa yang sebenarnya diekstrak oleh GraphicsAbsorber?

Ia mengekstrak sub-jalur vektor berwarna dari sebuah halaman sebagai elemen SubPath, masing-masing dengan batas Rectangle dalam ruang halaman, melalui GraphicsAbsorber.Visit.

Kapan saya harus menggunakan OptimizedMemoryStream alih-alih MemoryStream?

Saat data yang di-buffer dapat mendekati atau melebihi 2 GB, karena MemoryStream didukung oleh satu array dengan batas keras tersebut.

API Reference Ringkasan

Lihat Juga

• Metadata dan Utilitas
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation