ViewerConfig

ViewerConfig (namespace Doconut)는 브라우저 뷰어의 외관과 동작을 설명합니다. 문서 렌더링 품질에는 영향을 주지 않으며, 이를 위해서는 포맷 설정을 사용하십시오. C# 클래스와 오랜 역사를 가진 JavaScript 위젯은 기본값이 다르므로 값을 명시적으로 매핑해야 합니다.

이 릴리스의 두 클라이언트‑사이드 변경 사항은 조용히 실패합니다. 핸들러 함수는 옵션으로 전달되며 — 위젯은 더 이상 컨테이너 ID에서 전역 함수 이름을 유도하지 않으며 — ResPath는 애플리케이션 루트가 아니라 리소스 접두사 를 가리켜야 합니다. 두 경우 모두 서버는 정상적으로 작동하고 브라우저 콘솔에는 아무것도 보고되지 않습니다. 이전 라이브러리에서 페이지를 이어받는 경우, 먼저 콜백과 경로 체크리스트를 읽어 보세요.

C# 속성

var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "/doconut",
    ResPath = "/doconut-res/images",
    ShowHyperlinks = true
};

C#에서 JavaScript 매핑

직접 직렬화된 ViewerConfig를 docViewer(...)에 전달하지 마세요. 대부분의 위젯 키는 camelCase이며, 세 개의 경로/맞춤 키는 PascalCase입니다.

JavaScript 기본값

위젯은 C# 클래스와 다른 오래된 기본값을 가지고 있습니다. 아래 값들은 현재 docViewer.js 구현에서 가져온 것입니다.

동작에 중요한 값들은 기본값에 의존하지 말고 명시적으로 설정하세요:

<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    autoFocus: true,
    autoPageFocus: true,
    pageZoom: 100,
    zoomStep: 10,
    maxZoom: 300,
    FitType: 'width',
    cacheEnabled: false,
    largeDoc: false,
    showHyperlinks: true,
    fixedZoom: true,
    fixedZoomPercent: 100,
    fixedZoomPercentMobile: 75,
    BasePath: '/doconut',
    ResPath: '/doconut-res/images',
    onViewerReady: function () {},
    onError: function (message) { console.error('DocViewer:', message); }
});
</script>

콜백

콜백은 빠르게 처리하고, 텔레메트리를 비동기로 전송하며 페이지 렌더링을 차단하지 않도록 하세요.

이들 각각은 초기화 객체의 옵션입니다. 이전 뷰어는 컨테이너 ID에서 파생된 전역 함수 이름을 찾아 사용했으며, <div id="div_ctlDoc">가 있을 경우 function ctlDoc_OnViewerReady()와 같은 함수를 선언해야 했습니다. 이 조회 로직은 사라졌습니다. 함수를 명시적으로 전달하세요:

objctlDoc = $('#div_ctlDoc').docViewer({
    // ... 기존 옵션 ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // 이름으로 찾던 것이 사라짐
    onViewerReady:    ctlDoc_OnViewerReady,     // 이름으로 찾던 것이 사라짐
    onCopy:           ctlDoc_Copy,              // 이전에는 ctlDoc_Copy(text) 형태
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // 이전에는 ctlDoc_AutoLoadStatus(page) 형태
});

예전 조회는 빈 catch로 감싸져 있었기 때문에 아무것도 보고되지 않았습니다. 이번 릴리스에서는 함수가 전혀 실행되지 않으며, 흔히 나타나는 증상은 onViewerReady가 숨겨야 할 스피너를 멈추지 않아 바쁜 스피너가 영원히 돌아가는 것입니다. 실제 문서는 정상적으로 렌더링됩니다.

링크 클릭 콜백은 존재하지 않습니다 — 하이퍼링크 처리는 showHyperlinks에 의해 내장되어 있습니다.

공개 메서드 그룹

JavaScript 파일에는 내부 헬퍼도 포함되어 있습니다. 여기서 문서화된 메서드와 레퍼런스 UI에서 사용되는 메서드만을 안정적인 통합 지점으로 간주하십시오.

분산 페이지가 아직 렌더링 중일 때 재시도

retryOn409는 과거 이름을 그대로 유지합니다. 비동기 페이지 생성에 사용되며 현재 202 Accepted 응답과 이전 409 Conflict 신호를 모두 재시도합니다. 활성화하면 위젯은 다음 JavaScript 기본값으로 폴링합니다:

단일 노드 뷰어에서는 비활성화된 상태를 유지하세요. 이를 활성화해도 지원되지 않는 동기 렌더링을 비동기로 바꿀 수는 없습니다.

페이지가 FirstPagePriority와 함께 공유 스토리지에서 제공되는 경우, 이후 페이지가 202 Accepted를 반환할 때까지 재시도하도록 설정하세요. 재시도하지 않는 클라이언트는 아직 렌더링 중인 페이지에 대해 깨진 타일을 표시합니다 — 자세한 내용은 Distributed Deployments를 참고하세요.

경로 체크리스트

• DoconutOptions.MiddlewarePath는 실제로 매핑하는 브랜치를 설명해야 합니다.
• BasePath는 해당 브랜치를 가리켜야 합니다. 레퍼런스 애플리케이션은 MapWhen 브랜치에서 과거 DocImage.axd 요청 형태를 유지하므로 BasePath: '/'를 설정합니다.
• DoconutOptions.ResourcesPath는 임베디드 리소스 라우트입니다.
• ResPath는 일반적으로 /images 하위 폴더를 가리키며 — 기본 접두사와 함께 'doconut-res/images'가 됩니다. 이전 라이브러리에서는 빈 ResPath가 올바른 설정이었지만, 여기서는 올바르지 않으며 오류 없이 실패합니다.
• ExtractHyperlinks는 showHyperlinks가 무언가를 표시하기 전에 서버 포맷 설정에서 활성화되어야 합니다.