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

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

מרחב שם יחיד זה הוא חדש. ספריית .NET Standard הקודמת פיזרה סוגים אלה על פני Doconut.Configs, Doconut.Configs.View, ו-Doconut.Models. השמות הסוגים לא השתנו — ברוב הקבצים השינוי כולו הוא מחיקת שתי שורות using. ראה את מדריך ההגירה.

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`	מאפיין תאימות; המעבד הנוכחי אינו משתמש בו לשליטה בסרגל הכלים של הדפדפן.
`bool`	`CachePages`	`true`	שמור במטמון תמונות דפים מרונדרים עבור סשן המסמך.

PdfConfig

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

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

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

WordConfig

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

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`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`.

ExcelConfig

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

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`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`	ריק	הגבלת הרינדור לגיליונות בעלי שם.
`CustomStyleCell?`	`CustomStyles`	`null`	החלפות פורמט אופציונליות לתאריכים/דצימלים/שלמים.
`bool`	`AllowSearch`	`false`	מעביר ל‑`PdfConfig.AllowSearch`.
`bool`	`AllowCopy`	`false`	מעביר ל‑`PdfConfig.AllowCopy`.

CustomStyleCell חושף את CustomStyleDateTime, CustomStyleNumberDecimal ו‑CustomStyleNumberInteger, כולם מחרוזות ניתנות לאפס.

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

PptConfig

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

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`true`	רינדור שקף מקורי; `false` משתמש בהפנייה ל‑PDF.
`bool`	`FastLoad`	`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.

CadConfig

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

סוג	מאפיין	ברירת מחדל	התנהגות
`bool`	`DefaultRender`	`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`	רינדור מקורי של אימייל; `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`	הכרח ממדים קבועים לדף.

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

DicomConfig

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

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

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

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

VisioConfig

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

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

HtmlConfig, EpubConfig, MhtConfig, ו‑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 = new[] { "/usr/share/fonts/truetype" },
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = new[] { "/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
};