תצורות פורמט – תיעוד Doconut

כל מסמך נפתח עם מימוש של BaseConfig. העבירו אחד ל-OpenDocumentAsync או תנו לקטלוג הפורמט ליצור את ברירת המחדל שלו. כל המחלקות שלהלן נמצאות במרחב השמות Doconut.

csharp

var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true,
    ImageResolution = 150
});

ירושה והגדרות PDF מקוננות

כל פורמט יורש את חמשת המאפיינים של BaseConfig. פורמטים שיכולים להפנות דרך PDF חושפים PdfConfig מקונן. ב-WordConfig, ExcelConfig ו-PptConfig, AllowSearch ו-AllowCopy הם מאפיינים נוחים שקוראים וכותבים את ה-PdfConfig המקונן.

DefaultRender = true בוחר במעבד הפורמט המקורי. בפורמטים עם הפנייה ל-PDF, false ממיר תחילה ל-PDF בזיכרון ולאחר מכן משתמש במציג ה-PDF. נתיב זה לעיתים קרובות שימושי לחיפוש לפי קואורדינטות טקסט, אך מוסיף המרה נוספת.

אלא אם צוין אחרת, הטבלאות מציגות ערכי ברירת המחדל של הבונה/מאפיין. קטלוג הפורמט האוטומטי מתעלם בכוונה משניים מהם: הוא יוצר ExcelConfig עם SplitWorksheets = true, ו-MhtConfig עם DefaultRender = false.

תצורת בסיס (BaseConfig)

סוג	מאפיין	ברירת מחדל	התנהגות
`int`	`ImageResolution`	`0`	`0` משתמש בברירת המחדל של הפורמט. טווח תקף מפורש הוא 25-300 DPI; הקצאות בלתי תקינות מתעלמים.
`string`	`DocumentCulture`	`""`	`""` מגדיר אזור לשדות תאריכים ומספרים. ערכים שאינם ריקים נחתכים; הקצאות ריקות מתעלמים.
`string`	`Password`	`""`	`""` סיסמת מסמך מוגן. `DocOptions.Password` מועתק כאן אוטומטית.
`bool`	`ShowUI`	`true`	`true` מאפיין תאימות; המציג הנוכחי אינו משתמש בו לשליטה בסרגל הכלים של הדפדפן.
`bool`	`CachePages`	`true`	`true` שומר במטמון תמונות של דפים מרונדרים עבור סשן המסמך.

תצורת PDF (PdfConfig)

פורמטים: PDF. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` מתג תאימות. המפעל הנוכחי משתמש במציג ה-PDF המקורי.
`bool`	`AllowSearch`	`false`	`false` בונה/משתמש באינדקס חיפוש טקסט של PDF. דורש את יכולת הרישיון Search לבקשות.
`bool`	`AllowCopy`	`false`	`false` מאפשר פעולות בחירת טקסט/העתקה.
`bool`	`ExtractHyperlinks`	`false`	`false` מחלץ ריבועים של קישורים עבור שכבות לקוח.
`int`	`HyperlinksPageCount`	`0`	`0` מספר העמודים המרביים שנסרקו לחיפוש קישורים; `0` משמעותו כל העמודים.
`bool`	`CompressImages`	`false`	`false` מכווץ תמונות משובצות לפני הרינדור.
`int`	`CompressQuality`	`100`	`100` איכות JPEG המשמשת כאשר דחיסה מופעלת.
`bool`	`ResizeImages`	`false`	`false` משנה גודל תמונות משובצות לפני הרינדור.
`int`	`ResizeResolution`	`300`	`300` DPI יעד לתמונות בגודל מותאם.
`bool`	`CompressFast`	`false`	`false` מעדיף את נתיב הדחיסה המהיר, באיכות נמוכה יותר.
`bool`	`FixInvalidImages`	`false`	`false` מנסה לתקן תמונות משובצות בלתי תקינות.
`bool`	`SplitSegments`	`false`	`false` מאחד מילים שנפצלות על פני מקטעי שורה כדי לשפר חיפוש/העתקה.

showHyperlinks ב-ViewerConfig שולט בשכבת הלקוח, בעוד ExtractHyperlinks שולט בחילוץ בצד השרת. אפשר להפעיל את שניהם.

תצורת Word (WordConfig)

פורמטים: DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, XML. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` רינדור Word מקורי; `false` משתמש בהפנייה ל-PDF.
`PdfConfig`	`PdfConfig`	new instance	הגדרות המשמשות בנתיב PDF/חיפוש.
`DocPaperSize`	`PaperSize`	`A4`	גודל נייר פלט. השתמש ב-`Custom` עם רוחב/גובה.
`int`	`PaperWidth`	`595`	רוחב מותאם בנקודות.
`int`	`PaperHeight`	`841`	גובה מותאם בנקודות.
`bool`	`RemovePaperMargin`	`false`	הסר מרווחי עמוד של המסמך.
`bool`	`RenderPageColor`	`true`	שומר על צבע העמוד המוגדר ב-Word; `false` מציג עמודים לבנים.
`bool`	`ExportPdfA`	`false`	השתמש ב-PDF/A ארכיוני בנתיב PDF.
`Encoding?`	`FileEncoding`	`null`	דרוס קידוד מקור.
`string`	`FontInfo`	`""`	מידע על החלפת גופנים.
`string[]?`	`FontFolders`	`null`	ספריות גופנים נוספות, שימושיות במיוחד ב-Linux/קונטיינרים.
`bool`	`AllowSearch`	`false`	מועבר ל-`PdfConfig.AllowSearch`.
`bool`	`AllowCopy`	`false`	מועבר ל-`PdfConfig.AllowCopy`.
`TableAutoFitBehavior`	`AutoFitAllTables`	`None`	`None`, `AutoFitToContents`, או `AutoFitToWindow`.

תצורת Excel (ExcelConfig)

פורמטים: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` רינדור גיליון מקורי; `false` משתמש בהפנייה ל-PDF.
`PdfConfig`	`PdfConfig`	new instance	הגדרות לנתיב PDF/חיפוש.
`ExcelPaperSize`	`PaperSize`	`PaperA4`	גודל נייר פלט.
`double`	`PaperMargins`	`0.25`	מרווחי עמוד באינצ'ים.
`bool`	`PaperLandscape`	`true`	רינדור גיליון במצב אופקי.
`bool`	`AutoFitContents`	`false`	התאמה אוטומטית של גובה השורות ורוחב העמודות.
`bool`	`RemoveEmptyContent`	`true`	הדק את הפלט על ידי הוצאת תוכן ריק.
`bool`	`CalculateFormula`	`true`	חשב מחדש נוסחאות לפני הרינדור.
`bool`	`ShowRowColumnHeaders`	`true`	כלול כותרות גיליון.
`bool`	`ExportPdfA`	`false`	השתמש ב-PDF/A בנתיב PDF.
`bool`	`SplitWorksheets`	`false`	שמור גיליונות כקבוצות עמודים נפרדות.
`bool`	`ShowEmptyWorkSheets`	`false`	כלול גיליונות ריקים.
`bool`	`ExportLandscape`	`false`	הכרח ייצוא במצב אופקי.
`bool`	`ExportOnePagePerSheet`	`false`	התאם כל גיליון לעמוד פלט אחד.
`bool`	`MemoryOptimizationPreference`	`true`	הפחת את השימוש בזיכרון השיא, ייתכן במחיר של מהירות.
`bool`	`AutoTrimWorksheetRenderRange`	`true`	רנדר רק את הטווח הנראה בשימוש כאשר אין אזור הדפסה מפורש.
`bool`	`AutoTrimPreserveExistingPrintArea`	`true`	שמור על אזורי הדפסה שהוגדרו בחוברת העבודה במהלך חיתוך אוטומטי.
`string?`	`PrintArea`	`null`	טווח מפורש כגון "A1:Z100".
`bool`	`PrintGridlines`	`false`	הדפס קווי רשת של הגיליון.
`bool`	`PrintHeadings`	`false`	הדפס כותרות שורה/עמודה.
`List<string>`	`SheetNames`	empty	הגבל רינדור לגיליונות עם שם.
`CustomStyleCell?`	`CustomStyles`	`null`	החלפות פורמט אופציונליות לתאריך/דצימלי/שלם.
`bool`	`AllowSearch`	`false`	מועבר ל-`PdfConfig.AllowSearch`.
`bool`	`AllowCopy`	`false`	מועבר ל-`PdfConfig.AllowCopy`.

CustomStyleCell מציג את CustomStyleDateTime, CustomStyleNumberDecimal, ו-CustomStyleNumberInteger, כולם מחרוזות ניתנות לאפס.

new ExcelConfig() מגדיר את SplitWorksheets ל-false; פתיחת קובץ Excel ללא קונפיגורציה מפורשת משתמשת בקטלוג הפורמט, שמגדיר זאת ל-true.

תצורת PPT (PptConfig)

פורמטים: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` רינדור שקופיות מקורי; `false` משתמש בהפנייה ל-PDF.
`bool`	`FastLoad`	`false`	`false` נמנע מרינדור השקופית הראשונה בזמן פתיחה; השתמש במטא-דטה ורנדר לפי דרישה.
`PdfConfig`	`PdfConfig`	new instance	הגדרות להתנהגות PDF/חיפוש.
`string`	`FontInfo`	`""`	מידע על החלפת גופנים.
`string[]?`	`FontFolders`	`null`	ספריות גופנים נוספות.
`bool`	`AllowSearch`	`false`	מועבר ל-`PdfConfig.AllowSearch`.
`bool`	`AllowCopy`	`false`	מועבר ל-`PdfConfig.AllowCopy`.

ב-Linux וב-macOS, רינדור מצגות עם המנוע הנוכחי דורש libgdiplus ו-System.Drawing.EnableUnixSupport=true. התקינו את הגופנים המשמשים במצגת או ספקו FontFolders.

תצורת CAD (CadConfig)

פורמטים: DWG, DXF, DGN. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` רינדור CAD מקורי; `false` משתמש בהפנייה ל-PDF.
`PdfConfig`	`PdfConfig`	new instance	הגדרות נתיב PDF.
`bool`	`ExportPdfA`	`false`	פלט PDF/A ארכיוני.
`bool`	`ShowColor`	`true`	צבע במקום מונוכרום.
`bool`	`WhiteBackground`	`true`	רקע לבן במקום שחור.
`short`	`LineWidth`	`25`	רוחב קו CAD.
`bool`	`ShowLayouts`	`false`	רנדר כרטיסיות פריסה.
`bool`	`ShowModel`	`true`	רנדר מרחב מודל.
`bool`	`Check3DSolid`	`true`	עיבוד מוצקים תלת-ממדיים.
`bool`	`ExportAllLayouts`	`false`	ייצא את כל הפריסות, מתעלם מבחירת מודל/פריסה.
`bool`	`LimitMinimumSize`	`false`	החל `MinimumSize`.
`int`	`MinimumSize`	`700`	גודל פלט מינימלי בפיקסלים.
`bool`	`LimitMaximumSize`	`false`	החל `MaximumSize`.
`int`	`MaximumSize`	`700`	גודל פלט מרבי בפיקסלים.
`bool`	`ShowAllLayoutsDgn`	`false`	כלול את כל פריסות DGN.
`bool`	`AutomaticLayoutScaling`	`true`	קנה מידה אוטומטי של פריסות.
`float`	`PdfMargins`	`0.5`	מרווח PDF באינצ'ים.
`RenderQuality`	`QualityImage`	`Low`	איכות רסטר: `Low`, `Medium`, או `High`.
`RenderQuality`	`QualityText`	`Medium`	איכות טקסט: `Low`, `Medium`, או `High`.

תצורת אימייל (EmailConfig)

פורמטים: EML, EMLX, MSG. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` רינדור אימייל מקורי; `false` משתמש בהפנייה ל-PDF.
`PdfConfig`	`PdfConfig`	new instance	הגדרות נתיב PDF.
`Encoding?`	`EmailEncoding`	`null`	דרוס קידוד הודעה.
`Encoding?`	`SubjectEncoding`	`null`	דרוס קידוד נושא.
`Encoding?`	`BodyEncoding`	`null`	דרוס קידוד גוף.
`bool`	`SkipExternalImages`	`false`	אל טען תמונות המופנות מרחוק. מומלץ עבור אימיילים לא מהימנים.
`bool`	`RemoveLastWhitePage`	`false`	הסר עמוד ריק סופי.
`bool`	`UseAntiAliasing`	`false`	הפעל אנטי-אליאסינג.
`bool`	`UseHighQualityRendering`	`false`	העדף רינדור נקי יותר אך איטי יותר.
`TimeSpan?`	`TimeZoneOffset`	`null`	דרוס את אזור הזמן המשמש לתאריכים.
`bool`	`ForcePageSize`	`false`	הכרח ממדי עמוד קבועים.

תצורות תמונה, Tiff ו‑PSD (ImageConfig, TiffConfig, and PsdConfig)

ImageConfig מכסה JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF, ו‑SVG. DPI ברירת המחדל שלו הוא 100.

קונפיג	מאפיין	ברירת מחדל	התנהגות
`ImageConfig`	`MaxImagePixelSize`	`3000`	רוחב/גובה מרבי. `0` משמעותו ללא הגבלה; ערכים שונים מ-0 מתחת ל-50 מתעלמים.
`ImageConfig`	`TransparentPng`	`true`	שומר על שקיפות PNG; `false` משתמש ברקע לבן.
`TiffConfig`	ללא מאפיינים נוספים	DPI `200`	משתמש רק ב-`BaseConfig`; תומך ב‑TIFF מרובה עמודים.
`PsdConfig`	`MaxImagePixelSize`	`3000`	אותה ולידציה של `0`/מינימום‑50 כמו ב‑`ImageConfig`; DPI ברירת מחדל הוא `100`.

תצורת DICOM (DicomConfig)

פורמטים: DCM, IMA. DPI אפקטיבי ברירת מחדל: 100. דורש את תוסף DICOM.

סוג	מאפיין	ברירת מחדל	התנהגות
`int`	`HorizontalResolution`	`100` אפקטיבי	DPI אופקי מפורש; אחרת `ImageResolution`, ואז 100.
`int`	`VerticalResolution`	`100` אפקטיבי	DPI אנכי מפורש; אחרת `ImageResolution`, ואז 100.
`int`	`AnimationFrameDelayMs`	`100`	השהייה של אנימציית מרובה‑פריימים; תזמון GIF משתמש ביחידות של 10 מ״ש.
`ushort`	`LoopCount`	`0`	`0` לולאה לנצח; ערכים חיוביים עוצרים אחרי ספירה זו.
`DicomDisplayMode`	`DisplayMode`	`AnimationAndFrames`	`AnimationOnly`, `FramesOnly`, או תצוגה משולבת עם פריימים סטטיים.

תצורת TXT (TxtConfig)

פורמט: TXT. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`DocPaperSize`	`PaperSize`	`A4`	גודל נייר פלט.
`Encoding?`	`FileEncoding`	`null`	`null` משתמש ב‑UTF-8.
`string`	`FontInformation`	`""`	מידע על גופנים עבור רינדור טקסט.

השתמש ב‑WordConfig כאשר טקסט פשוט דורש התנהגות פריסת עמודים עשירה יותר.

תצורת פרויקט (ProjectConfig)

פורמטים: MPP, MPPX, MPX. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` תמונת Gantt מקורית; `false` משתמש בנתיב PDF מבוסס טקסט.
`PdfConfig`	`PdfConfig`	new instance	הגדרות נתיב PDF.
`bool`	`ExportPdfA`	`true`	`true` פלט PDF/A ארכיוני.
`MppPaperSize`	`PaperSize`	`Ledger`	גודל נייר פלט של הפרויקט.
`MppTimeScale`	`TimeScale`	`Months`	`Days` או `Months`.
`MppFormat`	`PresentationFormat`	`GanttChart`	`GanttChart`, `TaskUsage`, `ResourceUsage`, `ResourceSheet`, או `TaskSheet`.

לחיפוש מדויק לפי קואורדינטות טקסט, השתמש ב‑DefaultRender = false.

תצורת Visio (VisioConfig)

פורמטים: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. DPI ברירת מחדל: 200.

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	`true` רינדור דיאגרמה מקורי; `false` משתמש בהפנייה ל-PDF.
`PdfConfig`	`PdfConfig`	new instance	הגדרות נתיב PDF.
`bool`	`ExportPdfA`	`true`	`true` פלט PDF/A ארכיוני.

תצורות HTML, EPUB, MHT ו‑XPS (HtmlConfig, EpubConfig, MhtConfig, and XpsConfig)

כל הארבעה משתמשים ב‑DPI של 200 ומציגים PdfConfig מקונן.

קונפיג	פורמטים	`DefaultRender`	מאפיינים/התנהגות נוספים
`HtmlConfig`	HTML, HTM	`true`	רינדור מקורי; השתמש ב‑`false` לנתיב חיפוש PDF מבוסס טקסט.
`EpubConfig`	EPUB	`true`	רינדור מקורי; `false` משתמש ב‑PDF.
`MhtConfig`	MHT, MHTML	`true` במחלקה; `false` בקטלוג האוטומטי	הפתיחה הרגילה ללא קונפיג משתמשת בהפנייה ל‑PDF חיפושית. מופע ברירת מחדל שנבנה במפורש רונדר באופן מקורי.
`XpsConfig`	XPS	`false`	משתמש בנתיב PDF כברירת מחדל; קבע `true` לרינדור תמונה מקורי.

דוגמאות קונפיגורציה לפי משפחה

csharp

BaseConfig[] configs =
[
    new PdfConfig
    {
        AllowSearch = true,
        ExtractHyperlinks = true,
        HyperlinksPageCount = 0
    },
    new WordConfig
    {
        PaperSize = DocPaperSize.A4,
        RemovePaperMargin = false,
        FontFolders = ["/usr/share/fonts/truetype"],
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = ["/usr/share/fonts/truetype"],
        AllowSearch = true
    },
    new CadConfig
    {
        ShowColor = true,
        WhiteBackground = true,
        ShowModel = true,
        ShowLayouts = false,
        QualityText = CadConfig.RenderQuality.High
    },
    new EmailConfig
    {
        SkipExternalImages = true,
        RemoveLastWhitePage = true,
        TimeZoneOffset = TimeSpan.Zero
    },
    new ImageConfig
    {
        MaxImagePixelSize = 3000,
        TransparentPng = true
    },
    new DicomConfig
    {
        DisplayMode = DicomDisplayMode.AnimationAndFrames,
        AnimationFrameDelayMs = 100,
        LoopCount = 0
    }
];

בחירת קונפיגורציה לפי סיומת

csharp

static BaseConfig? ConfigForExtension(string extUpper) => extUpper switch
{
    ".DOC" or ".DOCX" or ".DOT" or ".DOTX" or ".ODT" => new WordConfig
    {
        AutoFitAllTables = WordConfig.TableAutoFitBehavior.AutoFitToWindow,
        PaperSize = DocPaperSize.Tabloid,
        PdfConfig = new PdfConfig { ExtractHyperlinks = true, HyperlinksPageCount = 5, AllowCopy = true }
    },
    ".PDF" => new PdfConfig { AllowSearch = true, AllowCopy = true },
    ".XLS" or ".XLSX" or ".ODS" or ".CSV" => new ExcelConfig { AllowSearch = true, AllowCopy = true },
    ".DCM" or ".IMA" => new DicomConfig { DisplayMode = DicomDisplayMode.AnimationAndFrames },
    // DefaultRender = false → PDF redirect → pixel-accurate native text search
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // fall back to the format's default config
};