格式配置 – Doconut 文档

每个文档都会使用 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

类型	属性	默认值	行为
`int`	`ImageResolution`	`0`	`0` 使用格式默认值。有效的显式范围为 25‑300 DPI；无效赋值将被忽略。
`string`	`DocumentCulture`	`""`	日期和数字的区域设置。非空值会被修剪；空值赋予将被忽略。
`string`	`Password`	`""`	受保护文档的密码。`DocOptions.Password` 会自动复制到此处。
`bool`	`ShowUI`	`true`	兼容性属性；当前渲染器并不使用它来控制浏览器工具栏。
`bool`	`CachePages`	`true`	为文档会话缓存已渲染的页面图像。

PdfConfig

格式：PDF。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	兼容性开关。当前工厂使用本机 PDF 查看器。
`bool`	`AllowSearch`	`false`	构建/使用 PDF 文本搜索索引。需要 Search 许可证功能。
`bool`	`AllowCopy`	`false`	允许文本选择/复制操作。
`bool`	`ExtractHyperlinks`	`false`	提取链接矩形以供客户端覆盖层使用。
`int`	`HyperlinksPageCount`	`0`	扫描链接的最大页数；`0` 表示所有页面。
`bool`	`CompressImages`	`false`	在渲染前压缩嵌入图像。
`int`	`CompressQuality`	`100`	启用压缩时使用的 JPEG 质量。
`bool`	`ResizeImages`	`false`	在渲染前调整嵌入图像大小。
`int`	`ResizeResolution`	`300`	调整后图像的目标 DPI。
`bool`	`CompressFast`	`false`	偏好更快、质量更低的压缩路径。
`bool`	`FixInvalidImages`	`false`	尝试修复无效的嵌入图像。
`bool`	`SplitSegments`	`false`	将跨行段落的单词重新合并，以改进搜索/复制。

ViewerConfig 中的 showHyperlinks 控制客户端覆盖层，而 ExtractHyperlinks 控制服务器端提取。两者都启用时才能生效。

WordConfig

格式：DOC、DOCX、DOCM、DOT、DOTX、DOTM、RTF、ODT、OTT、XML。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机 Word 渲染；`false` 使用 PDF 重定向。
`PdfConfig`	`PdfConfig`	新实例	PDF/搜索路径使用的设置。
`DocPaperSize`	`PaperSize`	`A4`	输出纸张大小。使用 `Custom` 可指定宽高。
`int`	`PaperWidth`	`595`	自定义宽度（单位：点）。
`int`	`PaperHeight`	`841`	自定义高度（单位：点）。
`bool`	`RemovePaperMargin`	`false`	去除文档页面边距。
`bool`	`RenderPageColor`	`true`	保持 Word 配置的页面颜色；`false` 渲染为白页。
`bool`	`ExportPdfA`	`false`	在 PDF 路径上使用归档 PDF/A。
`Encoding?`	`FileEncoding`	`null`	覆盖源文件编码。
`string`	`FontInfo`	`""`	字体替代信息。
`string[]?`	`FontFolders`	`null`	额外的字体目录，Linux/容器中尤为有用。
`bool`	`AllowSearch`	`false`	委托给 `PdfConfig.AllowSearch`。
`bool`	`AllowCopy`	`false`	委托给 `PdfConfig.AllowCopy`。
`TableAutoFitBehavior`	`AutoFitAllTables`	`None`	`None`、`AutoFitToContents` 或 `AutoFitToWindow`。

ExcelConfig

格式：XLS、XLSX、XLSM、XLSB、XLTX、XLTM、ODS、CSV。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机工作表渲染；`false` 使用 PDF 重定向。
`PdfConfig`	`PdfConfig`	新实例	PDF/搜索路径的设置。
`ExcelPaperSize`	`PaperSize`	`PaperA4`	输出纸张大小。
`double`	`PaperMargins`	`0.25`	页面边距（英寸）。
`bool`	`PaperLandscape`	`true`	横向工作表渲染。
`bool`	`AutoFitContents`	`false`	自动适配行高和列宽。
`bool`	`RemoveEmptyContent`	`true`	通过排除空内容来紧凑输出。
`bool`	`CalculateFormula`	`true`	渲染前重新计算公式。
`bool`	`ShowRowColumnHeaders`	`true`	包含电子表格标题行/列。
`bool`	`ExportPdfA`	`false`	在 PDF 路径上使用 PDF/A。
`bool`	`SplitWorksheets`	`false`	将工作表保持为独立的页面组。
`bool`	`ShowEmptyWorkSheets`	`false`	包含空工作表。
`bool`	`ExportLandscape`	`false`	强制横向导出。
`bool`	`ExportOnePagePerSheet`	`false`	将每个工作表适配为单页输出。
`bool`	`MemoryOptimizationPreference`	`true`	降低峰值内存占用，可能会牺牲部分速度。
`bool`	`AutoTrimWorksheetRenderRange`	`true`	当未指定打印区域时，仅渲染可见的使用范围。
`bool`	`AutoTrimPreserveExistingPrintArea`	`true`	自动裁剪时保留工作簿定义的打印区域。
`string?`	`PrintArea`	`null`	显式范围，例如 `"A1:Z100"`。
`bool`	`PrintGridlines`	`false`	打印工作表网格线。
`bool`	`PrintHeadings`	`false`	打印行/列标题。
`List<string>`	`SheetNames`	empty	限制渲染至指定名称的工作表。
`CustomStyleCell?`	`CustomStyles`	`null`	可选的日期/小数/整数格式覆盖。
`bool`	`AllowSearch`	`false`	委托给 `PdfConfig.AllowSearch`。
`bool`	`AllowCopy`	`false`	委托给 `PdfConfig.AllowCopy`。

CustomStyleCell 暴露 CustomStyleDateTime、CustomStyleNumberDecimal 和 CustomStyleNumberInteger，全部为可空字符串。

new ExcelConfig() 将 SplitWorksheets 设置为 false；在未显式提供配置打开 Excel 文件时，格式目录会将其设为 true。

PptConfig

格式：PPT、PPTX、PPTM、PPSX、PPSM、POT、POTX、POTM、ODP。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机幻灯片渲染；`false` 使用 PDF 重定向。
`bool`	`FastLoad`	`false`	打开时避免渲染第一张幻灯片；使用元数据并按需渲染。
`PdfConfig`	`PdfConfig`	新实例	PDF/搜索行为的设置。
`string`	`FontInfo`	`""`	字体替代信息。
`string[]?`	`FontFolders`	`null`	额外的字体目录。
`bool`	`AllowSearch`	`false`	委托给 `PdfConfig.AllowSearch`。
`bool`	`AllowCopy`	`false`	委托给 `PdfConfig.AllowCopy`。

在 Linux 和 macOS 上，当前引擎的演示渲染需要 libgdiplus 并将 System.Drawing.EnableUnixSupport=true。请安装演示使用的字体或提供 FontFolders。

CadConfig

格式：DWG、DXF、DGN。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机 CAD 渲染；`false` 使用 PDF 重定向。
`PdfConfig`	`PdfConfig`	新实例	PDF 路径设置。
`bool`	`ExportPdfA`	`false`	归档 PDF/A 输出。
`bool`	`ShowColor`	`true`	彩色而非单色。
`bool`	`WhiteBackground`	`true`	白色背景而非黑色。
`short`	`LineWidth`	`25`	CAD 笔画宽度。
`bool`	`ShowLayouts`	`false`	渲染布局标签页。
`bool`	`ShowModel`	`true`	渲染模型空间。
`bool`	`Check3DSolid`	`true`	处理 3D 实体。
`bool`	`ExportAllLayouts`	`false`	导出所有布局，覆盖模型/布局选择。
`bool`	`LimitMinimumSize`	`false`	应用 `MinimumSize`。
`int`	`MinimumSize`	`700`	最小输出尺寸（像素）。
`bool`	`LimitMaximumSize`	`false`	应用 `MaximumSize`。
`int`	`MaximumSize`	`700`	最大输出尺寸（像素）。
`bool`	`ShowAllLayoutsDgn`	`false`	包含所有 DGN 布局。
`bool`	`AutomaticLayoutScaling`	`true`	自动缩放布局。
`float`	`PdfMargins`	`0.5`	PDF 边距（英寸）。
`RenderQuality`	`QualityImage`	`Low`	栅格图像质量：`Low`、`Medium` 或 `High`。
`RenderQuality`	`QualityText`	`Medium`	文本质量：`Low`、`Medium` 或 `High`。

EmailConfig

格式：EML、EMLX、MSG。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机电子邮件渲染；`false` 使用 PDF 重定向。
`PdfConfig`	`PdfConfig`	新实例	PDF 路径设置。
`Encoding?`	`EmailEncoding`	`null`	覆盖消息编码。
`Encoding?`	`SubjectEncoding`	`null`	覆盖主题编码。
`Encoding?`	`BodyEncoding`	`null`	覆盖正文编码。
`bool`	`SkipExternalImages`	`false`	不加载远程引用的图像。建议用于不可信的邮件。
`bool`	`RemoveLastWhitePage`	`false`	移除尾部空白页。
`bool`	`UseAntiAliasing`	`false`	启用抗锯齿。
`bool`	`UseHighQualityRendering`	`false`	偏好更清晰但更慢的渲染。
`TimeSpan?`	`TimeZoneOffset`	`null`	覆盖用于日期的时区偏移。
`bool`	`ForcePageSize`	`false`	强制固定页面尺寸。

ImageConfig、TiffConfig 和 PsdConfig

ImageConfig 覆盖 JPG、JPEG、JPE、PNG、BMP、GIF、ICO、EPS、TGA、WEBP、CDR、CMX、DNG、EMF、WMF、AVIF 和 SVG。其默认 DPI 为 100。

配置	属性	默认值	行为
`ImageConfig`	`MaxImagePixelSize`	`3000`	最大宽/高。`0` 表示无限制；小于 50 的非零值会被忽略。
`ImageConfig`	`TransparentPng`	`true`	保持 PNG 透明度；`false` 使用白色背景。
`TiffConfig`	无额外属性	DPI `200`	仅使用 `BaseConfig`；支持多页 TIFF。
`PsdConfig`	`MaxImagePixelSize`	`3000`	与 `ImageConfig` 相同的 `0`/最小 50 验证；默认 DPI 为 `100`。

DicomConfig

格式：DCM、IMA。默认有效 DPI：100。需要 DICOM 插件。

类型	属性	默认值	行为
`int`	`HorizontalResolution`	`100` effective	显式水平 DPI；否则使用 `ImageResolution`，再没有则为 100。
`int`	`VerticalResolution`	`100` effective	显式垂直 DPI；否则使用 `ImageResolution`，再没有则为 100。
`int`	`AnimationFrameDelayMs`	`100`	多帧动画延迟；GIF 计时使用 10 ms 单位。
`ushort`	`LoopCount`	`0`	`0` 表示无限循环；正数在达到该次数后停止。
`DicomDisplayMode`	`DisplayMode`	`AnimationAndFrames`	`AnimationOnly`、`FramesOnly` 或动画加静态帧的组合概览。

TxtConfig

格式：TXT。默认 DPI：200。

类型	属性	默认值	行为
`DocPaperSize`	`PaperSize`	`A4`	输出纸张大小。
`Encoding?`	`FileEncoding`	`null`	`null` 时使用 UTF-8。
`string`	`FontInformation`	`""`	文本渲染的字体信息。

需要更丰富的页面布局行为时，请使用 WordConfig 来渲染纯文本。

ProjectConfig

格式：MPP、MPPX、MPX。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机甘特图图像；`false` 使用基于文本的 PDF 路径。
`PdfConfig`	`PdfConfig`	新实例	PDF 路径设置。
`bool`	`ExportPdfA`	`true`	归档 PDF/A 输出。
`MppPaperSize`	`PaperSize`	`Ledger`	项目输出纸张大小。
`MppTimeScale`	`TimeScale`	`Months`	`Days` 或 `Months`。
`MppFormat`	`PresentationFormat`	`GanttChart`	`GanttChart`、`TaskUsage`、`ResourceUsage`、`ResourceSheet` 或 `TaskSheet`。

若需精确的文本坐标搜索，请使用 DefaultRender = false。

VisioConfig

格式：VSD、VSDX、VSS、VSSX、VST、VSTX、VDX、VSX、VSDM。默认 DPI：200。

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机图表渲染；`false` 使用 PDF 重定向。
`PdfConfig`	`PdfConfig`	新实例	PDF 路径设置。
`bool`	`ExportPdfA`	`true`	归档 PDF/A 输出。

HtmlConfig、EpubConfig、MhtConfig 和 XpsConfig

这四种配置默认 DPI 为 200，并公开一个嵌套的 PdfConfig。

配置	格式	`DefaultRender`	其他属性/行为
`HtmlConfig`	HTML、HTM	`true`	本机渲染；使用 `false` 可走基于文本的 PDF 搜索路径。
`EpubConfig`	EPUB	`true`	本机渲染；`false` 使用 PDF。
`MhtConfig`	MHT、MHTML	`true` 类上；`false` 在自动目录中	默认无配置打开时使用可搜索的 PDF 重定向。显式构造的默认实例则本机渲染。
`XpsConfig`	XPS	`false`	默认使用 PDF 路径；设为 `true` 可本机图像渲染。

按族的配置示例

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

按扩展名选择配置

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 → pixel-accurate native text search
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // fall back to the format's default config
};