주석

뷰어에 주석 지원 추가

Doconut의 주석은 두 방향으로 작동합니다: 사용자가 브라우저 위젯에서 직접 그리면 서버가 페이지별로 저장하고, 혹은 코드를 통해 프로그래밍 방식으로 생성하여 열린 세션에 로드합니다. 어느 쪽이든 페이지에 렌더링되며 PDF/PNG 내보내기에 포함될 수 있습니다.

주석 지원은 Annotation 라이선스 기능에 의해 제한됩니다(활성 임시 라이선스가 있으면 자동으로 부여됩니다).

주석 UI 사용하기

주석은 Viewer 모듈이며, 독립적인 툴바가 아닙니다. 전체 페이지에는 Viewer 리소스, Viewer 툴바, Viewer 마운트, 그리고 초기화된 objViewer가 포함되어야 합니다; 그 후 Annotation Ribbon이 마운트되어 동일한 인스턴스에 연결됩니다.

주석 번들을 Viewer 번들과 함께 내보냅니다 — 이들은 라이선스로 제한되므로 해당 기능이 사용 가능할 때만 태그가 표시됩니다:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss     = true,
    IncludeAnnotationCss = true   // jquery-ui.min.css + annotationBar.css
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeViewerScripts      = true,
    IncludeAnnotationScripts  = true, // jquery-ui, raphael.js, annotation.js
    IncludeAnnotationBar      = true  // 내장된 annotation 리본
}))

마크업에 전체 Viewer 구성을 표시된 상태로 유지합니다:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer controls, Annotation을 여는 버튼을 포함 -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Annotation 번들은 annBarMount 내부에 Ribbon DOM을 생성합니다; 버튼이나 대화상자 마크업을 복사할 필요가 없습니다. 먼저 docViewer를 초기화하고, 서버가 주석이 라이선스가 부여되었음을 확인할 때만 Ribbon을 생성합니다:

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: 'doconut',
        ResPath: 'doconut-res/images',
        onAnnLoaded:    () => annBar?.handleAnnLoaded(),
        onAnnSaved:     () => annBar?.handleAnnSaved(),
        onAnnSaveError: () => annBar?.handleAnnSaveError(),
        onAnnClosed:    () => annBar?.handleAnnClosed(),
        onError:        (message) => console.error('Viewer error:', message)
    });

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => objViewer.Refit())
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

해당 기능이 없으면, ReferenceScripts는 Ribbon 스크립트를 제외하므로 서버 측 if가 보호되지 않은 doconutAnnotationBar(...) 호출이 페이지를 깨뜨리는 것을 방지합니다.

Ribbon에서 저장하면 미들웨어 (AnnSave)를 통해 데이터를 전송하며, 이는 페이지별 문서 세션에 저장됩니다. 로드(AnnLoad)는 주석이 있는 페이지가 렌더링될 때 자동으로 발생합니다. 네 개의 onAnn* 콜백은 Ribbon을 Viewer 라이프사이클과 동기화합니다.

호스트가 소유한 Viewer 툴바에서 언제든지 열고 닫을 수 있습니다:

javascript
annBar.open();
annBar.close();

공개 Ribbon API는 다음과 같습니다:

메서드목적
attach(objViewer)초기화된 Viewer에 Ribbon을 연결합니다; 한 번만 필요합니다
open() / close()주석 편집 모드에 들어가거나 나갑니다
reset()Ribbon을 닫힌 비편집 상태로 되돌립니다
isOpen() / annotating()Ribbon 상태 / Viewer의 주석 편집 상태를 읽습니다
reopenEditable()현재 페이지 주석을 편집 가능한 객체로 다시 로드합니다
updateActionState()호스트 변경 후 저장/삭제 제어 가능성을 새로 고칩니다
headerSlot()호스트가 소유한 컨트롤을 위한 선택적 헤더 확장 슬롯을 가져옵니다

onStatus, onToast, onLayout, onEditStart, 그리고 onEditEnd는 선택적인 호스트 콜백입니다. endpoints 객체는 추가로 exportPdf, exportPng, imageUpload, 그리고 imageList를 제공할 수 있습니다; 구성된 엔드포인트가 없는 컨트롤은 숨겨진 상태로 유지됩니다.

통합 Viewer, Search, 그리고 Annotation 시작 순서에 대해서는 빠른 시작을 참조하십시오.

Annotation 번들은 브라우저 저작 도구를 추가하지만, 데이터는 여전히 토큰으로 식별되는 서버 측 문서 세션에 속합니다. 소스를 다시 열면 새로운 세션이 생성됩니다; 주석이 세션 수명보다 오래 유지되어야 한다면 XML 또는 인코딩된 주석 엔벨로프를 애플리케이션에 저장하십시오.

두 가지 종류의 콜백, 두 방식으로 연결됨

주석 코드는 두 가지 콜백 스타일을 사용하며, 반대 방식으로 연결될 경우 각각 조용히 실패합니다:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed 은 옵션이며, docViewer({...}) 의 옵션으로, 모든 뷰어 콜백과 같습니다.
  • Created, Changed, Deleted, 및 Properties 은 이름으로 찾는 전역 함수이며: 이벤트에 뷰어 ID가 접두됩니다. #div_ctlDoc 의 뷰어에 대한 ID는 ctlDoc 이므로, 함수들은 ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted, 그리고 ctlDoc_Properties 입니다. 철자가 틀리거나 이름이 바뀐 함수는 호출되지 않습니다.

SaveAnnotations() 은 저장 여부를 반환하지 않습니다: 결과는 onAnnSaved 또는 onAnnSaveError 로 전달됩니다. 반환 값을 읽는 코드는 "unsaved changes" 플래그를 절대 해제하지 않습니다.

C#에서 주석 만들기

열려 있는 세션에 바인딩된 매니저를 가져와 주석을 추가하고 로드합니다 (타입을 위해 using Doconut.Annotations;, using System.Drawing; 은 Rectangle/Color 용):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // 열린 세션의 페이지 차원에 바인딩됨
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // 페이지당 하나의 스탬프
    for (int page = 1; page <= pageCount; page++)
    {
        manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
            $"PAGE {page}", 28, 4, Color.Maroon)
        {
            Opacity = 60,
            Rotate  = -8
        });
    }

    manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
        "Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));

    // 세션에 로드 — 위젯이 AnnLoad를 통해 가져오고
    // 렌더러가 이를 이미지/PDF 내보내기에 삽입합니다.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

주석 유형

모든 유형은 Doconut.Annotations 에 존재하며 BaseAnnotation (페이지 번호 + 경계 Rectangle) 를 상속합니다:

유형설명
StampAnnotation글꼴 크기, 테두리, 색상이 있는 텍스트 스탬프; Opacity, Rotate 지원
NoteAnnotation텍스트, 배경 색상, 글꼴 크기, TitleColor 가 포함된 스티키 노트
RectangleAnnotation테두리와 채우기 색상, Title/ShowTitle
CircleAnnotation테두리와 채우기, ShowBorder
EllipseAnnotation테두리와 채우기, ShowBorder
TriangleAnnotation테두리 색상, BackColor, ShowBorder
LineAnnotation너비와 색상이 있는 직선
ArrowAnnotation화살표가 있는 선; 설정 가능한 Direction (유형 ArrowDirection, 나침반 포인트, 기본값 E)
FreehandAnnotation인코딩된 FreehandData 포인트로부터 자유로운 스트로크
ImageAnnotationURL에서 가져온 이미지. 상대 URL은 주석이 추가될 때 요청 호스트를 기준으로 해석됩니다; 서버는 이미지 를 번인 시점에만 가져옵니다 — 아래 내보내기 주석을 참고하십시오.

AnnotationManager API

멤버목적
Add(BaseAnnotation)주석을 대기열에 넣기
GetAnnotations() / GetAnnotations(int page)매니저가 보유한 것을 검사하기
ClearAnnotations() / ClearAnnotations(int page)전체 제거 / 페이지별 제거
GetAnnotationData() / GetAnnotationData(int page)인코딩된 주석 데이터 문자열 — 위젯이 사용하는 Base64 전송 봉투
GetAnnotationXml()XML 형식

Viewer 은 세션에 대한 로드/읽기 작업을 반영합니다: LoadAnnotationData(token, manager) 또는 LoadAnnotationData(token, encodedData) (GetAnnotationData() 로부터의 Base64 전송 봉투), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

주석이 번인된 상태로 내보내기

csharp
// 주석이 렌더링된 모든 페이지의 PDF
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
    return Results.File(pdf, "application/pdf", "export.pdf");
});

// 또는 페이지별 PNG ZIP
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
    return Results.File(zip, "application/zip", "annotations-png.zip");
});

내보내기는 화면 렌더링과 동일한 번인 방식을 사용하므로 사용자가 보는 것이 파일에 포함된 내용과 동일합니다 — 이미지 주석을 제외하고는, 다음에 설명합니다.

인트라넷 호스트에서 이미지 주석이 "이미지 차단"으로 내보내짐

뷰어와 내보내기는 ImageAnnotation의 이미지를 서로 다른 위치에서 가져옵니다:

구분이미지를 다운로드하는 주체인트라넷 또는 개발 호스트에서
브라우저의 뷰어사용자의 브라우저이미지가 표시됩니다
ExportAnnotationsToPdfAsync / …PngZipAsync서버빨간색 "Image blocked" 자리표시자

서버가 이미지를 가져와 삽입하려고 할 때, 사설 네트워크로 다시 연결되는 주소는 거부됩니다: 루프백 (localhost, 127.0.0.1), 0.0.0.0, 링크‑로컬 (169.254.x.x), 사설 범위 10.x, 172.16–31.x, 및 192.168.x, 캐리어‑그레이드 NAT (100.64.0.0/10), 그리고 IPv6 링크‑로컬 및 유니크‑로컬 주소. 이는 서버가 조작된 이미지 URL을 통해 내부 시스템에 접근하는 것을 방지하며, 이를 끄는 스위치는 없습니다.

상대 이미지 URL은 현재 요청의 호스트를 기준으로 해석되므로, localhost에서, 인트라넷 서버에서, 혹은 사설 주소를 통해 접근되는 모든 사이트에서 이미지가 뷰어에 표시되고 내보내기에는 대신 자리표시자가 포함됩니다. 이는 방어 메커니즘이 작동한 것이지 렌더링 오류가 아닙니다. 내보내기에 이미지가 반드시 포함되어야 한다면, 공용 주소를 가진 호스트에서 제공하고 절대 URL을 사용하십시오. 해결할 수 없는 호스트 이름도 동일하게 거부되며, 다른 다운로드 실패 시 URL과 오류 메시지가 빨간색으로 표시되어 이미지가 있던 위치에 나타납니다.

지속성 워크플로우

  1. 문서를 열고 토큰을 가져옵니다.
  2. 이전에 저장된 XML 또는 인코딩된 데이터를 해당 토큰에 로드합니다.
  3. 위젯이 세션 주석을 읽고 편집하도록 합니다.
  4. 애플리케이션이 지속을 결정할 때 GetAnnotationXML(token)를 사용해 XML을 가져옵니다.
  5. 평면화된 전달물이 필요할 경우 PDF/PNG로 내보냅니다.
  6. 문서 세션을 종료합니다.

불투명 뷰어 토큰을 영구적인 주석 식별자로 사용하지 마십시오. 지속된 주석 데이터를 귀하의 문서 및 버전 식별자와 연결하십시오.

보안 및 렌더링 참고사항

  • 주석 요청은 페이지 요청과 동일한 세션/토큰 보안을 사용합니다.
  • 서버 측 요청 위조를 방지하기 위해 사용자 제공 이미지 URL을 검증하고 제어하십시오.
  • 내보내기는 화면상의 페이지 렌더링과 동일한 라이선스/맞춤 워터마크 결정을 적용합니다.
  • 대용량 자유형 페이로드와 고해상도 내보내기는 메모리 사용량을 증가시키므로, 실제 문서와 줌 값을 테스트하십시오.

문제 해결

증상점검
주석 리본이 누락됨Annotation 기능 및 네 개의 주석 CSS/스크립트 플래그
저장 콜백이 오류를 보고함토큰/세션 만료 및 미들웨어 BasePath
ctlDoc_Created (또는 다른 이벤트 함수) 실행되지 않음함수 이름: viewer id + _ + event, 전역 함수로
C# 주석이 표시되지 않음페이지 번호가 1부터 시작하며 데이터가 활성 토큰에 로드되었습니다
이미지 주석이 화면에는 표시되지만 내보내기에는 포함되지 않음이미지 호스트가 사설 또는 루프백 주소를 가지고 있습니다 — 위를 참조하십시오
다시 연 문서에 주석이 없음뷰어 세션 외부에 XML/데이터를 지속한 후, 새 토큰에 로드하십시오

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