Configurações de Formato

Opções completas de renderização por formato

Todo documento abre com uma implementação BaseConfig. Passe uma para OpenDocumentAsync ou deixe o catálogo de formatos criar seu padrão. Todas as classes abaixo estão no namespace Doconut.

csharp
var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true,
    ImageResolution = 150
});

Herança e configurações PDF aninhadas

Todo formato herda as cinco propriedades BaseConfig. Formatos que podem redirecionar através de PDF expõem um PdfConfig aninhado. Em WordConfig, ExcelConfig e PptConfig, AllowSearch e AllowCopy são propriedades de conveniência que leem e escrevem o PdfConfig aninhado.

DefaultRender = true seleciona o renderizador nativo de formato. Em formatos com redirecionamento PDF, false converte primeiro para um PDF em memória e então usa o visualizador de PDF. Esse caminho costuma ser útil para busca por coordenadas de texto, mas custa uma conversão extra.

Salvo indicação em contrário, as tabelas mostram os valores padrão de construtor/propriedade. O catálogo automático de formatos substitui deliberadamente dois deles: ele cria ExcelConfig com SplitWorksheets = true, e MhtConfig com DefaultRender = false.

BaseConfig

TipoPropriedadePadrãoComportamento
intImageResolution00 usa o padrão do formato. Faixa explícita válida é 25-300 DPI; atribuições inválidas são ignoradas.
stringDocumentCulture""Local para datas e números. Valores não vazios são aparados; atribuições vazias são ignoradas.
stringPassword""Senha de documento protegido. DocOptions.Password é copiado aqui automaticamente.
boolShowUItruePropriedade de compatibilidade; o renderizador atual não a usa para controlar a barra de ferramentas do navegador.
boolCachePagestrueArmazena em cache as imagens de página renderizadas para a sessão do documento.

PdfConfig

Formatos: PDF. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueInterruptor de compatibilidade. A fábrica atual usa o visualizador PDF nativo.
boolAllowSearchfalseConstrói/usa o índice de busca de texto PDF. Requer a capacidade de licença Search para solicitações.
boolAllowCopyfalsePermite operações de seleção/cópia de texto.
boolExtractHyperlinksfalseExtrai retângulos de links para sobreposições do cliente.
intHyperlinksPageCount0Máximo de páginas escaneadas para links; 0 significa todas as páginas.
boolCompressImagesfalseComprime imagens incorporadas antes da renderização.
intCompressQuality100Qualidade JPEG usada quando a compressão está habilitada.
boolResizeImagesfalseRedimensiona imagens incorporadas antes da renderização.
intResizeResolution300DPI alvo para imagens redimensionadas.
boolCompressFastfalsePrefere o caminho de compressão mais rápido e de menor qualidade.
boolFixInvalidImagesfalseTenta reparar imagens incorporadas inválidas.
boolSplitSegmentsfalseReúne palavras divididas em segmentos de linha para melhorar busca/cópia.

showHyperlinks em ViewerConfig controla a sobreposição do cliente, enquanto ExtractHyperlinks controla a extração no servidor. Ative ambos.

WordConfig

Formatos: DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, XML. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa do Word; false usa o redirecionamento PDF.
PdfConfigPdfConfignova instânciaConfigurações usadas pelo caminho PDF/busca.
DocPaperSizePaperSizeA4Tamanho de papel de saída. Use Custom com largura/altura.
intPaperWidth595Largura personalizada em pontos.
intPaperHeight841Altura personalizada em pontos.
boolRemovePaperMarginfalseRemove margens de página do documento.
boolRenderPageColortruePreserva a cor de página configurada no Word; false renderiza páginas brancas.
boolExportPdfAfalseUsa PDF/A de arquivamento no caminho PDF.
Encoding?FileEncodingnullSubstitui a codificação de origem.
stringFontInfo""Informação de substituição de fontes.
string[]?FontFoldersnullDiretórios de fontes adicionais, especialmente úteis em Linux/containers.
boolAllowSearchfalseDelegado para PdfConfig.AllowSearch.
boolAllowCopyfalseDelegado para PdfConfig.AllowCopy.
TableAutoFitBehaviorAutoFitAllTablesNoneNone, AutoFitToContents ou AutoFitToWindow.

ExcelConfig

Formatos: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa da planilha; false usa o redirecionamento PDF.
PdfConfigPdfConfignova instânciaConfigurações para o caminho PDF/pesquisa.
ExcelPaperSizePaperSizePaperA4Tamanho do papel de saída.
doublePaperMargins0.25Margens da página em polegadas.
boolPaperLandscapetrueRenderização da planilha em paisagem.
boolAutoFitContentsfalseAjuste automático da altura das linhas e largura das colunas.
boolRemoveEmptyContenttrueAperte a saída excluindo conteúdo vazio.
boolCalculateFormulatrueRecalcular fórmulas antes da renderização.
boolShowRowColumnHeaderstrueIncluir cabeçalhos da planilha.
boolExportPdfAfalseUsar PDF/A no caminho PDF.
boolSplitWorksheetsfalseManter planilhas como grupos de páginas separados.
boolShowEmptyWorkSheetsfalseIncluir planilhas vazias.
boolExportLandscapefalseForçar exportação em paisagem.
boolExportOnePagePerSheetfalseAjustar cada planilha a uma página de saída.
boolMemoryOptimizationPreferencetrueReduzir memória máxima, potencialmente trocando por alguma velocidade.
boolAutoTrimWorksheetRenderRangetrueRenderizar apenas o intervalo usado visível quando não existe área de impressão explícita.
boolAutoTrimPreserveExistingPrintAreatruePreservar áreas de impressão definidas na pasta de trabalho durante o auto‑corte.
string?PrintAreanullIntervalo explícito como "A1:Z100".
boolPrintGridlinesfalseImprimir linhas de grade da planilha.
boolPrintHeadingsfalseImprimir cabeçalhos de linhas/colunas.
List<string>SheetNamesvazioRestringir renderização a planilhas nomeadas.
CustomStyleCell?CustomStylesnullSobrescritas opcionais de formatação de data/decimal/inteiro.
boolAllowSearchfalseDelegado a PdfConfig.AllowSearch.
boolAllowCopyfalseDelegado a PdfConfig.AllowCopy.

CustomStyleCell expõe CustomStyleDateTime, CustomStyleNumberDecimal e CustomStyleNumberInteger, todas strings anuláveis.

new ExcelConfig() define SplitWorksheets para false; abrir um arquivo Excel sem uma configuração explícita usa o catálogo de formatos, que o define para true.

PptConfig

Formatos: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa de slide; false usa o redirecionamento PDF.
boolFastLoadfalseEvitar renderizar o primeiro slide ao abrir; usar metadados e renderizar sob demanda.
PdfConfigPdfConfignova instânciaConfigurações para o comportamento PDF/pesquisa.
stringFontInfo""Informações de substituição de fonte.
string[]?FontFoldersnullDiretórios de fontes adicionais.
boolAllowSearchfalseDelegado a PdfConfig.AllowSearch.
boolAllowCopyfalseDelegado a PdfConfig.AllowCopy.

As páginas são desenhadas com as fontes instaladas no servidor. No Linux, instale as fontes usadas nas apresentações ou aponte FontFolders para elas: uma fonte ausente é substituída sem erro, portanto quebras de linha podem diferir do Windows. fonts-liberation, fonts-crosextra-carlito e fonts-crosextra-caladea fornecem substitutos metricamente compatíveis para as fontes Windows comuns. O Linux precisa apenas de libfontconfig1 (libgdiplus não é necessário).

CadConfig

Formatos: DWG, DXF, DGN. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa CAD; false usa o redirecionamento PDF.
PdfConfigPdfConfignova instânciaConfigurações do caminho PDF.
boolExportPdfAfalseSaída PDF/A de arquivamento.
boolShowColortrueCor em vez de monocromático.
boolWhiteBackgroundtrueFundo branco em vez de preto.
shortLineWidth25Largura do traço CAD.
boolShowLayoutsfalseRenderizar abas de layout.
boolShowModeltrueRenderizar espaço de modelo.
boolCheck3DSolidtrueProcessar sólidos 3D.
boolExportAllLayoutsfalseExportar todos os layouts, sobrescrevendo a seleção de modelo/layout.
boolLimitMinimumSizefalseAplicar MinimumSize.
intMinimumSize700Tamanho mínimo de saída em pixels.
boolLimitMaximumSizefalseAplicar MaximumSize.
intMaximumSize700Tamanho máximo de saída em pixels.
boolShowAllLayoutsDgnfalseIncluir todos os layouts DGN.
boolAutomaticLayoutScalingtrueDimensionar layouts automaticamente.
floatPdfMargins0.5Margem PDF em polegadas.
RenderQualityQualityImageLowQualidade raster: Low, Medium ou High.
RenderQualityQualityTextMediumQualidade de texto: Low, Medium ou High.

Configuração de Email

Formatos: EML, EMLX, MSG. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa de email; false usa o redirecionamento PDF.
PdfConfigPdfConfignova instânciaConfigurações de caminho PDF.
Encoding?EmailEncodingnullSubstitui a codificação da mensagem.
Encoding?SubjectEncodingnullSubstitui a codificação do assunto.
Encoding?BodyEncodingnullSubstitui a codificação do corpo.
boolSkipExternalImagesfalseNão carregue imagens referenciadas remotamente. Recomendado para email não confiável.
boolRemoveLastWhitePagefalseRemove uma página em branco final.
boolUseAntiAliasingfalseHabilita anti-aliasing.
boolUseHighQualityRenderingfalsePrefere renderização mais limpa e lenta.
TimeSpan?TimeZoneOffsetnullSubstitui o fuso horário usado para datas.
boolForcePageSizefalseForça dimensões de página fixas.

Configurações de Imagem, Tiff e Psd

ImageConfig cobre JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF e SVG. Seu DPI padrão é 100.

ConfiguraçãoPropriedadePadrãoComportamento
ImageConfigMaxImagePixelSize3000Largura/altura máxima. 0 significa ilimitado; valores diferentes de zero abaixo de 50 são ignorados.
ImageConfigTransparentPngtruePreserva a transparência PNG; false usa fundo branco.
TiffConfigsem propriedades adicionaisDPI 200Usa apenas BaseConfig; suporta TIFF multipágina.
PsdConfigMaxImagePixelSize3000Mesma validação 0/mínimo-50 que ImageConfig; DPI padrão é 100.

Configuração Dicom

Formatos: DCM, IMA. DPI efetivo padrão: 100. Requer o plugin DICOM.

TipoPropriedadePadrãoComportamento
intHorizontalResolution100 efetivoDPI horizontal explícito; caso contrário ImageResolution, então 100.
intVerticalResolution100 efetivoDPI vertical explícito; caso contrário ImageResolution, então 100.
intAnimationFrameDelayMs100Atraso de animação de múltiplos quadros; temporização GIF usa unidades de 10 ms.
ushortLoopCount00 repete indefinidamente; valores positivos param após essa contagem.
DicomDisplayModeDisplayModeAnimationAndFramesAnimationOnly, FramesOnly, ou visão geral combinada mais quadros estáticos.

Configuração Txt

Formato: TXT. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
DocPaperSizePaperSizeA4Tamanho de papel de saída.
Encoding?FileEncodingnullnull usa UTF-8.
stringFontInformation""Informação de fonte para renderização de texto.

Use WordConfig quando texto simples precisar de comportamento de layout de página mais rico.

Configuração de Projeto

Formatos: MPP, MPPX, MPX. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueImagem Gantt nativa; false usa um caminho PDF baseado em texto.
PdfConfigPdfConfignova instânciaConfigurações de caminho PDF.
boolExportPdfAtrueSaída PDF/A de arquivamento.
MppPaperSizePaperSizeLedgerTamanho de papel de saída do projeto.
MppTimeScaleTimeScaleMonthsDays ou Months.
MppFormatPresentationFormatGanttChartGanttChart, TaskUsage, ResourceUsage, ResourceSheet, ou TaskSheet.

Para busca exata por coordenadas de texto, use DefaultRender = false.

Configuração Visio

Formatos: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. DPI padrão: 200.

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa de diagrama; false usa o redirecionamento PDF.
PdfConfigPdfConfignova instânciaConfigurações de caminho PDF.
boolExportPdfAtrueSaída PDF/A de arquivamento.

Configurações Html, Epub, Mht e Xps

Todas as quatro têm DPI padrão de 200 e expõem um PdfConfig aninhado.

ConfiguraçãoFormatosDefaultRenderPropriedades/comportamento adicionais
HtmlConfigHTML, HTMtrueRenderização nativa; use false para um caminho de busca PDF baseado em texto.
EpubConfigEPUBtrueRenderização nativa; false usa PDF.
MhtConfigMHT, MHTMLtrue na classe; false no catálogo automáticoA abertura normal sem configuração usa o redirecionamento PDF pesquisável. Uma instância padrão explicitamente construída renderiza nativamente.
XpsConfigXPSfalseUsa o caminho PDF por padrão; defina true para renderização nativa de imagem.

Exemplos de configuração por família

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

Seleção por extensão

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 redirecionamento → pesquisa de texto nativa pixel-precisa
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // recuar para a configuração padrão do formato
};

Esta página foi útil?