格式配置

每种格式的完整渲染选项

每个文档都使用 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 查看器。此路径常用于文本坐标搜索,但会增加一次转换开销。

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

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 路径上使用归档 PDF/A。
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 路径上使用 PDF/A。
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,全部为可空字符串。

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白色背景而非黑色背景。
shortLineWidth25CAD 笔画宽度。
boolShowLayoutsfalse渲染布局标签页。
boolShowModeltrue渲染模型空间。
boolCheck3DSolidtrue处理 3D 实体。
boolExportAllLayoutsfalse导出所有布局,覆盖模型/布局选择。
boolLimitMinimumSizefalse应用 MinimumSize。
intMinimumSize700最小输出尺寸(像素)。
boolLimitMaximumSizefalse应用 MaximumSize。
intMaximumSize700最大输出尺寸(像素)。
boolShowAllLayoutsDgnfalse包含所有 DGN 布局。
boolAutomaticLayoutScalingtrue自动缩放布局。
floatPdfMargins0.5PDF 边距(英寸)。
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, and 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/最小 50 验证,如同 ImageConfig;默认 DPI 为 100。

DicomConfig

格式:DCM、IMA。默认有效 DPI:100。需要 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本机甘特图像;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, and XpsConfig

这四者默认使用 200 DPI,并公开一个嵌套的 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 = ["/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 重定向 → 像素精确的原生文本搜索
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // 回退到该格式的默认配置
};

此页面对您有帮助吗?