مرجع گزینه‌های پیکربندی

مرجع گزینه‌های پیکربندی

اکثر عملیات بارگذاری، ذخیره‌سازی و تبدیل در Aspose.PDF FOSS برای .NET یک *Options شیئی که رفتار آن عملیات را پیکربندی می‌کند. LoadOptions and SaveOptions دو ریشهٔ انتزاعی این خانواده هستند: هر بارگذار مخصوص فرمت (HtmlLoadOptions, MdLoadOptions, TxtLoadOptions, SvgLoadOptions) LoadOptions، و هر نویسنده مخصوص فرمت (PdfSaveOptions, HtmlSaveOptions, SvgSaveOptions) SaveOptions. این صفحه توضیح می‌دهد که این خانواده چگونه به هم پیوسته است و کلاس‌های گزینه‌ای را که هنوز توسط تبدیل و بهینه‌سازی راهنما.

بارگذاری اسناد با LoadOptions

هر زیرکلاس *LoadOptions، WarningHandler، WarningHandlerName، DisableFontLicenseVerifications و LoadFormat را از کلاس پایهٔ LoadOptions به ارث می‌برد، سپس خصوصیات مخصوص به فرمت منبع خود را اضافه می‌کند.

// HTML: resolve relative images/CSS against a base path
var htmlOptions = new HtmlLoadOptions("assets/");
htmlOptions.IsEmbedFonts = true;
using var htmlDoc = new Document("input.html", htmlOptions);

// Markdown: apply custom CSS while rendering to PDF
var mdOptions = new MdLoadOptions();
mdOptions.CssStyles = "body { font-family: sans-serif; }";
using var mdDoc = new Document("input.md", mdOptions);

// Plain text: control the rendered font size
var txtOptions = new TxtLoadOptions();
txtOptions.FontSize = 11;
using var txtDoc = Document.Open("input.txt", txtOptions);

// SVG: let the page size follow the artwork dimensions
var svgOptions = new SvgLoadOptions();
svgOptions.AdjustPageSize = true;
using var svgDoc = new Document("input.svg", svgOptions);

ذخیره به PDF با PdfSaveOptions

PdfSaveOptions کنترل مدیریت فونت و مکان‌گذاری فایل‌های موقت را هنگام نوشتن یک Document به‌صورت PDF بر عهده دارد. این کلاس CloseResponse، SaveFullPath، WarningHandler، CacheGlyphs و SaveFormat را از پایهٔ مشترک SaveOptions ارث می‌برد.

using var doc = Document.Open("input.pdf");

var pdfOptions = new PdfSaveOptions();
pdfOptions.DefaultFontName = "Arial";
pdfOptions.TempPath = "temp/";

doc.Save("output.pdf", pdfOptions);

صدور به HTML و SVG

HtmlSaveOptions و SvgSaveOptions هر دو از UnifiedSaveOptions ارث می‌برند. علاوه بر کنترل‌های تصویر/فونت/چیدمان که در راهنمای تبدیل پوشش داده شده‌اند، HtmlSaveOptions همچنین به شما امکان انتخاب نوع سند و استراتژی صفحه‌بندی را می‌دهد، در حالی که SvgSaveOptions کاملاً به اعضای ارث‌بردهٔ SaveOptions/UnifiedSaveOptions وابسته است.

using var doc = Document.Open("input.pdf");

// Fixed-layout HTML5 output, split one file per page
var htmlOptions = new HtmlSaveOptions(HtmlDocumentType.Html5, fixedLayout: true);
htmlOptions.SplitIntoPages = true;
htmlOptions.ImageResolution = 150;
htmlOptions.Title = "Converted Document";
doc.Save("output.html", htmlOptions);

// SVG export configured through the shared SaveOptions members
var svgOptions = new SvgSaveOptions();
svgOptions.SaveFullPath = false;
doc.Save("output.svg", svgOptions);

تبدیل یک‌مرحله‌ای با Document.Convert

Document.Convert یک فراخوانی ایستاتیک یک‌پارچه می‌پذیرد که منبع LoadOptions و مقصد SaveOptions را به‌صورت همزمان دریافت می‌کند، بنابراین می‌توانید بین فرمت‌ها تبدیل کنید بدون اینکه نیاز به باز کردن، تبدیل و آزادسازی دستی Document داشته باشید.

var loadOptions = new HtmlLoadOptions();
var saveOptions = new PdfSaveOptions();

Document.Convert("input.html", loadOptions, "output.pdf", saveOptions);

گزینه‌های استخراج متن

TextExtractionOptions تعیین می‌کند که چگونه TextAbsorber (و TextDevice) متن استخراج‌شده را قالب‌بندی می‌کند، بدون وابستگی به این‌که کدام جاذب یا کلاس دستگاه استخراج را انجام می‌دهد.

using var doc = Document.Open("input.pdf");

var extractionOptions = new TextExtractionOptions(TextFormattingMode.Raw);
extractionOptions.ScaleFactor = 1.0;
extractionOptions.IgnoreResourceFontErrors = true;

var absorber = new TextAbsorber(extractionOptions);
doc.Pages[1].Accept(absorber);

string text = absorber.Text;

بهینه‌سازی خروجی با OptimizationOptions

OptimizationOptions یک مکانیزم جداگانه و مستقل از فرمت برای کاهش حجم فایل است. این مکانیزم از طریق Document.OptimizeResources اعمال می‌شود، نه از طریق یک کلاس *SaveOptions، بنابراین می‌تواند با هر مسیر ذخیره‌سازی ترکیب شود.

using var doc = Document.Open("input.pdf");

var optimizationOptions = new OptimizationOptions();
optimizationOptions.RemoveUnusedObjects = true;
optimizationOptions.CompressObjects = true;
optimizationOptions.SubsetFonts = true;
optimizationOptions.ImageCompressionOptions.CompressImages = true;
optimizationOptions.ImageCompressionOptions.ImageQuality = 80;

doc.OptimizeResources(optimizationOptions);
doc.Save("optimized.pdf");

نکات و بهترین شیوه‌ها

• هر زیرکلاس *LoadOptions و *SaveOptions WarningHandler/WarningHandlerName را به ارث می‌برد - هر دو را همزمان تنظیم کنید تا تشخیص‌های قابل بازیابی را ضبط کنید.
• ترجیحاً یک نمونه *LoadOptions/*SaveOptions مخصوص فرمت را به‌جای تکیه بر استنتاج فرمت مبتنی بر پسوند استفاده کنید، به‌ویژه هنگام کار با جریان‌ها به‌جای مسیرهای فایل.
• از Document.Convert(srcFileName, loadOptions, dstFileName, saveOptions) برای تبدیل‌های یک‌بار استفاده کنید به‌جای باز کردن دستی و ذخیره‌مجدد یک Document.
• OptimizationOptions مستقل از خانواده *SaveOptions است - قبل از Save، OptimizeResources را فراخوانی کنید تا خروجی را صرف‌نظر از فرمت هدف کوچک کنید.
• یک نمونه گزینه‌ها را در چندین سند زمانی که تنظیمات یکسان اعمال می‌شود، مجدداً استفاده کنید، به‌جای بازسازی آن در هر بار.

مسائل رایج

FAQ

تفاوت بین LoadOptions و SaveOptions چیست؟

LoadOptions نحوهٔ خواندن یک سند را از فرمت منبع غیر PDF (HTML، Markdown، متن، SVG) پیکربندی می‌کند؛ SaveOptions نحوهٔ نوشتن یک Document را به فرمت خروجی (PDF، HTML، SVG) تنظیم می‌کند. هر کلاس گزینه‌های مخصوص فرمت دقیقاً از یکی از این دو ریشه ارث می‌برد.

آیا هنگام باز کردن یک PDF بومی نیاز به مشخص کردن LoadOptions دارم؟

خیر. Document.Open و سازندهٔ Document یک مسیر فایل ساده یا جریان را برای ورودی PDF بومی می‌پذیرند. زیرکلاس‌های *LoadOptions فقط زمانی لازم هستند که فرمت منبع غیر PDF مانند HTML، Markdown، متن یا SVG را وارد می‌کنید.

آیا می‌توانم همان نمونهٔ SaveOptions را در چندین فراخوانی Save دوباره استفاده کنم؟

بله. یک نمونهٔ گزینه‌ها فقط یک شیء پیکربندی ساده است؛ هیچ وضعیت سراسری برای هر سندی نگه نمی‌دارد، بنابراین همان نمونهٔ PdfSaveOptions یا HtmlSaveOptions می‌تواند به Save برای چند سند که تنظیمات یکسان دارند، پاس داده شود.

چگونه OptimizationOptions با کلاس‌های مخصوص فرمت SaveOptions متفاوت است؟

OptimizationOptions توسط Document.OptimizeResources مصرف می‌شود، گامی جداگانه از ذخیره‌سازی. این کار اشیاء/جریان‌های استفاده‌نشده را حذف کرده و تصاویر را درجا دوباره فشرده می‌کند، و می‌تواند پیش از فراخوانی Save با هر زیرکلاس *SaveOptions اعمال شود.

آیا هر فرمت منبع/هدف هر دو کلاس LoadOptions و SaveOptions را دارد؟

لزوماً متقارن نیست. برای مثال، Markdown و plain text در حال حاضر MdLoadOptions/TxtLoadOptions را برای واردات ارائه می‌دهند اما هیچ معادل *SaveOptions مطابقتی ندارند، که نشان‌دهنده جهت پشتیبانی هر فرمت برای تبدیل است.

API Reference خلاصه

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

• تبدیل و بهینه‌سازی
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation