Chú thích

Chú thích trong Doconut hoạt động theo hai hướng: người dùng vẽ chúng trong widget trình duyệt và máy chủ lưu trữ chúng theo từng trang, hoặc mã của bạn tạo chúng một cách lập trình và tải chúng vào một phiên mở. Dù sao chúng cũng được hiển thị trên các trang và có thể được nhúng vào các file xuất PDF/PNG.

Hỗ trợ chú thích được kiểm soát bởi khả năng cấp phép Annotation (được cấp tự động khi có giấy phép Temporary đang hoạt động).

Bật giao diện người dùng chú thích

Chú thích là một mô-đun Viewer, không phải là thanh công cụ độc lập. Trang đầy đủ phải bao gồm các tài nguyên Viewer, thanh công cụ Viewer, phần gắn Viewer và objViewer đã được khởi tạo; sau đó Ribbon Chú thích sẽ được gắn và đính kèm vào cùng một thể hiện.

Phát các gói chú thích cùng với các gói viewer — chúng được kiểm soát bằng giấy phép, vì vậy các thẻ chỉ xuất hiện khi khả năng này có sẵn:

@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  // the embedded annotation ribbon
}))

Giữ toàn bộ cấu trúc Viewer hiển thị trong markup:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer controls, including the button that opens Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Gói Chú thích tạo ra DOM Ribbon bên trong annBarMount; bạn không cần sao chép các nút hoặc markup của hộp thoại. Khởi tạo docViewer trước, sau đó tạo Ribbon chỉ khi máy chủ xác nhận rằng Chú thích đã được cấp phép:

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

Việc lưu từ Ribbon gửi dữ liệu qua middleware (AnnSave), lưu trữ nó trong phiên tài liệu theo từng trang. Việc tải (AnnLoad) diễn ra tự động khi một trang có chú thích được hiển thị. Bốn callback onAnn* giữ cho Ribbon đồng bộ với vòng đời của viewer.

Mở và đóng nó từ bất kỳ thanh công cụ Viewer nào thuộc chủ sở hữu:

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

API Ribbon công cộng là:

onStatus, onToast, onLayout, onEditStart, và onEditEnd là các callback tùy chọn của host. Đối tượng endpoints có thể bổ sung cung cấp exportPdf, exportPng, imageUpload, và imageList; các điều khiển không có endpoint được cấu hình sẽ ẩn.

Đối với chuỗi khởi động kết hợp Viewer, Search và Annotation, xem Bắt đầu nhanh.

Gói chú thích thêm các công cụ tạo nội dung trong trình duyệt, nhưng dữ liệu vẫn thuộc về phiên tài liệu phía máy chủ được xác định bằng token. Mở lại nguồn tạo một phiên mới; lưu trữ XML hoặc envelope chú thích đã mã hoá trong ứng dụng của bạn nếu các chú thích cần tồn tại vượt quá thời gian sống của phiên.

Tạo chú thích trong C#

Lấy một manager gắn với phiên mở, thêm chú thích và tải chúng (với using Doconut.Annotations; cho các kiểu và using System.Drawing; cho Rectangle/Color):

app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Bound to the open session's page dimensions
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // One stamp per page
    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));

    // Load into the session — the widget fetches them via AnnLoad and the
    // renderer burns them into image/PDF exports.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Các loại chú thích

Tất cả các loại nằm trong Doconut.Annotations và kế thừa từ BaseAnnotation (số trang + Rectangle bao quanh):

API AnnotationManager

Viewer phản chiếu các thao tác tải/đọc đối với một phiên: LoadAnnotationData(token, manager) hoặc LoadAnnotationData(token, encodedData) (envelope Base64 từ GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Xuất với chú thích được nhúng

// PDF of all pages with annotations rendered onto them
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");
});

// Or a ZIP of per-page PNGs
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");
});

Quá trình xuất sử dụng cùng một bộ công cụ như khi hiển thị trên màn hình, vì vậy những gì người dùng thấy là những gì file chứa.

Quy trình lưu trữ

1. Mở tài liệu và lấy token của nó.
2. Tải XML hoặc dữ liệu đã mã hoá đã lưu trước vào token đó.
3. Cho phép widget đọc và chỉnh sửa các chú thích trong phiên.
4. Lấy XML bằng GetAnnotationXML(token) khi ứng dụng của bạn quyết định lưu trữ.
5. Xuất PDF/PNG khi cần một tài liệu đã được làm phẳng.
6. Đóng phiên tài liệu.

Không sử dụng token viewer không trong suốt làm định danh chú thích vĩnh viễn. Liên kết dữ liệu chú thích đã lưu với các định danh tài liệu và phiên bản của bạn.

Ghi chú bảo mật và render

• Các yêu cầu chú thích sử dụng cùng cơ chế bảo mật session/token như các yêu cầu trang.
• Một URL ImageAnnotation tương đối được giải quyết từ host yêu cầu và phải vẫn có thể truy cập được từ máy chủ tại thời điểm nhúng.
• Xác thực và kiểm soát bất kỳ URL hình ảnh do người dùng cung cấp để tránh tấn công giả mạo yêu cầu phía máy chủ.
• Quá trình xuất áp dụng cùng quyết định giấy phép/đánh dấu tùy chỉnh như khi render trang trên màn hình.
• Các payload freehand lớn và xuất độ phân giải cao tăng việc sử dụng bộ nhớ; hãy kiểm tra tài liệu thực tế và các giá trị thu phóng.

Khắc phục sự cố