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ù nào đi nữa, 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

Annotation 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 đó 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ữ nguyên cấu trúc Viewer đầy đủ 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 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 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>

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. 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 của host:

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

API Ribbon công khai 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ẽ 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 annotation 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 sau khi phiên kết thúc.

Tạo chú thích trong C#

Lấy một trình quản lý được ràng buộc 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) =>
{
    // 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 cho 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ộ kết xuất chèn chúng vào hình ảnh/PDF khi xuất.
    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) (bao bì Base64 từ GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Xuất với chú thích đã được chèn

// PDF của tất cả các trang với chú thích được vẽ lên chúng
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 file ZIP chứa các PNG theo từng 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");
});

Việc xuất sử dụng cùng bộ chèn 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ì 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 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 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 cố định. 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à hiển thị

• Yêu cầu chú thích sử dụng cùng một bảo mật phiên/token như các yêu cầu trang.
• Một URL ImageAnnotation tương đối được giải quyết từ máy chủ 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 render.
• 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ủ.
• Việ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 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 thử nghiệm với tài liệu thực tế và các giá trị phóng to.

Khắc phục sự cố