Chú thích

Các 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 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ù theo cách nào, chúng sẽ được hiển thị trên các trang và có thể được nhúng vào các tệp 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).

Kích hoạt giao diện người dùng chú thích

Annotation là một mô-đun Viewer, không phải một 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; Ribbon Annotation sau đó được gắn và đính kèm vào cùng một thể hiện.

Phát hành 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 khả dụng:

@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 Annotation tạo ra Ribbon DOM bên trong annBarMount; bạn không cần sao chép các nút hoặc markup hộp thoại của nó. Khởi tạo docViewer trước, sau đó tạo Ribbon chỉ khi máy chủ xác nhận rằng Annotation đã đượ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), nơi lưu trữ chúng trong phiên tài liệu theo 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 sở hữu host:

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

API công khai của Ribbon 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 exportPdf, exportPng, imageUpload, và imageList; các điều khiển không có endpoint được cấu hình sẽ bị ẩn. Đối với chuỗi khởi động kết hợp Viewer, Search và Annotation, xem Khởi động 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; hãy lưu trữ XML hoặc phong bì 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.

Xây dựng chú thích trong C#

Lấy một manager gắn với phiên mở, thêm các 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 của 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) (phong bì Base64 từ GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Xuất với các 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");
});

Các xuất khẩu sử dụng cùng một bộ xử lý như khi render trên màn hình, vì vậy những gì người dùng thấy là những gì tệp 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 bản giao hàng đã được làm phẳng.
6. Đóng phiên tài liệu.

Không sử dụng token viewer ẩn danh 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 riêng 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 phiên/token như các yêu cầu trang.
• Một URL ImageAnnotation tương đối sẽ được giải quyết từ host yêu cầu và phải vẫn có thể truy cập được bởi máy chủ tại thời điểm nhúng.
• Kiểm tra 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ủ.
• Các xuất khẩu á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à các xuất khẩu độ phân giải cao làm tăng mức sử dụng bộ nhớ; hãy kiểm thử với các tài liệu và mức zoom thực tế.

Khắc phục sự cố