Configurazioni Formato

Opzioni di rendering complete per ogni formato

Ogni documento si apre con un'implementazione BaseConfig. Passane una a OpenDocumentAsync o lascia che il catalogo dei formati crei il suo valore predefinito. Tutte le classi seguenti vivono nello spazio dei nomi Doconut.

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

Ereditarietà e impostazioni PDF nidificate

Ogni formato eredita le cinque proprietà BaseConfig. I formati che possono reindirizzare tramite PDF espongono un PdfConfig nidificato. In WordConfig, ExcelConfig e PptConfig, AllowSearch e AllowCopy sono proprietà di convenienza che leggono e scrivono il PdfConfig nidificato.

DefaultRender = true seleziona il renderer nativo del formato. Nei formati con un reindirizzamento PDF, false converte prima in un PDF in memoria e poi utilizza il visualizzatore PDF. Questo percorso è spesso utile per la ricerca per coordinate di testo, ma comporta una conversione aggiuntiva.

Salvo indicazione contraria, le tabelle mostrano i valori predefiniti di costruttori/proprietà. Il catalogo automatico dei formati sovrascrive deliberatamente due di essi: crea ExcelConfig con SplitWorksheets = true e MhtConfig con DefaultRender = false.

BaseConfig

TipoProprietàPredefinitoComportamento
intImageResolution00 utilizza il valore predefinito del formato. L'intervallo esplicito valido è 25-300 DPI; le assegnazioni non valide vengono ignorate.
stringDocumentCulture""Locale per date e numeri. I valori non vuoti vengono trimmati; le assegnazioni vuote vengono ignorate.
stringPassword""Password del documento protetto. DocOptions.Password viene copiata qui automaticamente.
boolShowUItrueProprietà di compatibilità; il renderer attuale non la utilizza per controllare la barra degli strumenti del browser.
boolCachePagestrueMemorizza nella cache le immagini delle pagine renderizzate per la sessione del documento.

PdfConfig

Formati: PDF. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueInterruttore di compatibilità. La factory attuale utilizza il visualizzatore PDF nativo.
boolAllowSearchfalseCrea/utilizza l'indice di ricerca testuale PDF. Richiede la capacità di licenza Search per le richieste.
boolAllowCopyfalseConsente operazioni di selezione/copia del testo.
boolExtractHyperlinksfalseEstrae i rettangoli dei collegamenti per le sovrapposizioni client.
intHyperlinksPageCount0Numero massimo di pagine scansionate per i collegamenti; 0 significa tutte le pagine.
boolCompressImagesfalseComprimi le immagini incorporate prima del rendering.
intCompressQuality100Qualità JPEG usata quando la compressione è abilitata.
boolResizeImagesfalseRidimensiona le immagini incorporate prima del rendering.
intResizeResolution300DPI target per le immagini ridimensionate.
boolCompressFastfalsePreferisci il percorso di compressione più veloce e di qualità inferiore.
boolFixInvalidImagesfalseTentativo di riparare le immagini incorporate non valide.
boolSplitSegmentsfalseRiunisci parole divise tra segmenti di linea per migliorare ricerca/copia.

showHyperlinks in ViewerConfig controlla la sovrapposizione client, mentre ExtractHyperlinks controlla l'estrazione server. Abilita entrambi.

WordConfig

Formati: DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, XML. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueRender nativo Word; false utilizza il reindirizzamento PDF.
PdfConfigPdfConfignew instanceImpostazioni usate dal percorso PDF/ricerca.
DocPaperSizePaperSizeA4Dimensione della carta di output. Usa Custom con larghezza/altezza.
intPaperWidth595Larghezza personalizzata in punti.
intPaperHeight841Altezza personalizzata in punti.
boolRemovePaperMarginfalseRimuovi i margini della pagina del documento.
boolRenderPageColortruePreserva il colore della pagina configurato in Word; false rende pagine bianche.
boolExportPdfAfalseUsa PDF/A archivistico nel percorso PDF.
Encoding?FileEncodingnullSovrascrivi la codifica di origine.
stringFontInfo""Informazioni sulla sostituzione dei font.
string[]?FontFoldersnullDirectory di font aggiuntive, particolarmente utili in Linux/container.
boolAllowSearchfalseDelega a PdfConfig.AllowSearch.
boolAllowCopyfalseDelega a PdfConfig.AllowCopy.
TableAutoFitBehaviorAutoFitAllTablesNoneNone, AutoFitToContents o AutoFitToWindow.

ExcelConfig

Formati: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueRendering nativo del foglio; false utilizza il reindirizzamento PDF.
PdfConfigPdfConfignuova istanzaImpostazioni per il percorso PDF/ricerca.
ExcelPaperSizePaperSizePaperA4Dimensione della carta di output.
doublePaperMargins0.25Margini della pagina in pollici.
boolPaperLandscapetrueRendering del foglio in orizzontale.
boolAutoFitContentsfalseAdattamento automatico dell'altezza delle righe e della larghezza delle colonne.
boolRemoveEmptyContenttrueStringere l'output escludendo contenuti vuoti.
boolCalculateFormulatrueRicalcolare le formule prima del rendering.
boolShowRowColumnHeaderstrueIncludere le intestazioni del foglio di calcolo.
boolExportPdfAfalseUsare PDF/A nel percorso PDF.
boolSplitWorksheetsfalseMantenere i fogli di lavoro come gruppi di pagine separati.
boolShowEmptyWorkSheetsfalseIncludere fogli di lavoro vuoti.
boolExportLandscapefalseForzare l'esportazione in orizzontale.
boolExportOnePagePerSheetfalseAdattare ogni foglio di lavoro a una pagina di output.
boolMemoryOptimizationPreferencetrueRidurre la memoria di picco, potenzialmente sacrificando un po' di velocità.
boolAutoTrimWorksheetRenderRangetrueRenderizzare solo l'intervallo usato visibile quando non esiste un'area di stampa esplicita.
boolAutoTrimPreserveExistingPrintAreatruePreservare le aree di stampa definite nella cartella di lavoro durante il ritaglio automatico.
string?PrintAreanullIntervallo esplicito come "A1:Z100".
boolPrintGridlinesfalseStampare le linee della griglia del foglio di lavoro.
boolPrintHeadingsfalseStampare le intestazioni di righe/colonne.
List<string>SheetNamesvuotoLimitare il rendering ai fogli di lavoro nominati.
CustomStyleCell?CustomStylesnullSovrascritture opzionali di formattazione data/decimale/intero.
boolAllowSearchfalseDelega a PdfConfig.AllowSearch.
boolAllowCopyfalseDelega a PdfConfig.AllowCopy.

CustomStyleCell espone CustomStyleDateTime, CustomStyleNumberDecimal e CustomStyleNumberInteger, tutte stringhe nullable.

new ExcelConfig() imposta SplitWorksheets a false; aprire un file Excel senza una configurazione esplicita utilizza il catalogo dei formati, che lo imposta a true.

PptConfig

Formati: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueRendering nativo della diapositiva; false utilizza il reindirizzamento PDF.
boolFastLoadfalseEvitare il rendering della prima diapositiva durante l'apertura; usare i metadati e renderizzare su richiesta.
PdfConfigPdfConfignuova istanzaImpostazioni per il comportamento PDF/ricerca.
stringFontInfo""Informazioni sulla sostituzione dei font.
string[]?FontFoldersnullDirectory dei font aggiuntive.
boolAllowSearchfalseDelega a PdfConfig.AllowSearch.
boolAllowCopyfalseDelega a PdfConfig.AllowCopy.

Le pagine sono disegnate con i font installati sul server. Su Linux, installa i font usati dalle presentazioni o punta FontFolders verso di essi: un font mancante viene sostituito senza errore, quindi le interruzioni di riga possono differire da Windows. fonts-liberation, fonts-crosextra-carlito e fonts-crosextra-caladea forniscono sostituti metricamente compatibili per i comuni font Windows. Linux ha bisogno solo di libfontconfig1 (libgdiplus non è richiesto).

CadConfig

Formati: DWG, DXF, DGN. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueRendering nativo CAD; false utilizza il reindirizzamento PDF.
PdfConfigPdfConfignuova istanzaImpostazioni del percorso PDF.
boolExportPdfAfalseOutput PDF/A di archivio.
boolShowColortrueColore anziché monocromatico.
boolWhiteBackgroundtrueSfondo bianco invece di nero.
shortLineWidth25Larghezza del tratto CAD.
boolShowLayoutsfalseRenderizzare le schede di layout.
boolShowModeltrueRenderizzare lo spazio modello.
boolCheck3DSolidtrueElaborare solidi 3D.
boolExportAllLayoutsfalseEsportare tutti i layout, sovrascrivendo la selezione modello/layout.
boolLimitMinimumSizefalseApplicare MinimumSize.
intMinimumSize700Dimensione minima di output in pixel.
boolLimitMaximumSizefalseApplicare MaximumSize.
intMaximumSize700Dimensione massima di output in pixel.
boolShowAllLayoutsDgnfalseIncludere tutti i layout DGN.
boolAutomaticLayoutScalingtrueRidimensionare automaticamente i layout.
floatPdfMargins0.5Margine PDF in pollici.
RenderQualityQualityImageLowQualità raster: Low, Medium o High.
RenderQualityQualityTextMediumQualità del testo: Low, Medium o High.

EmailConfig

Formati: EML, EMLX, MSG. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueRendering nativo dell'email; false utilizza il reindirizzamento PDF.
PdfConfigPdfConfignuova istanzaImpostazioni del percorso PDF.
Encoding?EmailEncodingnullSovrascrivi la codifica del messaggio.
Encoding?SubjectEncodingnullSovrascrivi la codifica dell'oggetto.
Encoding?BodyEncodingnullSovrascrivi la codifica del corpo.
boolSkipExternalImagesfalseNon caricare immagini referenziate remotamente. Consigliato per email non attendibili.
boolRemoveLastWhitePagefalseRimuovi una pagina vuota finale.
boolUseAntiAliasingfalseAbilita l'anti-aliasing.
boolUseHighQualityRenderingfalsePreferisci un rendering più pulito e più lento.
TimeSpan?TimeZoneOffsetnullSovrascrivi il fuso orario usato per le date.
boolForcePageSizefalseForza dimensioni di pagina fisse.

ImageConfig, TiffConfig e PsdConfig

ImageConfig copre JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF e SVG. Il suo DPI predefinito è 100.

ConfigurazioneProprietàPredefinitoComportamento
ImageConfigMaxImagePixelSize3000Larghezza/altezza massima. 0 significa illimitato; i valori diversi da zero inferiori a 50 sono ignorati.
ImageConfigTransparentPngtruePreserva la trasparenza PNG; false utilizza uno sfondo bianco.
TiffConfignessuna proprietà aggiuntivaDPI 200Utilizza solo BaseConfig; supporta TIFF multi-pagina.
PsdConfigMaxImagePixelSize3000Stessa validazione 0/minimum-50 di ImageConfig; il DPI predefinito è 100.

DicomConfig

Formati: DCM, IMA. DPI efficace predefinito: 100. Richiede il plugin DICOM. In questo pacchetto i file DICOM vengono renderizzati completamente, ma i metadati tecnici non sono disponibili — vedi Plugin DICOM.

TipoProprietàPredefinitoComportamento
intHorizontalResolution100 efficaceDPI orizzontale esplicito; altrimenti ImageResolution, poi 100.
intVerticalResolution100 efficaceDPI verticale esplicito; altrimenti ImageResolution, poi 100.
intAnimationFrameDelayMs100Ritardo animazione multiframe; il timing GIF utilizza unità di 10 ms.
ushortLoopCount00 ripete all'infinito; i valori positivi si fermano dopo quel conteggio.
DicomDisplayModeDisplayModeAnimationAndFramesAnimationOnly, FramesOnly, o panoramica combinata più fotogrammi statici.

TxtConfig

Formato: TXT. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
DocPaperSizePaperSizeA4Dimensione carta di output.
Encoding?FileEncodingnullnull utilizza UTF-8.
stringFontInformation""Informazioni sul font per il rendering del testo.

Usa WordConfig quando il testo semplice necessita di un comportamento di layout di pagina più ricco.

ProjectConfig

Formati: MPP, MPPX, MPX. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueImmagine Gantt nativa; false utilizza un percorso PDF basato su testo.
PdfConfigPdfConfignuova istanzaImpostazioni del percorso PDF.
boolExportPdfAtrueOutput PDF/A d'archivio.
MppPaperSizePaperSizeLedgerDimensione carta di output del progetto.
MppTimeScaleTimeScaleMonthsDays o Months.
MppFormatPresentationFormatGanttChartGanttChart, TaskUsage, ResourceUsage, ResourceSheet, o TaskSheet.

Per una ricerca esatta per coordinate di testo, usa DefaultRender = false.

VisioConfig

Formati: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. DPI predefinito: 200.

TipoProprietàPredefinitoComportamento
boolDefaultRendertrueRendering nativo del diagramma; false utilizza il reindirizzamento PDF.
PdfConfigPdfConfignuova istanzaImpostazioni del percorso PDF.
boolExportPdfAtrueOutput PDF/A d'archivio.

HtmlConfig, EpubConfig, MhtConfig e XpsConfig

Tutti e quattro hanno come DPI predefinito 200 e espongono un PdfConfig annidato.

ConfigurazioneFormatiDefaultRenderProprietà/comportamento aggiuntivi
HtmlConfigHTML, HTMtrueRendering nativo; usa false per un percorso di ricerca PDF basato su testo.
EpubConfigEPUBtrueRendering nativo; false utilizza PDF.
MhtConfigMHT, MHTMLtrue sulla classe; false nel catalogo automaticoL'apertura normale senza configurazione utilizza il reindirizzamento PDF ricercabile. Un'istanza predefinita costruita esplicitamente rende nativamente.
XpsConfigXPSfalseUtilizza il percorso PDF per impostazione predefinita; imposta true per il rendering nativo dell'immagine.

Esempi di configurazione per famiglia

csharp
BaseConfig[] configs =
{
    new PdfConfig
    {
        AllowSearch = true,
        ExtractHyperlinks = true,
        HyperlinksPageCount = 0
    },
    new WordConfig
    {
        PaperSize = DocPaperSize.A4,
        RemovePaperMargin = false,
        FontFolders = new[] { "/usr/share/fonts/truetype" },
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = new[] { "/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
    }
};

Selezione per estensione

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 → reindirizzamento PDF → ricerca di testo nativa a pixel preciso
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // ripristina la configurazione predefinita del formato
};

Questa pagina è stata utile?