Konfiguracje formatów

Pełne opcje renderowania dla każdego formatu

Każdy dokument otwiera się z implementacją BaseConfig. Przekaż ją do OpenDocumentAsync lub pozwól katalogowi formatów utworzyć domyślną. Wszystkie klasy poniżej znajdują się w przestrzeni nazw Doconut.

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

Dziedziczenie i zagnieżdżone ustawienia PDF

Każdy format dziedziczy pięć właściwości BaseConfig. Formatom, które mogą przekierowywać przez PDF, udostępniany jest zagnieżdżony PdfConfig. W WordConfig, ExcelConfig i PptConfig, AllowSearch oraz AllowCopy są właściwościami ułatwiającymi, które odczytują i zapisują zagnieżdżony PdfConfig.

DefaultRender = true wybiera natywny renderer formatu. W formatach z przekierowaniem PDF, false najpierw konwertuje do PDF w pamięci, a następnie używa przeglądarki PDF. Ta ścieżka jest często przydatna do wyszukiwania po współrzędnych tekstu, ale wymaga dodatkowej konwersji.

O ile nie zaznaczono inaczej, tabele pokazują domyślne wartości konstruktorów/właściwości. Automatyczny katalog formatów celowo nadpisuje dwie z nich: tworzy ExcelConfig z SplitWorksheets = true oraz MhtConfig z DefaultRender = false.

BaseConfig

TypWłaściwośćDomyślnaZachowanie
intImageResolution00 używa domyślnego formatu. Prawidłowy zakres wyraźny to 25‑300 DPI; nieprawidłowe przypisania są ignorowane.
stringDocumentCulture""Ustawienia regionalne dla dat i liczb. Niepuste wartości są przycinane; puste przypisania są ignorowane.
stringPassword""Hasło dokumentu chronionego. DocOptions.Password jest tutaj kopiowane automatycznie.
boolShowUItrueWłaściwość kompatybilności; bieżący renderer nie używa jej do kontrolowania paska narzędzi przeglądarki.
boolCachePagestrueBuforuj renderowane obrazy stron dla sesji dokumentu.

PdfConfig

Formaty: PDF. Domyślne DPI: 200.

TypWłaściwośćDomyślnaZachowanie
boolDefaultRendertruePrzełącznik kompatybilności. Bieżąca fabryka używa natywnej przeglądarki PDF.
boolAllowSearchfalseBuduj/używaj indeksu wyszukiwania tekstu w PDF. Wymaga uprawnienia licencji Search dla żądań.
boolAllowCopyfalseZezwalaj na operacje zaznaczania/kopiowania tekstu.
boolExtractHyperlinksfalseWyodrębniaj prostokąty linków dla nakładek klienta.
intHyperlinksPageCount0Maksymalna liczba stron skanowanych pod kątem linków; 0 oznacza każdą stronę.
boolCompressImagesfalseKompresuj osadzone obrazy przed renderowaniem.
intCompressQuality100Jakość JPEG używana, gdy włączona jest kompresja.
boolResizeImagesfalseZmieniaj rozmiar osadzonych obrazów przed renderowaniem.
intResizeResolution300Docelowe DPI dla zmienionych rozmiarów obrazów.
boolCompressFastfalsePreferuj szybszą, niższej jakości ścieżkę kompresji.
boolFixInvalidImagesfalsePróbuj naprawić nieprawidłowe osadzone obrazy.
boolSplitSegmentsfalseŁącz ponownie słowa podzielone na segmenty linii, aby poprawić wyszukiwanie/kopiowanie.

showHyperlinks w ViewerConfig kontroluje nakładkę klienta, podczas gdy ExtractHyperlinks kontroluje wyodrębnianie po stronie serwera. Włącz oba.

WordConfig

Formaty: DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, XML. Domyślne DPI: 200.

TypWłaściwośćDomyślnaZachowanie
boolDefaultRendertrueNatywne renderowanie Word; false używa przekierowania PDF.
PdfConfigPdfConfignowa instancjaUstawienia używane przez ścieżkę PDF/wyszukiwania.
DocPaperSizePaperSizeA4Rozmiar papieru wyjściowego. Użyj Custom z szerokością/wysokością.
intPaperWidth595Niestandardowa szerokość w punktach.
intPaperHeight841Niestandardowa wysokość w punktach.
boolRemovePaperMarginfalseUsuń marginesy stron dokumentu.
boolRenderPageColortrueZachowaj skonfigurowany kolor strony w Word; false renderuje białe strony.
boolExportPdfAfalseUżyj archiwalnego PDF/A w ścieżce PDF.
Encoding?FileEncodingnullZastąp kodowanie źródłowe.
stringFontInfo""Informacje o podstawianiu czcionek.
string[]?FontFoldersnullDodatkowe katalogi czcionek, szczególnie przydatne w Linux/containers.
boolAllowSearchfalseDeleguje do PdfConfig.AllowSearch.
boolAllowCopyfalseDeleguje do PdfConfig.AllowCopy.
TableAutoFitBehaviorAutoFitAllTablesNoneNone, AutoFitToContents lub AutoFitToWindow.

ExcelConfig

Formaty: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. Domyślna DPI: 200.

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywne renderowanie arkusza; false używa przekierowania PDF.
PdfConfigPdfConfignowa instancjaUstawienia ścieżki PDF/wyszukiwania.
ExcelPaperSizePaperSizePaperA4Rozmiar papieru wyjściowego.
doublePaperMargins0.25Marginesy strony w calach.
boolPaperLandscapetrueRenderowanie arkusza w orientacji poziomej.
boolAutoFitContentsfalseAutomatyczne dopasowanie wysokości wierszy i szerokości kolumn.
boolRemoveEmptyContenttrueZacieśnianie wyjścia przez wykluczenie pustej zawartości.
boolCalculateFormulatruePrzeliczenie formuł przed renderowaniem.
boolShowRowColumnHeaderstrueDołączenie nagłówków arkusza.
boolExportPdfAfalseUżycie PDF/A na ścieżce PDF.
boolSplitWorksheetsfalseZachowanie arkuszy jako oddzielnych grup stron.
boolShowEmptyWorkSheetsfalseDołączenie pustych arkuszy.
boolExportLandscapefalseWymuszenie eksportu w orientacji poziomej.
boolExportOnePagePerSheetfalseDopasowanie każdego arkusza do jednej strony wyjściowej.
boolMemoryOptimizationPreferencetrueRedukcja szczytowego zużycia pamięci, potencjalnie kosztem nieco większej prędkości.
boolAutoTrimWorksheetRenderRangetrueRenderowanie tylko widocznego używanego zakresu, gdy nie istnieje wyraźny obszar wydruku.
boolAutoTrimPreserveExistingPrintAreatrueZachowanie obszarów wydruku zdefiniowanych w skoroszycie podczas automatycznego przycinania.
string?PrintAreanullWyraźny zakres, taki jak "A1:Z100".
boolPrintGridlinesfalseDrukowanie linii siatki arkusza.
boolPrintHeadingsfalseDrukowanie nagłówków wierszy/kolumn.
List<string>SheetNamespusteOgraniczenie renderowania do nazwanych arkuszy.
CustomStyleCell?CustomStylesnullOpcjonalne nadpisania formatowania daty/liczby dziesiętnej/liczby całkowitej.
boolAllowSearchfalseDeleguje do PdfConfig.AllowSearch.
boolAllowCopyfalseDeleguje do PdfConfig.AllowCopy.

CustomStyleCell udostępnia CustomStyleDateTime, CustomStyleNumberDecimal i CustomStyleNumberInteger, wszystkie jako łańcuchy dopuszczalne do wartości null.

new ExcelConfig() ustawia SplitWorksheets na false; otwarcie pliku Excel bez wyraźnej konfiguracji używa katalogu formatów, który ustawia to na true.

PptConfig

Formaty: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. Domyślna DPI: 200.

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywne renderowanie slajdu; false używa przekierowania PDF.
boolFastLoadfalseUnikanie renderowania pierwszego slajdu podczas otwierania; użycie metadanych i renderowanie na żądanie.
PdfConfigPdfConfignowa instancjaUstawienia zachowania PDF/wyszukiwania.
stringFontInfo""Informacje o podstawianiu czcionek.
string[]?FontFoldersnullDodatkowe katalogi czcionek.
boolAllowSearchfalseDeleguje do PdfConfig.AllowSearch.
boolAllowCopyfalseDeleguje do PdfConfig.AllowCopy.

Strony są rysowane czcionkami zainstalowanymi na serwerze. W systemie Linux zainstaluj czcionki używane w prezentacjach lub skieruj FontFolders do nich: brakująca czcionka jest zastępowana bez błędu, więc podziały linii mogą różnić się od Windows. fonts-liberation, fonts-crosextra-carlito i fonts-crosextra-caladea dostarczają zamienniki o zgodnych metrykach dla typowych czcionek Windows. Linux potrzebuje tylko libfontconfig1 (libgdiplus nie jest wymagany).

CadConfig

Formaty: DWG, DXF, DGN. Domyślna DPI: 200.

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywne renderowanie CAD; false używa przekierowania PDF.
PdfConfigPdfConfignowa instancjaUstawienia ścieżki PDF.
boolExportPdfAfalseArchiwalny wyjściowy PDF/A.
boolShowColortrueKolor zamiast monochromu.
boolWhiteBackgroundtrueBiałe tło zamiast czarnego.
shortLineWidth25Szerokość kreski CAD.
boolShowLayoutsfalseRenderowanie zakładek układu.
boolShowModeltrueRenderowanie przestrzeni modelu.
boolCheck3DSolidtruePrzetwarzanie brył 3D.
boolExportAllLayoutsfalseEksport wszystkich układów, nadpisując wybór model/układ.
boolLimitMinimumSizefalseZastosowanie MinimumSize.
intMinimumSize700Minimalny rozmiar wyjścia w pikselach.
boolLimitMaximumSizefalseZastosowanie MaximumSize.
intMaximumSize700Maksymalny rozmiar wyjścia w pikselach.
boolShowAllLayoutsDgnfalseDołączenie wszystkich układów DGN.
boolAutomaticLayoutScalingtrueAutomatyczne skalowanie układów.
floatPdfMargins0.5Margines PDF w calach.
RenderQualityQualityImageLowJakość rastra: Low, Medium lub High.
RenderQualityQualityTextMediumJakość tekstu: Low, Medium lub High.

EmailConfig

Formaty: EML, EMLX, MSG. Domyślna DPI: 200.

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywne renderowanie e‑mail; false używa przekierowania PDF.
PdfConfigPdfConfignowa instancjaUstawienia ścieżki PDF.
Encoding?EmailEncodingnullZastąp kodowanie wiadomości.
Encoding?SubjectEncodingnullZastąp kodowanie tematu.
Encoding?BodyEncodingnullZastąp kodowanie treści.
boolSkipExternalImagesfalseNie ładuj zdalnie odwoływanych obrazów. Zalecane dla niepewnych e‑maili.
boolRemoveLastWhitePagefalseUsuń końcową pustą stronę.
boolUseAntiAliasingfalseWłącz antyaliasing.
boolUseHighQualityRenderingfalsePreferuj czystsze, wolniejsze renderowanie.
TimeSpan?TimeZoneOffsetnullZastąp strefę czasową używaną dla dat.
boolForcePageSizefalseWymuś stałe wymiary strony.

ImageConfig, TiffConfig i PsdConfig

ImageConfig obejmuje JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF i SVG. Jego domyślna DPI to 100.

KonfiguracjaWłaściwośćDomyślnieZachowanie
ImageConfigMaxImagePixelSize3000Maksymalna szerokość/wysokość. 0 oznacza nieograniczone; niezerowe wartości poniżej 50 są ignorowane.
ImageConfigTransparentPngtrueZachowaj przeźroczystość PNG; false używa białego tła.
TiffConfigbrak dodatkowych właściwościDPI 200Używa tylko BaseConfig; obsługuje wielostronicowy TIFF.
PsdConfigMaxImagePixelSize3000Ta sama walidacja 0/minimum-50 co ImageConfig; domyślna DPI to 100.

DicomConfig

Formaty: DCM, IMA. Domyślna efektywna DPI: 100. Wymaga wtyczki DICOM.

TypWłaściwośćDomyślnieZachowanie
intHorizontalResolution100 efektywnaJawna pozioma DPI; w przeciwnym razie ImageResolution, potem 100.
intVerticalResolution100 efektywnaJawna pionowa DPI; w przeciwnym razie ImageResolution, potem 100.
intAnimationFrameDelayMs100Opóźnienie animacji wieloklatkowej; czasowanie GIF używa jednostek 10 ms.
ushortLoopCount00 pętli w nieskończoność; dodatnie wartości zatrzymują po tej liczbie.
DicomDisplayModeDisplayModeAnimationAndFramesAnimationOnly, FramesOnly, lub połączony przegląd plus statyczne klatki.

TxtConfig

Format: TXT. Domyślna DPI: 200.

TypWłaściwośćDomyślnieZachowanie
DocPaperSizePaperSizeA4Rozmiar papieru wyjściowego.
Encoding?FileEncodingnullnull używa UTF-8.
stringFontInformation""Informacje o czcionce dla renderowania tekstu.

Użyj WordConfig, gdy zwykły tekst wymaga bardziej rozbudowanego zachowania układu strony.

ProjectConfig

Formaty: MPP, MPPX, MPX. Domyślna DPI: 200.

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywny obraz Gantt; false używa tekstowej ścieżki PDF.
PdfConfigPdfConfignowa instancjaUstawienia ścieżki PDF.
boolExportPdfAtrueArchiwalny wyjściowy PDF/A.
MppPaperSizePaperSizeLedgerRozmiar papieru wyjściowego projektu.
MppTimeScaleTimeScaleMonthsDays lub Months.
MppFormatPresentationFormatGanttChartGanttChart, TaskUsage, ResourceUsage, ResourceSheet, lub TaskSheet.

Do dokładnego wyszukiwania po współrzędnych tekstu użyj DefaultRender = false.

VisioConfig

Formaty: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. Domyślna DPI: 200.

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywne renderowanie diagramu; false używa przekierowania PDF.
PdfConfigPdfConfignowa instancjaUstawienia ścieżki PDF.
boolExportPdfAtrueArchiwalny wyjściowy PDF/A.

HtmlConfig, EpubConfig, MhtConfig i XpsConfig

Wszystkie cztery domyślnie mają 200 DPI i udostępniają zagnieżdżony PdfConfig.

KonfiguracjaFormatyDefaultRenderDodatkowe właściwości/zachowanie
HtmlConfigHTML, HTMtrueNatywne renderowanie; użyj false dla tekstowej ścieżki wyszukiwania PDF.
EpubConfigEPUBtrueNatywne renderowanie; false używa PDF.
MhtConfigMHT, MHTMLtrue w klasie; false w automatycznym kataloguNormalne otwarcie bez konfiguracji używa przekierowania PDF z możliwością wyszukiwania. Jawnie skonstruowana domyślna instancja renderuje natywnie.
XpsConfigXPSfalseUżywa domyślnie ścieżki PDF; ustaw true dla natywnego renderowania obrazu.

Przykłady konfiguracji według rodziny

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

Wybór per-rozszerzenie

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 przekierowanie → dokładne do piksela natywne wyszukiwanie tekstu
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // przywróć domyślną konfigurację formatu
};

Czy ta strona była pomocna?