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.
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
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
int | ImageResolution | 0 | 0 usa o padrão do formato. Faixa explícita válida é 25‑300 DPI; atribuições inválidas são ignoradas. |
string | DocumentCulture | "" | Local para datas e números. Valores não vazios são aparados; atribuições vazias são ignoradas. |
string | Password | "" | Senha de documento protegido. DocOptions.Password é copiada aqui automaticamente. |
bool | ShowUI | true | Propriedade de compatibilidade; o renderizador atual não a usa para controlar a barra de ferramentas do navegador. |
bool | CachePages | true | Cache de imagens de página renderizadas para a sessão do documento. |
PdfConfig
Formatos: PDF. DPI padrão: 200.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Interruptor de compatibilidade. A fábrica atual usa o visualizador PDF nativo. |
bool | AllowSearch | false | Constrói/usa o índice de busca de texto em PDF. Requer a capacidade de licença Search para solicitações. |
bool | AllowCopy | false | Permite operações de seleção/cópia de texto. |
bool | ExtractHyperlinks | false | Extrai retângulos de links para sobreposições do cliente. |
int | HyperlinksPageCount | 0 | Máximo de páginas escaneadas para links; 0 significa todas as páginas. |
bool | CompressImages | false | Compacta imagens incorporadas antes da renderização. |
int | CompressQuality | 100 | Qualidade JPEG usada quando a compactação está habilitada. |
bool | ResizeImages | false | Redimensiona imagens incorporadas antes da renderização. |
int | ResizeResolution | 300 | DPI alvo para imagens redimensionadas. |
bool | CompressFast | false | Prefere o caminho de compressão mais rápido e de qualidade inferior. |
bool | FixInvalidImages | false | Tenta reparar imagens incorporadas inválidas. |
bool | SplitSegments | false | Reú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.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Renderização nativa do Word; false usa o redirecionamento PDF. |
PdfConfig | PdfConfig | new instance | Configurações usadas pelo caminho PDF/busca. |
DocPaperSize | PaperSize | A4 | Tamanho de papel de saída. Use Custom com largura/altura. |
int | PaperWidth | 595 | Largura personalizada em pontos. |
int | PaperHeight | 841 | Altura personalizada em pontos. |
bool | RemovePaperMargin | false | Remove as margens de página do documento. |
bool | RenderPageColor | true | Preserva a cor de página configurada no Word; false renderiza páginas brancas. |
bool | ExportPdfA | false | Usa PDF/A de arquivamento no caminho PDF. |
Encoding? | FileEncoding | null | Substitui a codificação de origem. |
string | FontInfo | "" | Informações de substituição de fontes. |
string[]? | FontFolders | null | Diretórios de fontes adicionais — útil em um servidor que não possui as fontes usadas pelos documentos. |
bool | AllowSearch | false | Delegado para PdfConfig.AllowSearch. |
bool | AllowCopy | false | Delegado para PdfConfig.AllowCopy. |
TableAutoFitBehavior | AutoFitAllTables | None | None, AutoFitToContents ou AutoFitToWindow. |
ConfiguraçãoExcel
Formatos: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. DPI padrão: 200.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Renderização nativa de planilha; false usa o redirecionamento para PDF. |
PdfConfig | PdfConfig | nova instância | Configurações para o caminho PDF/pesquisa. |
ExcelPaperSize | PaperSize | PaperA4 | Tamanho do papel de saída. |
double | PaperMargins | 0.25 | Margens da página em polegadas. |
bool | PaperLandscape | true | Renderização de planilha em modo paisagem. |
bool | AutoFitContents | false | Ajuste automático da altura das linhas e largura das colunas. |
bool | RemoveEmptyContent | true | Aperta a saída excluindo conteúdo vazio. |
bool | CalculateFormula | true | Recalcula fórmulas antes da renderização. |
bool | ShowRowColumnHeaders | true | Incluir cabeçalhos da planilha. |
bool | ExportPdfA | false | Usar PDF/A no caminho PDF. |
bool | SplitWorksheets | false | Manter planilhas como grupos de páginas separados. |
bool | ShowEmptyWorkSheets | false | Incluir planilhas vazias. |
bool | ExportLandscape | false | Forçar exportação em paisagem. |
bool | ExportOnePagePerSheet | false | Ajustar cada planilha a uma página de saída. |
bool | MemoryOptimizationPreference | true | Reduzir o pico de memória, potencialmente trocando por alguma velocidade. |
bool | AutoTrimWorksheetRenderRange | true | Renderizar apenas o intervalo usado visível quando não existe área de impressão explícita. |
bool | AutoTrimPreserveExistingPrintArea | true | Preservar áreas de impressão definidas na pasta de trabalho durante o corte automático. |
string? | PrintArea | null | Intervalo explícito como "A1:Z100". |
bool | PrintGridlines | false | Imprimir linhas de grade da planilha. |
bool | PrintHeadings | false | Imprimir cabeçalhos de linhas/colunas. |
List<string> | SheetNames | vazio | Restringir a renderização a planilhas nomeadas. |
CustomStyleCell? | CustomStyles | null | Sobrescritas opcionais de formatação de data/decimal/integer. |
bool | AllowSearch | false | Delegado para PdfConfig.AllowSearch. |
bool | AllowCopy | false | Delegado 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.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Renderização nativa de slide; false usa o redirecionamento para PDF. |
bool | FastLoad | false | Evitar renderizar o primeiro slide ao abrir; usar metadados e renderizar sob demanda. |
PdfConfig | PdfConfig | nova instância | Configurações para o comportamento PDF/pesquisa. |
string | FontInfo | "" | Informações de substituição de fontes. |
string[]? | FontFolders | null | Diretórios de fontes adicionais. |
bool | AllowSearch | false | Delegado para PdfConfig.AllowSearch. |
bool | AllowCopy | false | Delegado 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.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Renderização nativa CAD; false usa o redirecionamento para PDF. |
PdfConfig | PdfConfig | nova instância | Configurações do caminho PDF. |
bool | ExportPdfA | false | Saída PDF/A de arquivamento. |
bool | ShowColor | true | Cor em vez de monocromático. |
bool | WhiteBackground | true | Fundo branco em vez de preto. |
short | LineWidth | 25 | Largura do traço CAD. |
bool | ShowLayouts | false | Renderizar abas de layout. |
bool | ShowModel | true | Renderizar espaço de modelo. |
bool | Check3DSolid | true | Processar sólidos 3D. |
bool | ExportAllLayouts | false | Exportar todos os layouts, sobrescrevendo a seleção de modelo/layout. |
bool | LimitMinimumSize | false | Aplicar MinimumSize. |
int | MinimumSize | 700 | Tamanho mínimo de saída em pixels. |
bool | LimitMaximumSize | false | Aplicar MaximumSize. |
int | MaximumSize | 700 | Tamanho máximo de saída em pixels. |
bool | ShowAllLayoutsDgn | false | Incluir todos os layouts DGN. |
bool | AutomaticLayoutScaling | true | Escalar layouts automaticamente. |
float | PdfMargins | 0.5 | Margem do PDF em polegadas. |
RenderQuality | QualityImage | Low | Qualidade raster: Low, Medium ou High. |
RenderQuality | QualityText | Medium | Qualidade de texto: Low, Medium ou High. |
EmailConfig
Formatos: EML, EMLX, MSG. DPI padrão: 200.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Renderização nativa de e‑mail; false usa o redirecionamento para PDF. |
PdfConfig | PdfConfig | nova instância | Configurações de caminho PDF. |
Encoding? | EmailEncoding | null | Substitui a codificação da mensagem. |
Encoding? | SubjectEncoding | null | Substitui a codificação do assunto. |
Encoding? | BodyEncoding | null | Substitui a codificação do corpo. |
bool | SkipExternalImages | false | Não carrega imagens referenciadas remotamente. Recomendado para e‑mail não confiável. |
bool | RemoveLastWhitePage | false | Remove uma página em branco final. |
bool | UseAntiAliasing | false | Habilita anti‑aliasing. |
bool | UseHighQualityRendering | false | Prefere renderização mais limpa e lenta. |
TimeSpan? | TimeZoneOffset | null | Substitui o fuso horário usado nas datas. |
bool | ForcePageSize | false | Forç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ção | Propriedade | Padrão | Comportamento |
|---|---|---|---|
ImageConfig | MaxImagePixelSize | 3000 | Largura/altura máxima. 0 significa ilimitado; valores diferentes de zero abaixo de 50 são ignorados. |
ImageConfig | TransparentPng | true | Preserva transparência PNG; false usa fundo branco. |
TiffConfig | nenhuma propriedade adicional | DPI 200 | Usa apenas BaseConfig; suporta TIFF multipágina. |
PsdConfig | MaxImagePixelSize | 3000 | Mesma 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.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
int | HorizontalResolution | 100 efetivo | DPI horizontal explícito; caso contrário ImageResolution, então 100. |
int | VerticalResolution | 100 efetivo | DPI vertical explícito; caso contrário ImageResolution, então 100. |
int | AnimationFrameDelayMs | 100 | Atraso de animação multiquadro; temporização GIF usa unidades de 10 ms. |
ushort | LoopCount | 0 | 0 repete indefinidamente; valores positivos param após essa contagem. |
DicomDisplayMode | DisplayMode | AnimationAndFrames | AnimationOnly, FramesOnly, ou visão geral combinada mais quadros estáticos. |
TxtConfig
Formato: TXT. DPI padrão: 200.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
DocPaperSize | PaperSize | A4 | Tamanho de papel de saída. |
Encoding? | FileEncoding | null | null usa UTF-8. |
string | FontInformation | "" | 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.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Imagem Gantt nativa; false usa um caminho PDF baseado em texto. |
PdfConfig | PdfConfig | nova instância | Configurações de caminho PDF. |
bool | ExportPdfA | true | Saída PDF/A de arquivamento. |
MppPaperSize | PaperSize | Ledger | Tamanho de papel de saída do projeto. |
MppTimeScale | TimeScale | Months | Days ou Months. |
MppFormat | PresentationFormat | GanttChart | GanttChart, 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.
| Tipo | Propriedade | Padrão | Comportamento |
|---|---|---|---|
bool | DefaultRender | true | Renderização nativa de diagrama; false usa o redirecionamento para PDF. |
PdfConfig | PdfConfig | nova instância | Configurações de caminho PDF. |
bool | ExportPdfA | true | Saí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ção | Formatos | DefaultRender | Propriedades/comportamento adicionais |
|---|---|---|---|
HtmlConfig | HTML, HTM | true | Renderização nativa; use false para um caminho de busca PDF baseado em texto. |
EpubConfig | EPUB | true | Renderização nativa; false usa PDF. |
MhtConfig | MHT, MHTML | true na classe; false no catálogo automático | A abertura normal sem configuração usa o redirecionamento PDF pesquisável. Uma instância padrão explicitamente construída renderiza nativamente. |
XpsConfig | XPS | false | Usa o caminho PDF por padrão; defina true para renderização nativa de imagem. |
Exemplos de configuração por família
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
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?