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

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

Каждый документ открывается с реализацией BaseConfig. Передайте её в OpenDocumentAsync или позвольте каталогу форматов создать значение по умолчанию. Все классы ниже находятся в пространстве имён Doconut.

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.
PdfConfigPdfConfigновый экземплярНастройки, используемые в пути PDF/поиска.
DocPaperSizePaperSizeA4Размер выводимой бумаги. Используйте Custom с шириной/высотой.
intPaperWidth595Пользовательская ширина в пунктах.
intPaperHeight841Пользовательская высота в пунктах.
boolRemovePaperMarginfalseУдалять поля страниц документа.
boolRenderPageColortrueСохранять настроенный в Word цвет страниц; false отрисовывает белые страницы.
boolExportPdfAfalseИспользовать архивный PDF/A в пути PDF.
Encoding?FileEncodingnullПереопределять кодировку источника.
stringFontInfo""Информация о замене шрифтов.
string[]?FontFoldersnullДополнительные каталоги шрифтов, особенно полезные в Linux/контейнерах.
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, все являются nullable‑строками.

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.

Страницы рисуются шрифтами, установленными на сервере. В Linux установите шрифты, используемые в презентациях, или укажите путь к ним через FontFolders: отсутствующий шрифт заменяется без ошибки, поэтому разрывы строк могут отличаться от Windows. fonts-liberation, fonts-crosextra-carlito и fonts-crosextra-caladea предоставляют метрически совместимые заменители для распространённых шрифтов Windows. В Linux требуется только libfontconfig1 (libgdiplus не требуется).

Конфигурация 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Рендер нативного email; false использует перенаправление в PDF.
PdfConfigPdfConfigновый экземплярНастройки пути PDF.
Encoding?EmailEncodingnullПереопределить кодировку сообщения.
Encoding?SubjectEncodingnullПереопределить кодировку темы.
Encoding?BodyEncodingnullПереопределить кодировку тела.
boolSkipExternalImagesfalseНе загружать изображения, полученные удаленно. Рекомендуется для недоверенных email.
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 effectiveЯвный горизонтальный DPI; иначе ImageResolution, затем 100.
intVerticalResolution100 effectiveЯвный вертикальный 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[] { "/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 → пиксельно-точный нативный поиск текста
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // вернуться к конфигу по умолчанию формата
};

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