Konfiguracje Formatów

Pełne opcje renderowania dla każdego formatu

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

Ta pojedyncza przestrzeń nazw jest nowa. Poprzednia biblioteka .NET Standard rozkładała te typy na Doconut.Configs, Doconut.Configs.View i Doconut.Models. Nazwy typów nie uległy zmianie — w większości plików cała zmiana polega na usunięciu dwóch linii using. Zobacz przewodnik migracji.

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. Formaty, które mogą przekierowywać przez PDF, udostępniają 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ślneZachowanie
intImageResolution00 używa domyślnego formatu. Poprawny zakres jawny to 25‑300 DPI; nieprawidłowe przypisania są ignorowane.
stringDocumentCulture""Lokalizacja 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 sterowania paskiem narzędzi przeglądarki.
boolCachePagestrueBuforuj renderowane obrazy stron dla sesji dokumentu.

PdfConfig

Formaty: PDF. Domyślne DPI: 200.

TypWłaściwośćDomyślneZachowanie
boolDefaultRendertruePrzełącznik kompatybilności. Bieżąca fabryka używa natywnej przeglądarki PDF.
boolAllowSearchfalseBuduj/używaj indeksu wyszukiwania tekstu PDF. Wymaga 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ślneZachowanie
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ła.
stringFontInfo""Informacje o podstawianiu czcionek.
string[]?FontFoldersnullDodatkowe katalogi czcionek — przydatne na serwerze, który nie posiada czcionek używanych w dokumentach.
boolAllowSearchfalseDeleguje do PdfConfig.AllowSearch.
boolAllowCopyfalseDeleguje do PdfConfig.AllowCopy.
TableAutoFitBehaviorAutoFitAllTablesNoneNone, AutoFitToContents, lub AutoFitToWindow.

Konfiguracja Excel

Formaty: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. Domyślne 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 trybie poziomym.
boolAutoFitContentsfalseAutomatyczne dopasowanie wysokości wierszy i szerokości kolumn.
boolRemoveEmptyContenttrueZacieśnianie wyjścia poprzez wykluczenie pustej zawartości.
boolCalculateFormulatruePrzeliczenie formuł przed renderowaniem.
boolShowRowColumnHeaderstrueDołączanie nagłówków arkusza kalkulacyjnego.
boolExportPdfAfalseUżycie PDF/A w ścieżce PDF.
boolSplitWorksheetsfalseZachowanie arkuszy jako oddzielnych grup stron.
boolShowEmptyWorkSheetsfalseDołączanie pustych arkuszy.
boolExportLandscapefalseWymuszenie eksportu w trybie poziomym.
boolExportOnePagePerSheetfalseDopasowanie każdego arkusza do jednej strony wyjściowej.
boolMemoryOptimizationPreferencetrueRedukcja maksymalnego zużycia pamięci, potencjalnie kosztem nieco większej prędkości.
boolAutoTrimWorksheetRenderRangetrueRenderowanie tylko widocznego używanego zakresu, gdy nie istnieje wyraźny obszar drukowania.
boolAutoTrimPreserveExistingPrintAreatrueZachowanie obszarów drukowania 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>SheetNamespustyOgraniczenie renderowania do nazwanych arkuszy.
CustomStyleCell?CustomStylesnullOpcjonalne nadpisania formatowania daty/liczb dziesiętnych/liczb całkowitych.
boolAllowSearchfalseDeleguje do PdfConfig.AllowSearch.
boolAllowCopyfalseDeleguje do PdfConfig.AllowCopy.

CustomStyleCell udostępnia CustomStyleDateTime, CustomStyleNumberDecimal i CustomStyleNumberInteger, wszystkie jako nullable strings.

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

Konfiguracja PPT

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

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

Zainstaluj czcionki używane przez prezentacje na serwerze lub wskaż FontFolders na folder, który je zawiera. Brakujące czcionki są podstawiane bez żadnego błędu.

Konfiguracja CAD

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

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywne renderowanie CAD; false używa przekierowania PDF.
PdfConfigPdfConfignowa instancjaUstawienia ścieżki PDF.
boolExportPdfAfalseArchiwalny wynik PDF/A.
boolShowColortrueKolor zamiast czerni i bieli.
boolWhiteBackgroundtrueBiałe zamiast czarnego tła.
shortLineWidth25Szerokość linii CAD.
boolShowLayoutsfalseRenderowanie zakładek układu.
boolShowModeltrueRenderowanie przestrzeni modelu.
boolCheck3DSolidtruePrzetwarzanie brył 3D.
boolExportAllLayoutsfalseEksport wszystkich układów, nadpisując wybór modelu/układu.
boolLimitMinimumSizefalseZastosuj MinimumSize.
intMinimumSize700Minimalny rozmiar wyjścia w pikselach.
boolLimitMaximumSizefalseZastosuj MaximumSize.
intMaximumSize700Maksymalny rozmiar wyjścia w pikselach.
boolShowAllLayoutsDgnfalseDołącz wszystkie układy 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ślne 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 obsługuje JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF i SVG. Jego domyślne 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.
PsdConfigMaxImagePixelSize3000To samo sprawdzanie 0/minimum-50 co ImageConfig; domyślne DPI to 100.

DicomConfig

Formaty: DCM, IMA. Domyślne skuteczne DPI: 100. Wymaga wtyczki DICOM. W tym pakiecie pliki DICOM renderują się w pełni, ale metadane techniczne nie są dostępne — zobacz Wtyczka DICOM.

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

TxtConfig

Format: TXT. Domyślne 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 układu strony.

ProjectConfig

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

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywny obraz Gantt; false używa tekstowej ścieżki PDF.
PdfConfigPdfConfignowa instancjaustawienia ścieżki PDF.
boolExportPdfAtrueArchiwalny output 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ślne DPI: 200.

TypWłaściwośćDomyślnieZachowanie
boolDefaultRendertrueNatywne renderowanie diagramu; false używa przekierowania PDF.
PdfConfigPdfConfignowa instancjaustawienia ścieżki PDF.
boolExportPdfAtrueArchiwalny output 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 przeszukiwalnego przekierowania PDF. Jawnie skonstruowana domyślna instancja renderuje natywnie.
XpsConfigXPSfalseDomyślnie używa ś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 = new[] { Path.Combine(AppContext.BaseDirectory, "Fonts") },
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = new[] { Path.Combine(AppContext.BaseDirectory, "Fonts") },
        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 według rozszerzenia

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 → wyszukiwanie tekstu natywne z dokładnością do piksela
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // wrócić do domyślnej konfiguracji formatu
};

Czy ta strona była pomocna?