ViewerConfig
클라이언트 뷰어 위젯 옵션
ViewerConfig (namespace Doconut)는 브라우저 뷰어의 외관과 동작을 설명합니다. 이는 문서 렌더링 품질에 영향을 주지 않으며, 해당 목적을 위해서는 포맷 구성을 사용하십시오. C# 클래스와 오랫동안 사용되어 온 JavaScript 위젯은 기본값이 다르므로 값을 명시적으로 매핑해야 합니다.
이번 릴리스에서 두 가지 클라이언트 측 변경 사항이 조용히 실패합니다. 핸들러 함수는 옵션으로 전달되며 — 위젯은 이제 컨테이너 ID에서 이벤트 콜백을 파생하지 않습니다 — 그리고
ResPath는 애플리케이션 루트가 아니라 리소스 접두사를 가리켜야 합니다. 두 경우 모두 서버는 정상적으로 작동하지만 브라우저 콘솔에는 아무런 보고도 없습니다. 이전 라이브러리에서 페이지를 이어받고 있다면, 먼저 콜백 및 경로 체크리스트를 읽으세요.
C# 속성
| 형식 | 속성 | 기본값 | 설명 |
|---|---|---|---|
bool | ShowThumbs | true | 썸네일 패널을 표시합니다. |
bool | AutoLoad | false | 초기화 후 자동으로 로드합니다. 일반 토큰 흐름은 View(token)을 명시적으로 호출합니다. |
bool | AutoFocus | true | 초기화 중에 브라우저 포커스/스크롤을 뷰어로 이동합니다. |
bool | AutoPageFocus | true | 페이지가 변경되는 동안 현재 썸네일을 보이게 유지합니다. |
int | PageZoom | 100 | 초기 확대 비율. |
int | ZoomStep | 10 | 확대/축소 명령으로 추가하거나 제거되는 비율. |
int | MaxZoom | 300 | 최대 확대 비율. |
bool | ShowToolTip | true | 스크롤 중에 페이지 위치 툴팁을 표시합니다. |
string | ToolTipPageText | "Page " | 페이지 툴팁에 사용되는 접두사. |
bool | CacheEnabled | false | 브라우저 메모리에 페이지 이미지의 이동 윈도우를 유지합니다. localStorage를 사용하지 않습니다. |
bool | LargeDoc | false | 큰 문서의 경우 페이지 요소를 시간 배치로 추가합니다. |
bool | ShowHyperlinks | false | 서버 구성에서 추출된 경우 하이퍼링크 오버레이를 렌더링합니다. |
bool | FixedZoom | true | 반응형 재계산 대신 고정 확대 비율을 사용합니다. |
int | FixedZoomPercent | 100 | 고정 데스크톱 확대. |
int | FixedZoomPercentMobile | 75 | 고정 모바일 확대. |
string | BasePath | "/" | 뷰어가 페이지 요청을 보내는 위치. "/"는 사이트 루트에서 DocImage.axd입니다; 그렇지 않으면 호스트가 UseDoconut()를 매핑하는 분기이며, 선행 / 없이 ("doconut"는 /doconut/DocImage.axd를 의미합니다). |
string | ResPath | "doconut-res/images" (26.9.0; "doconut-res" before) | 위젯이 자체 이미지를 로드하는 폴더: ResourcesPath 아래의 images 폴더이며, 선행 / 없이. |
string | FitType | "width" | "width", "height", 또는 자동 맞춤을 하지 않으려면 비워두세요. 현재 위젯은 "page"를 허용하지 않습니다. |
bool | RetryOn409 | false | 비동기/분산 페이지 생성이 202 Accepted에 응답할 때 폴링을 활성화합니다; 409도 오래된 서버와의 호환성을 위해 허용됩니다. 일반 동기 뷰어에서는 필요하지 않습니다. |
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 |
|---|---|
ShowThumbs | showThumbs |
AutoLoad | autoLoad |
AutoFocus | autoFocus |
AutoPageFocus | autoPageFocus |
PageZoom | pageZoom |
ZoomStep | zoomStep |
MaxZoom | maxZoom |
ShowToolTip | showToolTip |
ToolTipPageText | toolTipPageText |
CacheEnabled | cacheEnabled |
LargeDoc | largeDoc |
ShowHyperlinks | showHyperlinks |
FixedZoom | fixedZoom |
FixedZoomPercent | fixedZoomPercent |
FixedZoomPercentMobile | fixedZoomPercentMobile |
BasePath | BasePath |
ResPath | ResPath |
FitType | FitType |
RetryOn409 | retryOn409 |
JavaScript 기본값
위젯은 C# 클래스와 다른 오래된 기본값을 가지고 있습니다. 다음 값들은 현재 docViewer.js 구현에서 가져온 것입니다.
| 옵션 | 기본값 | 비고 |
|---|---|---|
leftMinWidth / leftMaxWidth | 220 / 800 | 썸네일 패널 너비 범위. |
showThumbs | true | 초기 썸네일 가시성. |
autoFocus / autoPageFocus | true / false | autoPageFocus 은 C# 기본값과 다릅니다. |
thumbWidth / thumbHeight / thumbPadding | 150 / 200 / 10 | 픽셀 단위 썸네일 기하학. |
pageZoom / zoomStep / maxZoom | 100 / 10 / 200 | JavaScript maxZoom 은 C# (300)와 다릅니다. |
showToolTip / toolTipPageText | true / "Page " | 페이지 위치 툴팁. |
format / doc / AccessToken | "" / 0 / "" | 내부 초기화 값; 일반적으로 View(token)에 의해 채워집니다. |
debugMode | false | 추가 클라이언트 진단. |
FitType | "" | 제공되지 않으면 자동 맞춤이 없습니다. |
BasePath | "DocImage.axd" | 호환성을 위해 유지된 과거 클라이언트 기본값입니다. 현재 ASP.NET Core 호스트는 매핑된 미들웨어 브랜치에 명시적으로 설정해야 합니다. |
ResPath | "" | 임베드된 이미지 경로에 명시적으로 설정합니다. |
cacheEnabled / cacheCount / cacheDelay | false / 3 / 3 | 메모리 내 페이지 사전 로드 창 및 지연. |
autoLoad | false | 명시적인 토큰 흐름을 권장합니다. |
largeDoc | true | C# 기본값과 다릅니다. |
fixedZoom | false | C# 기본값과 다릅니다. |
fixedZoomPercent / fixedZoomPercentMobile | 100 / 50 | 모바일 값은 C# (75)와 다릅니다. |
showHyperlinks | true | 오버레이를 생성하려면 서버 측 추출이 필요합니다. |
동작에 중요한 모든 값을 설정하고 기본값에 의존하지 마십시오:
<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>콜백
| 콜백 | 인수 | 목적 |
|---|---|---|
onPageLoading | pageNum | 페이지 요청이 시작됩니다. |
onPageLoaded | pageNum | 페이지 이미지 로드가 완료되었습니다. |
onThumbnailClicked | pageNum | 사용자가 썸네일을 선택했습니다. |
onPageClicked | pageNum | 사용자가 페이지를 선택했습니다. |
onDoubleClick | none | 뷰어가 더블 클릭을 받았습니다. |
onViewerBusy | none | 뷰어가 바쁜 상태에 들어갔습니다. |
onViewerReady | none | 초기화가 완료되었습니다. |
onViewerError | none | 뷰어가 오류 상태에 들어갔습니다. |
onError | message | 작업이 오류 메시지를 반환했습니다. |
onCopy | data | 텍스트 복사 데이터가 사용 가능합니다. |
onAutoLoadStatus | pageNum | 자동 로딩이 페이지로 진행되었습니다. |
onThumbsShown | none | 썸네일 패널이 표시되었습니다. |
onAnnLoaded | none | 주석 데이터가 로드되었습니다. |
onAnnSaved | none | 주석 데이터가 저장되었습니다. |
onAnnSaveError | none | 주석 저장에 실패했습니다. |
onAnnClosed | none | 주석 UI가 닫혔습니다. |
콜백은 빠르게 유지하고, 텔레메트리를 비동기적으로 전송하며 페이지 렌더링을 차단하지 마십시오.
이 중 모든 항목은 init 객체의 옵션입니다. 이전 뷰어는 컨테이너 ID에서 파생된 이름을 가진 전역 함수를 찾아 사용했습니다 — <div id="div_ctlDoc">가 있는 페이지는 function ctlDoc_OnViewerReady()만 선언하면 되었습니다. 그 조회는 사라졌습니다. 함수를 명시적으로 전달하십시오:
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 기본값으로 폴링합니다:
| 옵션 | 기본값 |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
일반 단일 노드 뷰어에서는 비활성화된 상태로 두세요. 이를 활성화해도 지원되지 않는 동기 렌더링을 비동기로 전환할 수 없습니다.
FirstPagePriority 로 공유 스토리지에서 페이지를 제공하고, 이후 페이지가 작성될 때까지 정당하게 202 Accepted 에 응답하는 경우 이를 활성화하세요. 재시도하지 않는 클라이언트는 아직 렌더링 중인 페이지에 대해 깨진 타일을 표시합니다 — 분산 배포를 참고하세요.
경로 체크리스트
DoconutOptions.MiddlewarePath은 실제 매핑하는 브랜치를 설명해야 합니다.BasePath은 해당 브랜치를 대상으로 해야 하며, 선행/없이 작성됩니다 ('doconut','/doconut'가 아니라: 뷰어가 슬래시를 추가하고,//doconut/...은 다른 호스트에 대한 요청입니다). 일반적인 설정은MapWhen브랜치에서 과거의DocImage.axd요청 형태를 유지하므로BasePath: '/'을 설정합니다.DoconutOptions.ResourcesPath은 임베디드 리소스 경로입니다.ResPath은 일반적으로 선행/없이 해당images하위 폴더를 대상으로 하며, 기본 접두사와 함께'doconut-res/images'합니다. 이전 라이브러리에서는 리소스가 애플리케이션 루트에서 제공되었기 때문에 빈ResPath가 올바른 것이었지만, 여기서는 올바르지 않으며 오류 없이 실패합니다.ExtractHyperlinks은showHyperlinks가 어떤 것도 표시하기 전에 서버 포맷 설정에서 활성화되어야 합니다.
이 페이지가 도움이 되었나요?