포맷 구성 – Doconut 문서

모든 문서는 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 뷰어를 사용합니다. 이 경로는 텍스트 좌표 검색에 유용하지만 추가 변환 비용이 발생합니다.

별도로 명시되지 않는 한, 표는 생성자/속성 기본값을 보여줍니다. 자동 포맷 카탈로그는 의도적으로 두 값을 재정의합니다: ExcelConfig를 SplitWorksheets = true로 생성하고, MhtConfig를 DefaultRender = false로 생성합니다.

BaseConfig

유형	속성	기본값	동작
`int`	`ImageResolution`	`0`	`0`은 포맷 기본값을 사용합니다. 유효한 명시적 범위는 25-300 DPI이며, 유효하지 않은 할당은 무시됩니다.
`string`	`DocumentCulture`	`""`	날짜와 숫자의 로케일입니다. 비공백 값은 트림되고, 공백 할당은 무시됩니다.
`string`	`Password`	`""`	보호된 문서 비밀번호입니다. `DocOptions.Password`가 자동으로 복사됩니다.
`bool`	`ShowUI`	`true`	호환성 속성; 현재 렌더러는 브라우저 툴바 제어에 사용하지 않습니다.
`bool`	`CachePages`	`true`	문서 세션 동안 렌더링된 페이지 이미지를 캐시합니다.

PdfConfig

포맷: PDF. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	호환성 스위치. 현재 팩토리는 기본 PDF 뷰어를 사용합니다.
`bool`	`AllowSearch`	`false`	PDF 텍스트 검색 인덱스를 구축/사용합니다. 요청에 Search 라이선스 기능이 필요합니다.
`bool`	`AllowCopy`	`false`	텍스트 선택/복사 작업을 허용합니다.
`bool`	`ExtractHyperlinks`	`false`	클라이언트 오버레이용 링크 사각형을 추출합니다.
`int`	`HyperlinksPageCount`	`0`	링크를 스캔할 최대 페이지 수; `0`은 모든 페이지를 의미합니다.
`bool`	`CompressImages`	`false`	렌더링 전에 포함된 이미지를 압축합니다.
`int`	`CompressQuality`	`100`	압축이 활성화될 때 사용되는 JPEG 품질.
`bool`	`ResizeImages`	`false`	렌더링 전에 포함된 이미지를 크기 조정합니다.
`int`	`ResizeResolution`	`300`	크기 조정된 이미지의 목표 DPI.
`bool`	`CompressFast`	`false`	더 빠르고 품질이 낮은 압축 경로를 선호합니다.
`bool`	`FixInvalidImages`	`false`	잘못된 포함 이미지 수리를 시도합니다.
`bool`	`SplitSegments`	`false`	검색/복사를 개선하기 위해 줄 구간에 걸쳐 분할된 단어를 다시 결합합니다.

ViewerConfig의 showHyperlinks는 클라이언트 오버레이를 제어하고, ExtractHyperlinks는 서버 추출을 제어합니다. 두 옵션을 모두 활성화하세요.

WordConfig

포맷: DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, XML. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 Word 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF/검색 경로에 사용되는 설정.
`DocPaperSize`	`PaperSize`	`A4`	출력 용지 크기. 너비/높이와 함께 `Custom`을 사용합니다.
`int`	`PaperWidth`	`595`	포인트 단위의 사용자 정의 너비.
`int`	`PaperHeight`	`841`	포인트 단위의 사용자 정의 높이.
`bool`	`RemovePaperMargin`	`false`	문서 페이지 여백을 제거합니다.
`bool`	`RenderPageColor`	`true`	Word에 설정된 페이지 색상을 유지합니다; `false`는 흰색 페이지를 렌더링합니다.
`bool`	`ExportPdfA`	`false`	PDF 경로에서 보관용 PDF/A를 사용합니다.
`Encoding?`	`FileEncoding`	`null`	소스 인코딩을 재정의합니다.
`string`	`FontInfo`	`""`	폰트 대체 정보.
`string[]?`	`FontFolders`	`null`	추가 폰트 디렉터리, 특히 Linux/컨테이너에서 유용합니다.
`bool`	`AllowSearch`	`false`	`PdfConfig.AllowSearch`에 위임합니다.
`bool`	`AllowCopy`	`false`	`PdfConfig.AllowCopy`에 위임합니다.
`TableAutoFitBehavior`	`AutoFitAllTables`	`None`	`None`, `AutoFitToContents`, `AutoFitToWindow` 중 하나.

ExcelConfig

포맷: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 시트 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF/검색 경로에 대한 설정.
`ExcelPaperSize`	`PaperSize`	`PaperA4`	출력 용지 크기.
`double`	`PaperMargins`	`0.25`	인치 단위 페이지 여백.
`bool`	`PaperLandscape`	`true`	가로 시트 렌더링.
`bool`	`AutoFitContents`	`false`	행 높이와 열 너비를 자동 맞춤합니다.
`bool`	`RemoveEmptyContent`	`true`	빈 콘텐츠를 제외하여 출력 압축.
`bool`	`CalculateFormula`	`true`	렌더링 전에 수식을 재계산합니다.
`bool`	`ShowRowColumnHeaders`	`true`	스프레드시트 헤더 포함.
`bool`	`ExportPdfA`	`false`	PDF 경로에서 PDF/A 사용.
`bool`	`SplitWorksheets`	`false`	워크시트를 별도 페이지 그룹으로 유지합니다.
`bool`	`ShowEmptyWorkSheets`	`false`	빈 워크시트 포함.
`bool`	`ExportLandscape`	`false`	가로 내보내기 강제.
`bool`	`ExportOnePagePerSheet`	`false`	각 워크시트를 하나의 출력 페이지에 맞춥니다.
`bool`	`MemoryOptimizationPreference`	`true`	피크 메모리를 줄이며, 속도가 약간 감소할 수 있습니다.
`bool`	`AutoTrimWorksheetRenderRange`	`true`	명시적 인쇄 영역이 없을 때 사용된 가시 범위만 렌더링합니다.
`bool`	`AutoTrimPreserveExistingPrintArea`	`true`	자동 트림 중에 워크북 정의 인쇄 영역을 보존합니다.
`string?`	`PrintArea`	`null`	`"A1:Z100"`와 같은 명시적 범위.
`bool`	`PrintGridlines`	`false`	워크시트 격자선 인쇄.
`bool`	`PrintHeadings`	`false`	행/열 헤더 인쇄.
`List<string>`	`SheetNames`	empty	지정된 워크시트 이름으로 렌더링 제한.
`CustomStyleCell?`	`CustomStyles`	`null`	선택적 날짜/소수/정수 서식 재정의.
`bool`	`AllowSearch`	`false`	`PdfConfig.AllowSearch`에 위임합니다.
`bool`	`AllowCopy`	`false`	`PdfConfig.AllowCopy`에 위임합니다.

new ExcelConfig()는 SplitWorksheets를 false로 설정합니다; 명시적 구성이 없는 Excel 파일을 열면 포맷 카탈로그가 이를 true로 설정합니다.

PptConfig

포맷: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 슬라이드 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`bool`	`FastLoad`	`false`	열 때 첫 슬라이드 렌더링을 피하고 메타데이터를 사용해 필요 시 렌더링합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF/검색 동작에 대한 설정.
`string`	`FontInfo`	`""`	폰트 대체 정보.
`string[]?`	`FontFolders`	`null`	추가 폰트 디렉터리.
`bool`	`AllowSearch`	`false`	`PdfConfig.AllowSearch`에 위임합니다.
`bool`	`AllowCopy`	`false`	`PdfConfig.AllowCopy`에 위임합니다.

Linux 및 macOS에서 현재 엔진으로 프레젠테이션을 렌더링하려면 libgdiplus와 System.Drawing.EnableUnixSupport=true가 필요합니다. 프레젠테이션에 사용되는 폰트를 설치하거나 FontFolders를 제공하세요.

CadConfig

포맷: DWG, DXF, DGN. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 CAD 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF 경로 설정.
`bool`	`ExportPdfA`	`false`	보관용 PDF/A 출력.
`bool`	`ShowColor`	`true`	흑백이 아닌 컬러.
`bool`	`WhiteBackground`	`true`	검은색 대신 흰색 배경.
`short`	`LineWidth`	`25`	CAD 선 굵기.
`bool`	`ShowLayouts`	`false`	레이아웃 탭 렌더링.
`bool`	`ShowModel`	`true`	모델 공간 렌더링.
`bool`	`Check3DSolid`	`true`	3D 솔리드 처리.
`bool`	`ExportAllLayouts`	`false`	모델/레이아웃 선택을 무시하고 모든 레이아웃을 내보냅니다.
`bool`	`LimitMinimumSize`	`false`	`MinimumSize` 적용.
`int`	`MinimumSize`	`700`	최소 출력 크기(픽셀).
`bool`	`LimitMaximumSize`	`false`	`MaximumSize` 적용.
`int`	`MaximumSize`	`700`	최대 출력 크기(픽셀).
`bool`	`ShowAllLayoutsDgn`	`false`	모든 DGN 레이아웃 포함.
`bool`	`AutomaticLayoutScaling`	`true`	레이아웃을 자동으로 스케일링합니다.
`float`	`PdfMargins`	`0.5`	인치 단위 PDF 여백.
`RenderQuality`	`QualityImage`	`Low`	래스터 품질: `Low`, `Medium`, `High`.
`RenderQuality`	`QualityText`	`Medium`	텍스트 품질: `Low`, `Medium`, `High`.

EmailConfig

포맷: EML, EMLX, MSG. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 이메일 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF 경로 설정.
`Encoding?`	`EmailEncoding`	`null`	메시지 인코딩 재정의.
`Encoding?`	`SubjectEncoding`	`null`	제목 인코딩 재정의.
`Encoding?`	`BodyEncoding`	`null`	본문 인코딩 재정의.
`bool`	`SkipExternalImages`	`false`	원격 이미지 로드를 하지 않습니다. 신뢰할 수 없는 이메일에 권장됩니다.
`bool`	`RemoveLastWhitePage`	`false`	끝에 있는 빈 페이지를 제거합니다.
`bool`	`UseAntiAliasing`	`false`	안티앨리어싱 활성화.
`bool`	`UseHighQualityRendering`	`false`	깨끗하지만 느린 렌더링을 선호합니다.
`TimeSpan?`	`TimeZoneOffset`	`null`	날짜에 사용되는 시간대를 재정의합니다.
`bool`	`ForcePageSize`	`false`	고정 페이지 크기 강제.

ImageConfig, TiffConfig, and PsdConfig

ImageConfig는 JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF, SVG를 포함합니다. 기본 DPI는 100입니다.

구성	속성	기본값	동작
`ImageConfig`	`MaxImagePixelSize`	`3000`	최대 너비/높이. `0`은 무제한; 50 미만의 0이 아닌 값은 무시됩니다.
`ImageConfig`	`TransparentPng`	`true`	PNG 투명도 유지; `false`는 흰색 배경 사용.
`TiffConfig`	추가 속성 없음	DPI `200`	추가 속성 없음. DPI `200`. `BaseConfig`만 사용; 다중 페이지 TIFF 지원.
`PsdConfig`	`MaxImagePixelSize`	`3000`	`ImageConfig`와 동일한 `0`/최소 50 검증; 기본 DPI는 `100`.

DicomConfig

포맷: DCM, IMA. 기본 유효 DPI: 100. DICOM 플러그인이 필요합니다.

유형	속성	기본값	동작
`int`	`HorizontalResolution`	`100` effective	명시적 가로 DPI; 없으면 `ImageResolution`, 그 다음 100.
`int`	`VerticalResolution`	`100` effective	명시적 세로 DPI; 없으면 `ImageResolution`, 그 다음 100.
`int`	`AnimationFrameDelayMs`	`100`	다중 프레임 애니메이션 지연; GIF 타이밍은 10ms 단위 사용.
`ushort`	`LoopCount`	`0`	`0`은 무한 반복; 양수 값은 해당 횟수 후 중지.
`DicomDisplayMode`	`DisplayMode`	`AnimationAndFrames`	`AnimationOnly`, `FramesOnly`, 또는 개요와 정적 프레임을 결합한 모드.

TxtConfig

포맷: TXT. 기본 DPI: 200.

유형	속성	기본값	동작
`DocPaperSize`	`PaperSize`	`A4`	출력 용지 크기.
`Encoding?`	`FileEncoding`	`null`	`null`은 UTF-8 사용.
`string`	`FontInformation`	`""`	텍스트 렌더링을 위한 폰트 정보.

플레인 텍스트에 더 풍부한 페이지 레이아웃 동작이 필요할 때 WordConfig를 사용하세요.

ProjectConfig

포맷: MPP, MPPX, MPX. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 Gantt 이미지; `false`는 텍스트 기반 PDF 경로 사용.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF 경로 설정.
`bool`	`ExportPdfA`	`true`	보관용 PDF/A 출력.
`MppPaperSize`	`PaperSize`	`Ledger`	프로젝트 출력 용지 크기.
`MppTimeScale`	`TimeScale`	`Months`	`Days` 또는 `Months`.
`MppFormat`	`PresentationFormat`	`GanttChart`	`GanttChart`, `TaskUsage`, `ResourceUsage`, `ResourceSheet`, `TaskSheet` 중 하나.

정확한 텍스트 좌표 검색을 위해 DefaultRender = false를 사용하세요.

VisioConfig

포맷: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 다이어그램 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF 경로 설정.
`bool`	`ExportPdfA`	`true`	보관용 PDF/A 출력.

HtmlConfig, EpubConfig, MhtConfig, and XpsConfig

네 개 모두 기본값은 200 DPI이며 중첩된 PdfConfig를 노출합니다.

구성	포맷	`DefaultRender`	추가 속성/동작
`HtmlConfig`	HTML, HTM	`true`	네이티브 렌더링; 텍스트 기반 PDF 검색 경로를 위해 `false` 사용.
`EpubConfig`	EPUB	`true`	네이티브 렌더링; `false`는 PDF 사용.
`MhtConfig`	MHT, MHTML	클래스에서는 `true`; 자동 카탈로그에서는 `false`	클래스에서는 `true`; 자동 카탈로그에서는 `false`. 기본 설정 없이 열면 검색 가능한 PDF 리다이렉트를 사용합니다. 명시적으로 생성된 기본 인스턴스는 네이티브 렌더링합니다.
`XpsConfig`	XPS	`false`	기본적으로 PDF 경로 사용; 네이티브 이미지 렌더링을 위해 `true`로 설정.

구성 예시 (패밀리별)

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

확장자별 선택

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 redirect → pixel-accurate native text search
    ".HTML" or ".HTM" => new HtmlConfig { DefaultRender = false },
    ".EML" or ".EMLX" or ".MSG" => new EmailConfig { DefaultRender = false },
    _ => null // fall back to the format's default config
};