포맷 구성 – 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`에 위임합니다.

CustomStyleCell은 CustomStyleDateTime, CustomStyleNumberDecimal, CustomStyleNumberInteger를 노출하며, 모두 nullable 문자열입니다.

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`	`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 타이밍은 10 ms 단위입니다.
`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`	네이티브 간트 이미지; `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

네 가지 모두 기본 DPI는 200이며 중첩된 PdfConfig를 노출합니다.

구성	포맷	`DefaultRender`	추가 속성/동작
`HtmlConfig`	HTML, HTM	`true`	네이티브 렌더링; 텍스트 기반 PDF 검색 경로를 사용하려면 `false`로 설정합니다.
`EpubConfig`	EPUB	`true`	네이티브 렌더링; `false`이면 PDF를 사용합니다.
`MhtConfig`	MHT, MHTML	`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 = ["/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
    }
];

확장자별 선택 예시

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