ViewerConfig

클라이언트 뷰어 위젯 옵션

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

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

C# 속성

형식속성기본값설명
boolShowThumbstrue썸네일 패널을 표시합니다.
boolAutoLoadfalse초기화 후 자동으로 로드합니다. 일반 토큰 흐름은 View(token)을 명시적으로 호출합니다.
boolAutoFocustrue초기화 중에 브라우저 포커스/스크롤을 뷰어로 이동합니다.
boolAutoPageFocustrue페이지가 변경되는 동안 현재 썸네일을 보이게 유지합니다.
intPageZoom100초기 확대 비율.
intZoomStep10확대/축소 명령으로 추가하거나 제거되는 비율.
intMaxZoom300최대 확대 비율.
boolShowToolTiptrue스크롤 중에 페이지 위치 툴팁을 표시합니다.
stringToolTipPageText"Page "페이지 툴팁에 사용되는 접두사.
boolCacheEnabledfalse브라우저 메모리에 페이지 이미지의 이동 윈도우를 유지합니다. localStorage를 사용하지 않습니다.
boolLargeDocfalse큰 문서의 경우 페이지 요소를 시간 배치로 추가합니다.
boolShowHyperlinksfalse서버 구성에서 추출된 경우 하이퍼링크 오버레이를 렌더링합니다.
boolFixedZoomtrue반응형 재계산 대신 고정 확대 비율을 사용합니다.
intFixedZoomPercent100고정 데스크톱 확대.
intFixedZoomPercentMobile75고정 모바일 확대.
stringBasePath"/"뷰어가 페이지 요청을 보내는 위치. "/"는 사이트 루트에서 DocImage.axd입니다; 그렇지 않으면 호스트가 UseDoconut()를 매핑하는 분기이며, 선행 / 없이 ("doconut"는 /doconut/DocImage.axd를 의미합니다).
stringResPath"doconut-res/images" (26.9.0; "doconut-res" before)위젯이 자체 이미지를 로드하는 폴더: ResourcesPath 아래의 images 폴더이며, 선행 / 없이.
stringFitType"width""width", "height", 또는 자동 맞춤을 하지 않으려면 비워두세요. 현재 위젯은 "page"를 허용하지 않습니다.
boolRetryOn409false비동기/분산 페이지 생성이 202 Accepted에 응답할 때 폴링을 활성화합니다; 409도 오래된 서버와의 호환성을 위해 허용됩니다. 일반 동기 뷰어에서는 필요하지 않습니다.
csharp
var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // 선행 '/' 없음: 뷰어가 추가합니다 ("/doconut" 은 //doconut, 다른 호스트)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

C#에서 JavaScript 매핑

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

C#JavaScript
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

JavaScript 기본값

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

옵션기본값비고
leftMinWidth / leftMaxWidth220 / 800썸네일 패널 너비 범위.
showThumbstrue초기 썸네일 가시성.
autoFocus / autoPageFocustrue / falseautoPageFocus 은 C# 기본값과 다릅니다.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10픽셀 단위 썸네일 기하학.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom 은 C# (300)와 다릅니다.
showToolTip / toolTipPageTexttrue / "Page "페이지 위치 툴팁.
format / doc / AccessToken"" / 0 / ""내부 초기화 값; 일반적으로 View(token)에 의해 채워집니다.
debugModefalse추가 클라이언트 진단.
FitType""제공되지 않으면 자동 맞춤이 없습니다.
BasePath"DocImage.axd"호환성을 위해 유지된 과거 클라이언트 기본값입니다. 현재 ASP.NET Core 호스트는 매핑된 미들웨어 브랜치에 명시적으로 설정해야 합니다.
ResPath""임베드된 이미지 경로에 명시적으로 설정합니다.
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3메모리 내 페이지 사전 로드 창 및 지연.
autoLoadfalse명시적인 토큰 흐름을 권장합니다.
largeDoctrueC# 기본값과 다릅니다.
fixedZoomfalseC# 기본값과 다릅니다.
fixedZoomPercent / fixedZoomPercentMobile100 / 50모바일 값은 C# (75)와 다릅니다.
showHyperlinkstrue오버레이를 생성하려면 서버 측 추출이 필요합니다.

동작에 중요한 모든 값을 설정하고 기본값에 의존하지 마십시오:

html
<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>

콜백

콜백인수목적
onPageLoadingpageNum페이지 요청이 시작됩니다.
onPageLoadedpageNum페이지 이미지 로드가 완료되었습니다.
onThumbnailClickedpageNum사용자가 썸네일을 선택했습니다.
onPageClickedpageNum사용자가 페이지를 선택했습니다.
onDoubleClicknone뷰어가 더블 클릭을 받았습니다.
onViewerBusynone뷰어가 바쁜 상태에 들어갔습니다.
onViewerReadynone초기화가 완료되었습니다.
onViewerErrornone뷰어가 오류 상태에 들어갔습니다.
onErrormessage작업이 오류 메시지를 반환했습니다.
onCopydata텍스트 복사 데이터가 사용 가능합니다.
onAutoLoadStatuspageNum자동 로딩이 페이지로 진행되었습니다.
onThumbsShownnone썸네일 패널이 표시되었습니다.
onAnnLoadednone주석 데이터가 로드되었습니다.
onAnnSavednone주석 데이터가 저장되었습니다.
onAnnSaveErrornone주석 저장에 실패했습니다.
onAnnClosednone주석 UI가 닫혔습니다.

콜백은 빠르게 유지하고, 텔레메트리를 비동기적으로 전송하며 페이지 렌더링을 차단하지 마십시오.

이 중 모든 항목은 init 객체의 옵션입니다. 이전 뷰어는 컨테이너 ID에서 파생된 이름을 가진 전역 함수를 찾아 사용했습니다 — <div id="div_ctlDoc">가 있는 페이지는 function ctlDoc_OnViewerReady()만 선언하면 되었습니다. 그 조회는 사라졌습니다. 함수를 명시적으로 전달하십시오:

javascript
function ctlDoc_OnViewerBusy() { /* 작업 표시기를 표시합니다 */ }
function ctlDoc_OnViewerReady() { /* 숨깁니다 */ }
function ctlDoc_Copy(text) { /* 복사된 텍스트를 사용합니다 */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* 진행 상황을 보고합니다 */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... 기존 옵션 ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // 이름으로 찾았습니다
    onViewerReady:    ctlDoc_OnViewerReady,     // 이름으로 찾았습니다
    onCopy:           ctlDoc_Copy,              // ctlDoc_Copy(text) 가 실행되었습니다
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // ctlDoc_AutoLoadStatus(page) 가 실행되었습니다
});

이전 조회는 빈 catch에 감싸여 있었기 때문에 아무것도 보고되지 않았습니다. 이번 릴리스에서는 함수가 전혀 실행되지 않습니다: 일반적인 증상은 숨기는 핸들러가 onViewerReady였기 때문에 멈추지 않는 바쁜 스피너입니다. 그 뒤의 문서는 올바르게 렌더링되고 있습니다.

두 개의 주석 저장 훅은 여전히 이름으로 조회됩니다: SaveAnnotations()는 존재할 경우 <elementId>_BeforeAnnSave()와 <elementId>_DeletedAnnotationIds()를 호출하며, 요소의 전체 ID(div_ctlDoc_BeforeAnnSave)를 사용합니다 (위 샘플).

링크 클릭 콜백은 없습니다 — 하이퍼링크 처리는 내장되어 있으며 showHyperlinks에 의해 구동됩니다.

공개 메서드 그룹

그룹공통 메서드
생명주기View(token, accessToken?), Close(server?), Token(), Init(), IsLoaded()
탐색GotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages()
확대 및 맞춤Zoom(zoomIn), CurrentZoom(), FitType(value), Refit()
방향Rotate(page, angle), Flip(page, flipType)
썸네일HideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb)
검색CanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...)
주석SaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...)
복사Copy(...), CopyPage(pageNumber), CopyMode(enabled)

JavaScript 파일에도 내부 헬퍼가 포함되어 있습니다. 여기 또는 기능 가이드에 문서화된 레퍼런스 UI에서 사용되는 메서드만을 안정적인 통합 포인트로 취급하십시오.

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

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

옵션기본값
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

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

FirstPagePriority 로 공유 스토리지에서 페이지를 제공하고, 이후 페이지가 작성될 때까지 정당하게 202 Accepted 에 응답하는 경우 이를 활성화하세요. 재시도하지 않는 클라이언트는 아직 렌더링 중인 페이지에 대해 깨진 타일을 표시합니다 — 분산 배포를 참고하세요.

경로 체크리스트

  • DoconutOptions.MiddlewarePath 은 실제 매핑하는 브랜치를 설명해야 합니다.
  • BasePath 은 해당 브랜치를 대상으로 해야 하며, 선행 / 없이 작성됩니다 ('doconut', '/doconut' 가 아니라: 뷰어가 슬래시를 추가하고, //doconut/... 은 다른 호스트에 대한 요청입니다). 일반적인 설정은 MapWhen 브랜치에서 과거의 DocImage.axd 요청 형태를 유지하므로 BasePath: '/' 을 설정합니다.
  • DoconutOptions.ResourcesPath 은 임베디드 리소스 경로입니다.
  • ResPath 은 일반적으로 선행 / 없이 해당 images 하위 폴더를 대상으로 하며, 기본 접두사와 함께 'doconut-res/images' 합니다. 이전 라이브러리에서는 리소스가 애플리케이션 루트에서 제공되었기 때문에 빈 ResPath 가 올바른 것이었지만, 여기서는 올바르지 않으며 오류 없이 실패합니다.
  • ExtractHyperlinks 은 showHyperlinks 가 어떤 것도 표시하기 전에 서버 포맷 설정에서 활성화되어야 합니다.

이 페이지가 도움이 되었나요?