格式配置 – Doconut 文档

每个文档都以 BaseConfig 实现打开。将其传递给 OpenDocumentAsync（或 OpenDocument），或让格式目录创建其默认实现。下面的所有类都位于 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 查看器。此路径通常对文本坐标搜索有用，但会增加一次转换开销。

除非另有说明，表格显示构造函数/属性的默认值。自动格式目录会有意覆盖其中两个：它使用 SplitWorksheets = true 创建 ExcelConfig，并使用 DefaultRender = false 创建 MhtConfig。

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`	重新连接跨行段的单词，以提升搜索/复制效果。

showHyperlinks 在 ViewerConfig 中控制客户端覆盖层，而 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`	附加字体目录——在缺少文档使用字体的服务器上很有用。
`bool`	`AllowSearch`	`false`	委托给 `PdfConfig.AllowSearch`。
`bool`	`AllowCopy`	`false`	委托给 `PdfConfig.AllowCopy`。
`TableAutoFitBehavior`	`AutoFitAllTables`	`None`	`None`、`AutoFitToContents` 或 `AutoFitToWindow`。

Excel 配置

格式：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`	空	限制渲染到已命名的工作表。
`CustomStyleCell?`	`CustomStyles`	`null`	可选的日期/小数/整数格式覆盖。
`bool`	`AllowSearch`	`false`	委托给 `PdfConfig.AllowSearch`。
`bool`	`AllowCopy`	`false`	委托给 `PdfConfig.AllowCopy`。

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

new ExcelConfig() 将 SplitWorksheets 设置为 false；在没有显式配置的情况下打开 Excel 文件时会使用格式目录，进而将其设置为 true。

Ppt 配置

格式：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`。

在服务器上安装演示文稿使用的字体，或将 FontFolders 指向包含这些字体的文件夹。没有 Office 的 Windows Server 所拥有的字体远少于开发机器，缺失的字体会被替换且不会产生错误。

Cad 配置

格式：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`。

电子邮件配置

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

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机电子邮件渲染；`false` 使用 PDF 重定向。
`PdfConfig`	`PdfConfig`	new instance	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`	no additional properties	DPI `200`	仅使用 `BaseConfig`；支持多页 TIFF。
`PsdConfig`	`MaxImagePixelSize`	`3000`	与 `ImageConfig` 相同的 `0`/最小 50 验证；默认 DPI 为 `100`。

Dicom 配置

格式：DCM、IMA。默认有效 DPI：100。需要 DICOM 插件。此软件包中 DICOM 文件可完整渲染，但技术元数据不可用——参见 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`，或组合概览加静态帧。

Txt 配置

格式：TXT。默认 DPI：200。

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

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

项目配置

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

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

要进行精确的文本坐标搜索，请使用 DefaultRender = false。

Visio 配置

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

类型	属性	默认值	行为
`bool`	`DefaultRender`	`true`	本机图表渲染；`false` 使用 PDF 重定向。
`PdfConfig`	`PdfConfig`	new instance	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 = new[] { HostingEnvironment.MapPath("~/App_Data/Fonts") },
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = new[] { HostingEnvironment.MapPath("~/App_Data/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)
{
    switch (extUpper)
    {
        case ".DOC": case ".DOCX": case ".DOT": case ".DOTX": case ".ODT":
            return new WordConfig
            {
                AutoFitAllTables = WordConfig.TableAutoFitBehavior.AutoFitToWindow,
                PaperSize = DocPaperSize.Tabloid,
                PdfConfig = new PdfConfig { ExtractHyperlinks = true, HyperlinksPageCount = 5, AllowCopy = true }
            };
        case ".PDF":
            return new PdfConfig { AllowSearch = true, AllowCopy = true };
        case ".XLS": case ".XLSX": case ".ODS": case ".CSV":
            return new ExcelConfig { AllowSearch = true, AllowCopy = true };
        case ".DCM": case ".IMA":
            return new DicomConfig { DisplayMode = DicomDisplayMode.AnimationAndFrames };
        // DefaultRender = false → PDF 重定向 → 像素精确的原生文本搜索
        case ".HTML": case ".HTM":
            return new HtmlConfig { DefaultRender = false };
        case ".EML": case ".EMLX": case ".MSG":
            return new EmailConfig { DefaultRender = false };
        default:
            return null; // 回退到该格式的默认配置
    }
}