مرجع خيارات التكوين

مرجع خيارات التكوين

تُقبل معظم عمليات التحميل والحفظ والتحويل في 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 - استدعِ OptimizeResources قبل Save لتقليص الناتج بغض النظر عن تنسيق الهدف.
• أعد استخدام كائن الخيارات الواحد عبر مستندات متعددة عندما تكون الإعدادات نفسها مطبقة، بدلاً من إعادة إنشائه في كل مرة.

المشكلات الشائعة

FAQ

ما الفرق بين LoadOptions و SaveOptions؟

LoadOptions يحدد كيفية قراءة المستند من تنسيق مصدر غير PDF (HTML، Markdown، نص، SVG)؛ SaveOptions يحدد كيفية كتابة Document إلى تنسيق إخراج (PDF، HTML، SVG). كل فئة خيارات خاصة بالتنسيق تُشتق من أحد هذين الجذرين بالضبط.

هل أحتاج إلى تحديد LoadOptions عند فتح ملف PDF أصلي؟

لا. Document.Open ومُنشئ Document يقبلان مسار ملف عادي أو تدفق للمدخلات PDF الأصلية. فئات *LoadOptions الفرعية لا تُطلب إلا عند استيراد تنسيق مصدر غير PDF مثل HTML، Markdown، نص، أو SVG.

هل يمكنني إعادة استخدام نفس مثيل SaveOptions عبر عدة استدعاءات Save؟

نعم. مثيل الخيارات هو مجرد كائن تكوين عادي؛ لا يحمل أي حالة خاصة بالمستند، لذلك يمكن تمرير نفس مثيل PdfSaveOptions أو HtmlSaveOptions إلى Save لعدة مستندات تشترك في نفس الإعدادات.

ما الفرق بين OptimizationOptions وفئات SaveOptions الخاصة بالتنسيق؟

OptimizationOptions تُستهلك بواسطة Document.OptimizeResources، خطوة منفصلة عن الحفظ. إنها تُزيل الكائنات/التدفقات غير المستخدمة وتُعيد ضغط الصور في موضعها، ويمكن تطبيقها قبل استدعاء Save بأي فئة فرعية من *SaveOptions.

هل لكل تنسيق مصدر/هدف فئة LoadOptions وفئة SaveOptions؟

ليس بالضرورة متماثلًا. على سبيل المثال، يتيح Markdown والنص العادي حاليًا MdLoadOptions/TxtLoadOptions للاستيراد ولكن لا وجود لمقابل *SaveOptions مماثل، مما يعكس الاتجاه الذي يُدعم فيه كل تنسيق للتحويل.

API Reference ملخص

انظر أيضاً

• التحويل والتحسين
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation