Конфигурации форматов

Полные параметры рендеринга для каждого формата

Каждый документ открывается с реализацией 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

ТипСвойствоПо умолчаниюПоведение
intImageResolution00 использует значение формата по умолчанию. Допустимый явный диапазон — 25‑300 DPI; недопустимые назначения игнорируются.
stringDocumentCulture""Локаль для дат и чисел. Непустые значения обрезаются; пустые назначения игнорируются.
stringPassword""Пароль защищённого документа. DocOptions.Password копируется сюда автоматически.
boolShowUItrueСвойство совместимости; текущий рендерер не использует его для управления панелью браузера.
boolCachePagestrueКешировать отрисованные изображения страниц в течение сессии документа.

PdfConfig

Форматы: PDF. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueПереключатель совместимости. Текущая фабрика использует нативный просмотрщик PDF.
boolAllowSearchfalseСоздавать/использовать индекс текстового поиска PDF. Требует наличие лицензии Search для запросов.
boolAllowCopyfalseРазрешить операции выбора/копирования текста.
boolExtractHyperlinksfalseИзвлекать прямоугольники ссылок для клиентских наложений.
intHyperlinksPageCount0Максимальное количество страниц, сканируемых для ссылок; 0 означает каждую страницу.
boolCompressImagesfalseСжимать встроенные изображения перед отрисовкой.
intCompressQuality100Качество JPEG, используемое при включённом сжатии.
boolResizeImagesfalseИзменять размер встроенных изображений перед отрисовкой.
intResizeResolution300Целевое DPI для изменённых изображений.
boolCompressFastfalseПредпочитать более быстрый путь сжатия более низкого качества.
boolFixInvalidImagesfalseПытаться восстановить недействительные встроенные изображения.
boolSplitSegmentsfalseОбъединять слова, разбитые по сегментам строк, для улучшения поиска/копирования.

showHyperlinks в ViewerConfig управляет клиентским наложением, тогда как ExtractHyperlinks управляет серверным извлечением. Включите оба.

WordConfig

Форматы: DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, XML. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueНативный рендер Word; false использует перенаправление в PDF.
PdfConfigPdfConfignew instanceНастройки, используемые путём PDF/поиска.
DocPaperSizePaperSizeA4Размер выходного листа. Используйте Custom с шириной/высотой.
intPaperWidth595Пользовательская ширина в пунктах.
intPaperHeight841Пользовательская высота в пунктах.
boolRemovePaperMarginfalseУдалить поля страниц документа.
boolRenderPageColortrueСохранять настроенный цвет страниц Word; false отрисовывает белые страницы.
boolExportPdfAfalseИспользовать архивный PDF/A в пути PDF.
Encoding?FileEncodingnullПереопределить кодировку источника.
stringFontInfo""Информация о замене шрифтов.
string[]?FontFoldersnullДополнительные каталоги шрифтов — полезно на сервере, где отсутствуют шрифты, используемые документами.
boolAllowSearchfalseДелегирует PdfConfig.AllowSearch.
boolAllowCopyfalseДелегирует PdfConfig.AllowCopy.
TableAutoFitBehaviorAutoFitAllTablesNoneNone, AutoFitToContents или AutoFitToWindow.

Конфигурация Excel

Форматы: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueРендер листа нативно; false использует перенаправление PDF.
PdfConfigPdfConfigновый экземплярНастройки пути PDF/поиска.
ExcelPaperSizePaperSizePaperA4Размер выходного листа.
doublePaperMargins0.25Поля страницы в дюймах.
boolPaperLandscapetrueРендер листа в альбомной ориентации.
boolAutoFitContentsfalseАвтоматическая подгонка высот строк и ширин столбцов.
boolRemoveEmptyContenttrueУменьшить вывод, исключая пустой контент.
boolCalculateFormulatrueПересчитать формулы перед рендерингом.
boolShowRowColumnHeaderstrueВключать заголовки таблицы.
boolExportPdfAfalseИспользовать PDF/A в пути PDF.
boolSplitWorksheetsfalseСохранять листы как отдельные группы страниц.
boolShowEmptyWorkSheetsfalseВключать пустые листы.
boolExportLandscapefalseПринудительный экспорт в альбомной ориентации.
boolExportOnePagePerSheetfalseПодгонять каждый лист к одной странице вывода.
boolMemoryOptimizationPreferencetrueСократить пиковую память, возможно ценой скорости.
boolAutoTrimWorksheetRenderRangetrueРендерить только видимый используемый диапазон, если нет явно заданной области печати.
boolAutoTrimPreserveExistingPrintAreatrueСохранять области печати, определённые в книге, при автообрезке.
string?PrintAreanullЯвный диапазон, например "A1:Z100".
boolPrintGridlinesfalseПечатать линии сетки листа.
boolPrintHeadingsfalseПечатать заголовки строк/столбцов.
List<string>SheetNamesпустоОграничить рендеринг именованными листами.
CustomStyleCell?CustomStylesnullНеобязательные переопределения формата даты/десятичных/целых чисел.
boolAllowSearchfalseПеренаправляется к PdfConfig.AllowSearch.
boolAllowCopyfalseПеренаправляется к PdfConfig.AllowCopy.

CustomStyleCell раскрывает CustomStyleDateTime, CustomStyleNumberDecimal и CustomStyleNumberInteger, все строки, допускающие null.

new ExcelConfig() устанавливает SplitWorksheets в false; открытие Excel‑файла без явной конфигурации использует каталог форматов, который устанавливает его в true.

Конфигурация PPT

Форматы: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueРендер слайда нативно; false использует перенаправление PDF.
boolFastLoadfalseИзбегать рендеринга первого слайда при открытии; использовать метаданные и рендерить по запросу.
PdfConfigPdfConfigновый экземплярНастройки поведения PDF/поиска.
stringFontInfo""Информация о замене шрифтов.
string[]?FontFoldersnullДополнительные каталоги шрифтов.
boolAllowSearchfalseПеренаправляется к PdfConfig.AllowSearch.
boolAllowCopyfalseПеренаправляется к PdfConfig.AllowCopy.

Установите шрифты, используемые презентациями, на сервере, либо укажите FontFolders на папку, где они находятся. Отсутствующие шрифты заменяются без каких‑либо ошибок.

Конфигурация CAD

Форматы: DWG, DXF, DGN. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueРендер CAD нативно; false использует перенаправление PDF.
PdfConfigPdfConfigновый экземплярНастройки пути PDF.
boolExportPdfAfalseВывод архивного PDF/A.
boolShowColortrueЦветной вместо монохромного.
boolWhiteBackgroundtrueБелый фон вместо черного.
shortLineWidth25Ширина штриха CAD.
boolShowLayoutsfalseРендер вкладок раскладки.
boolShowModeltrueРендер пространства модели.
boolCheck3DSolidtrueОбрабатывать 3D‑тела.
boolExportAllLayoutsfalseЭкспортировать все раскладки, переопределяя выбор модели/раскладки.
boolLimitMinimumSizefalseПрименить MinimumSize.
intMinimumSize700Минимальный размер вывода в пикселях.
boolLimitMaximumSizefalseПрименить MaximumSize.
intMaximumSize700Максимальный размер вывода в пикселях.
boolShowAllLayoutsDgnfalseВключать все раскладки DGN.
boolAutomaticLayoutScalingtrueАвтоматически масштабировать раскладки.
floatPdfMargins0.5Поле PDF в дюймах.
RenderQualityQualityImageLowКачество растра: Low, Medium или High.
RenderQualityQualityTextMediumКачество текста: Low, Medium или High.

EmailConfig

Форматы: EML, EMLX, MSG. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueНативный рендер электронной почты; false использует перенаправление PDF.
PdfConfigPdfConfigновый экземплярНастройки пути PDF.
Encoding?EmailEncodingnullПереопределить кодировку сообщения.
Encoding?SubjectEncodingnullПереопределить кодировку темы.
Encoding?BodyEncodingnullПереопределить кодировку тела.
boolSkipExternalImagesfalseНе загружать удаленно ссылочные изображения. Рекомендуется для недоверенной электронной почты.
boolRemoveLastWhitePagefalseУдалить завершающую пустую страницу.
boolUseAntiAliasingfalseВключить сглаживание.
boolUseHighQualityRenderingfalseПредпочитать более чистый, более медленный рендеринг.
TimeSpan?TimeZoneOffsetnullПереопределить часовой пояс, используемый для дат.
boolForcePageSizefalseПринудительно фиксировать размеры страниц.

ImageConfig, TiffConfig и PsdConfig

ImageConfig охватывает JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF и SVG. Его DPI по умолчанию — 100.

КонфигурацияСвойствоПо умолчаниюПоведение
ImageConfigMaxImagePixelSize3000Максимальная ширина/высота. 0 означает неограниченно; ненулевые значения ниже 50 игнорируются.
ImageConfigTransparentPngtrueСохранять прозрачность PNG; false использует белый фон.
TiffConfigдополнительные свойства отсутствуютDPI 200Использует только BaseConfig; поддерживает многостраничный TIFF.
PsdConfigMaxImagePixelSize3000Такая же проверка 0/minimum-50 как у ImageConfig; DPI по умолчанию — 100.

DicomConfig

Форматы: DCM, IMA. Эффективный DPI по умолчанию: 100. Требуется плагин DICOM. В этом пакете файлы DICOM полностью рендерятся, но технические метаданные недоступны — см. Плагин DICOM.

ТипСвойствоПо умолчаниюПоведение
intHorizontalResolution100 эффективныйЯвный горизонтальный DPI; иначе ImageResolution, затем 100.
intVerticalResolution100 эффективныйЯвный вертикальный DPI; иначе ImageResolution, затем 100.
intAnimationFrameDelayMs100Задержка анимации многокадрового изображения; тайминг GIF использует единицы в 10 мс.
ushortLoopCount00 зацикливается бесконечно; положительные значения останавливаются после указанного количества.
DicomDisplayModeDisplayModeAnimationAndFramesAnimationOnly, FramesOnly, или комбинированный обзор плюс статические кадры.

TxtConfig

Формат: TXT. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
DocPaperSizePaperSizeA4Размер выходного листа.
Encoding?FileEncodingnullnull использует UTF-8.
stringFontInformation""Информация о шрифте для рендеринга текста.

Используйте WordConfig, когда обычный текст нуждается в более богатом поведении макета страницы.

ProjectConfig

Форматы: MPP, MPPX, MPX. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueНативное изображение Gantt; false использует текстовый путь PDF.
PdfConfigPdfConfigновый экземплярНастройки пути PDF.
boolExportPdfAtrueАрхивный вывод PDF/A.
MppPaperSizePaperSizeLedgerРазмер выходного листа проекта.
MppTimeScaleTimeScaleMonthsDays или Months.
MppFormatPresentationFormatGanttChartGanttChart, TaskUsage, ResourceUsage, ResourceSheet, или TaskSheet.

Для точного поиска по координатам текста используйте DefaultRender = false.

VisioConfig

Форматы: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. DPI по умолчанию: 200.

ТипСвойствоПо умолчаниюПоведение
boolDefaultRendertrueНативный рендер диаграмм; false использует перенаправление PDF.
PdfConfigPdfConfigновый экземплярНастройки пути PDF.
boolExportPdfAtrueАрхивный вывод PDF/A.

HtmlConfig, EpubConfig, MhtConfig и XpsConfig

Все четыре по умолчанию используют DPI 200 и предоставляют вложенный PdfConfig.

КонфигурацияФорматыDefaultRenderДополнительные свойства/поведение
HtmlConfigHTML, HTMtrueНативный рендер; используйте false для текстового пути поиска PDF.
EpubConfigEPUBtrueНативный рендер; false использует PDF.
MhtConfigMHT, MHTMLtrue в классе; false в автоматическом каталогеОбычное открытие без конфигурации использует перенаправление на поисковый PDF. Явно созданный экземпляр по умолчанию рендерит нативно.
XpsConfigXPSfalseПо умолчанию использует путь PDF; установите true для нативного рендеринга изображений.

Примеры конфигураций по семейству

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

Выбор по расширению

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 перенаправление → поиск нативного текста с пиксельной точностью
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // возврат к конфигурации по умолчанию формата
};

Была ли эта страница полезной?