Configurações de Formato

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

Cada 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.

Esse namespace único é novo. A biblioteca .NET Standard anterior distribuía esses tipos entre Doconut.Configs, Doconut.Configs.View e Doconut.Models. Os nomes dos tipos não mudaram — na maioria dos arquivos a edição completa consiste em excluir duas linhas using. Consulte o guia de migração.

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

Herança e configurações PDF aninhadas

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

DefaultRender = true seleciona o renderizador de formato nativo. 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 implica uma conversão extra.

Salvo indicação em contrário, as tabelas mostram os valores padrão de construtores/propriedades. O catálogo de formatos automático 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 é copiada aqui automaticamente.
boolShowUItruePropriedade de compatibilidade; o renderizador atual não a usa para controlar a barra de ferramentas do navegador.
boolCachePagestrueCache de 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 em 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.
boolCompressImagesfalseCompacta imagens incorporadas antes da renderização.
intCompressQuality100Qualidade JPEG usada quando a compactaçã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 qualidade inferior.
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.
PdfConfigPdfConfignew instanceConfiguraçõ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 as 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ções de substituição de fontes.
string[]?FontFoldersnullDiretórios de fontes adicionais — útil em um servidor que não possui as fontes usadas pelos documentos.
boolAllowSearchfalseDelegado para PdfConfig.AllowSearch.
boolAllowCopyfalseDelegado para PdfConfig.AllowCopy.
TableAutoFitBehaviorAutoFitAllTablesNoneNone, AutoFitToContents ou AutoFitToWindow.

ConfiguraçãoExcel

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

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa de planilha; false usa o redirecionamento para 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 de planilha em modo paisagem.
boolAutoFitContentsfalseAjuste automático da altura das linhas e largura das colunas.
boolRemoveEmptyContenttrueAperta a saída excluindo conteúdo vazio.
boolCalculateFormulatrueRecalcula 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 o pico de memória, 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 corte automático.
string?PrintAreanullIntervalo explícito como "A1:Z100".
boolPrintGridlinesfalseImprimir linhas de grade da planilha.
boolPrintHeadingsfalseImprimir cabeçalhos de linhas/colunas.
List<string>SheetNamesvazioRestringir a renderização a planilhas nomeadas.
CustomStyleCell?CustomStylesnullSobrescritas opcionais de formatação de data/decimal/integer.
boolAllowSearchfalseDelegado para PdfConfig.AllowSearch.
boolAllowCopyfalseDelegado para PdfConfig.AllowCopy.

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

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

ConfiguraçãoPpt

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 para 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 fontes.
string[]?FontFoldersnullDiretórios de fontes adicionais.
boolAllowSearchfalseDelegado para PdfConfig.AllowSearch.
boolAllowCopyfalseDelegado para PdfConfig.AllowCopy.

Instale as fontes que as apresentações utilizam no servidor, ou aponte FontFolders para uma pasta que as contenha. Fontes ausentes são substituídas sem nenhum erro.

ConfiguraçãoCad

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

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa CAD; false usa o redirecionamento para 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.
boolAutomaticLayoutScalingtrueEscalar layouts automaticamente.
floatPdfMargins0.5Margem do PDF em polegadas.
RenderQualityQualityImageLowQualidade raster: Low, Medium ou High.
RenderQualityQualityTextMediumQualidade de texto: Low, Medium ou High.

EmailConfig

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

TipoPropriedadePadrãoComportamento
boolDefaultRendertrueRenderização nativa de e‑mail; false usa o redirecionamento para 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 carrega imagens referenciadas remotamente. Recomendado para e‑mail 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 nas datas.
boolForcePageSizefalseForça dimensões de página fixas.

ImageConfig, TiffConfig e PsdConfig

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 transparência PNG; false usa fundo branco.
TiffConfignenhuma propriedade adicionalDPI 200Usa apenas BaseConfig; suporta TIFF multipágina.
PsdConfigMaxImagePixelSize3000Mesma validação 0/mínimo-50 que ImageConfig; DPI padrão é 100.

DicomConfig

Formatos: DCM, IMA. DPI efetivo padrão: 100. Requer o plugin DICOM. Neste pacote, arquivos DICOM são renderizados totalmente, mas metadados técnicos não estão disponíveis — veja 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 multiquadro; 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.

TxtConfig

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.

ProjectConfig

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.

VisioConfig

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 para PDF.
PdfConfigPdfConfignova instânciaConfigurações de caminho PDF.
boolExportPdfAtrueSaída PDF/A de arquivamento.

HtmlConfig, EpubConfig, MhtConfig e XpsConfig

Todos os quatro têm padrão 200 DPI 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 = new[] { Path.Combine(AppContext.BaseDirectory, "Fonts") },
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = new[] { Path.Combine(AppContext.BaseDirectory, "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
    }
};

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

Esta página foi útil?