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. 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 wygodnymi, 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. Ważny zakres explicite 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ślneZachowanie
boolDefaultRendertruePrzełącznik kompatybilności. Bieżąca fabryka używa natywnej przeglądarki PDF.
boolAllowSearchfalseBuduj/używaj indeksu wyszukiwania tekstu w PDF. Wymaga możliwości licencyjnej 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 wszystkie strony.
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, natomiast ExtractHyperlinks kontroluje ekstrakcję 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.
PdfConfigPdfConfignew instanceUstawienia 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 stron 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/kontenerach.
boolAllowSearchfalseDeleguje do PdfConfig.AllowSearch.
boolAllowCopyfalseDeleguje do PdfConfig.AllowCopy.
TableAutoFitBehaviorAutoFitAllTablesNoneNone, AutoFitToContents lub AutoFitToWindow.

ExcelConfig

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 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 kalkulacyjnego.
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 widzialnego 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 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 ciągi znaków dopuszczające wartość null.

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

PptConfig

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ż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 wskaż FontFolders na nie: brakująca czcionka jest podstawiana bez błędu, więc podziały linii mogą różnić się od Windows. fonts-liberation, fonts-crosextra-carlito i fonts-crosextra-caladea zapewniają zamienniki metryczne kompatybilne z powszechnymi czcionkami Windows. Linux potrzebuje tylko libfontconfig1 (libgdiplus nie jest wymagane).

CadConfig

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.
boolExportPdfAfalseArchiwalne wyjście PDF/A.
boolShowColortrueKolor zamiast czerni i bieli.
boolWhiteBackgroundtrueBiałe tło zamiast czarnego.
shortLineWidth25Szerokość linii 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.

KonfiguracjaEmail

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.

KonfiguracjaObrazu, KonfiguracjaTiff i KonfiguracjaPsd

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; wartości niezerowe 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ślne DPI to 100.

KonfiguracjaDicom

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

TypWłaściwośćDomyślnieZachowanie
intHorizontalResolution100 skuteczneJawne poziome DPI; w przeciwnym razie ImageResolution, potem 100.
intVerticalResolution100 skuteczneJawne pionowe DPI; w przeciwnym razie ImageResolution, potem 100.
intAnimationFrameDelayMs100Opóźnienie animacji wieloklatkowej; czas GIF używa jednostek 10 ms.
ushortLoopCount00 pętli w nieskończoność; dodatnie wartości zatrzymują po podanej liczbie powtórzeń.
DicomDisplayModeDisplayModeAnimationAndFramesAnimationOnly, FramesOnly lub połączony podgląd z klatkami statycznymi.

KonfiguracjaTxt

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 zaawansowanego układu strony.

KonfiguracjaProjektu

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 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.

KonfiguracjaVisio

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 wyjściowy PDF/A.

KonfiguracjaHtml, KonfiguracjaEpub, KonfiguracjaMht i KonfiguracjaXps

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 jako tekstowej ścieżki wyszukiwania PDF.
EpubConfigEPUBtrueNatywne renderowanie; false używa PDF.
MhtConfigMHT, MHTMLtrue w klasie; false w automatycznym kataloguStandardowe 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[] { "/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
    }
};

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

Czy ta strona była pomocna?