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 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ù 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).

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 ra 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">
    <!-- Điều khiển Viewer, bao gồm nút mở Chú thích -->
</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 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 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), nơi lưu trữ chúng 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 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 Bắt đầu nhanh.

Gói chú thích thêm các công cụ tạo nội dung trên 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 được ràng buộc 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) =>
{
    // Ràng buộc với kích thước trang của phiên mở
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Một dấu tem mỗi trang
    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));

    // Tải vào phiên — widget lấy chúng qua AnnLoad và
    // bộ dựng chèn chúng vào các bản xuất ảnh/PDF.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Các loại chú thích

Tất cả các kiểu 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 file với chú thích đã được chèn

// PDF của tất cả các trang với chú thích được render lên
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");
});

// Hoặc một ZIP các PNG theo trang
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 bộ chèn như việc 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àm việc 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 của 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 không trong suốt làm định danh chú thích cố định. Hãy 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.

Bảo mật và ghi chú về việc render

• 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.
• URL ImageAnnotation tương đối được giải quyết dựa trên host của 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 burn.
• 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 request forgery phía máy chủ.
• 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 tự do lớn và xuất khẩu độ phân giải cao làm 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ị zoom.

Khắc phục sự cố