GroupDocs.Annotation은 UI에 구애받지 않습니다. 문서 내부의 마크업을 읽고 쓰며 화면에 아무것도 그리지 않습니다. 서버 라이브러리로서는 올바른 구분이며, 이를 채택하는 모든 사람에게 한 가지 질문이 남습니다: 사람이 실제로 주석을 어떻게 그리는가?

보통의 답변은 무겁습니다: 상용 뷰어를 삽입하거나 Angular 데모를 채택한 뒤 확장하려고 시도하는 것이죠. 더 가벼운 방법이 있습니다. 페이지 이미지, 캔버스, 그리고 여섯 개의 엔드포인트 — 뷰어 컴포넌트도 없고, 프런트엔드 프레임워크도 없으며, 빌드 단계도, CDN도 없습니다. 또한 전혀 외부 네트워크 접근 없이 실행되며, 이는 예전보다 더 중요합니다.

샘플은 GitHub에 있습니다: browser-annotation-ui-net — dotnet run 후 페이지에 상자를 끌어다 놓으세요.

한 문단으로 요약된 아이디어

각 페이지를 주석 없이 PNG로 한 번 렌더링하고 캐시합니다. 주석 목록을 데이터로 브라우저에 전송합니다. 캔버스가 이미지 위에 마크업을 그립니다. 댓글을 추가하면 문서에 작은 쓰기 작업과 목록 재로드만 발생하며 — 페이지를 다시 렌더링하지 않고 — 마크업은 선택 가능하고 클릭 가능하며 응답 가능하게 유지되어 그림에 고정되지 않습니다.

엔드포인트

메서드 경로 목적
GET /api/documents/{name}/info 페이지 수와 각 페이지의 크기(포인트)
GET /api/documents/{name}/pages/{n}/image 페이지 n의 PNG
GET /api/documents/{name}/annotations 페이지 단위의 사각형으로 된 모든 주석
POST /api/documents/{name}/annotations 하나 추가
PUT /api/documents/{name}/annotations/{id} 메시지를 변경하거나 답글을 추가
DELETE /api/documents/{name}/annotations/{id} 하나 삭제

각 쓰기 작업은 전체 목록을 반환하므로, 브라우저는 서버가 현재 무엇을 보유하고 있는지 추론할 필요가 없습니다.

렌더링

PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
    PreviewFormat = PreviewFormats.PNG,
    PageNumbers = new[] { pageNumber },   // 1-based
    RenderAnnotations = false,            // the canvas draws the markup
    Resolution = 144
};

annotator.Document.GeneratePreview(previewOptions);

캐시된 이미지의 타임스탬프를 문서와 비교하고, 문서가 실제로 변경된 경우에만 다시 렌더링합니다.

픽셀 입력, 페이지 단위 출력

캔버스는 사각형을 이미지 픽셀 단위로 유지하고, 그려진 이미지의 크기를 전송합니다 — 스케일 팩터가 아니라:

body: JSON.stringify({
    page: currentPage,
    x, y, width, height,
    imageWidth: img.clientWidth,
    imageHeight: img.clientHeight,
    message: window.prompt('Comment'),
    user: 'Reviewer'
})

그 한 가지 결정이 미리보기 해상도가 바뀌거나 CSS가 이미지를 스케일링하거나 누군가 휴대폰에서 열 때 UI가 올바르게 유지되게 합니다. 서버가 수학 연산을 수행합니다:

double scaleX = page.Width / request.ImageWidth;
double scaleY = page.Height / request.ImageHeight;

annotator.Add(new AreaAnnotation
{
    PageNumber = page.PageNumber - 1,     // PageInfo is 1-based, annotations are 0-based
    Box = new Rectangle(
        (float)(request.X * scaleX), (float)(request.Y * scaleY),
        (float)(request.Width * scaleX), (float)(request.Height * scaleY)),
    BackgroundColor = 0xFFE699,
    PenColor = 0xE08C00,
    Opacity = 0.35,
    Message = request.Message,
    User = new User { Id = 1, Name = request.User, Role = Role.Editor }
});

AreaAnnotation.Box는 페이지의 왼쪽 위 모서리에서 측정됩니다 — 브라우저가 측정하는 방향과 동일합니다 — 따라서 그려진 사각형은 스케일만 적용되고 뒤집히지 않습니다.

브라우저에 사각형 형태 하나 전송

텍스트 마크업은 그 원점을 공유하지 않습니다. HighlightAnnotation.Points 및 관련 항목들은 왼쪽 아래 모서리에서 측정됩니다. 서버에서 변환하여 프런트엔드에서는 항상 왼쪽 위 사각형만 보이게 합니다:

x = minX;
y = page.Height - maxY;      // flip to top-left
width = maxX - minX;
height = maxY - minY;

이렇게 하면 Word, Acrobat에서 추가된 하이라이트나 자동 검토 패스에 의해 추가된 하이라이트가 UI에서 올바른 위치에 표시되며, JavaScript가 PDF 기하학에 대해 알 필요가 없습니다.

쓰기 시 스와프 파일 사용

annotator는 소스를 열어 둔 상태이며 읽고 있는 파일 위에 바로 저장할 수 없습니다:

using (Annotator annotator = new Annotator(path))
{
    annotator.Add(annotation);
    annotator.Save(path + ".tmp");
}

File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);

전체 순서에 대해 문서별 잠금을 걸어야 합니다. 동시에 같은 파일을 읽고, 변경하고, 다시 쓰는 두 요청이 있으면 변경 중 하나가 손실됩니다.

이 설계가 해결하지 못하는 문제

명확히 말할 가치가 있습니다. 왜냐하면 현재 형태로 배포할 수 있는지를 결정하기 때문입니다:

  • Annotation ids change after a write. 쓰기 후에 Annotation ID가 변경됩니다. ID는 문서를 읽는 동안 할당되며 파일에 저장되지 않습니다. 매 변경 후 목록을 다시 로드하는 UI는 괜찮습니다. 다중 사용자 시스템은 주석을 자체 테이블에 보관하고 가져오기·내보내기를 사용해 파일 안팎으로 이동시켜야 합니다 — 이는 감사 로그와 사용자별 가시성을 제공하는 방법이기도 합니다.
  • The whole document is rewritten on every change. 모든 변경 시 전체 문서를 다시 씁니다. 30페이지 계약서에는 괜찮지만 2,000페이지 아카이브에는 부적합합니다.
  • There is no authentication. 샘플의 모든 호출자는 “Reviewer"입니다.

실행하기

git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi

또는 컨테이너에서 --network none 옵션을 사용하면 완전히 외부로 나가지 않고 동작하는 모습을 확인할 수 있습니다:

docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui

단계별 버전은 문서에 있습니다: Build an annotation UI for your web app. 이미 JavaScript PDF 뷰어를 삽입했다면 표시용으로 유지하고, 저장을 위해서만 이 엔드포인트를 사용하세요 — 기하학 규칙은 변하지 않습니다.