Chú thích

Thêm hỗ trợ chú thích cho trình xem

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 giấy 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

Chú thích là một mô-đun Viewer, không phải là 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; 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
@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  // dải chú thích nhúng
}))

Giữ nguyên cấu trúc Viewer đầy đủ hiển thị trong markup:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Các điều khiển Viewer, bao gồm nút mở Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

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

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

Không có khả năng này, ReferenceScripts sẽ bỏ qua script của Ribbon, vì vậy if phía máy chủ giữ một lời gọi doconutAnnotationBar(...) không được bảo vệ tránh làm hỏng trang.

Lưu từ Ribbon gửi dữ liệu qua middleware (AnnSave), cái mà lưu 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 hàm gọi lại 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 thuộc sở hữu của host nào:

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

API Ribbon công cộng là:

MethodPurpose
attach(objViewer)Kết nối Ribbon với viewer đã được khởi tạo; yêu cầu một lần
open() / close()Bắt đầu hoặc kết thúc việc chỉnh sửa chú thích
reset()Đưa Ribbon trở lại trạng thái đóng, không chỉnh sửa
isOpen() / annotating()Đọc trạng thái Ribbon / trạng thái chỉnh sửa chú thích của viewer
reopenEditable()Tải lại các chú thích của trang hiện tại dưới dạng đối tượng có thể chỉnh sửa
updateActionState()Làm mới khả năng điều khiển lưu/xóa sau khi host thay đổi
headerSlot()Lấy vị trí mở rộng tiêu đề tùy chọn cho các điều khiển thuộc sở hữu của host

onStatus, onToast, onLayout, onEditStart, và onEditEnd là các hàm gọi lại 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ẽ vẫn ẩn. Đối với chuỗi khởi động kết hợp Viewer, Search và Annotation, xem Bắt đầu nhanh.

Bundle 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 sẽ tạo một phiên mới; 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.

Hai loại callback, được nối theo hai cách

Mã chú thích sử dụng hai kiểu callback, và mỗi kiểu sẽ thất bại im lặng khi được nối theo cách còn lại:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed là các tùy chọn của docViewer({...}), giống như mọi callback của viewer.
  • Created, Changed, Deleted, và Properties là các hàm toàn cục được tìm theo tên: id của viewer được thêm vào trước sự kiện. Đối với viewer trong #div_ctlDoc, id là ctlDoc, vì vậy các hàm là ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted, và ctlDoc_Properties. Một hàm bị viết sai chính tả hoặc đổi tên sẽ đơn giản không bao giờ được gọi.

SaveAnnotations() không trả về việc nó đã lưu hay chưa: kết quả đến qua onAnnSaved hoặc onAnnSaveError. Mã đọc giá trị trả về của nó sẽ không bao giờ xóa cờ "thay đổi chưa lưu".

Tạo chú thích trong C#

Lấy một manager được ràng buộc với phiên đang mở, thêm chú thích, và tải chúng (với using Doconut.Annotations; cho các loại và using System.Drawing; cho Rectangle/Color):

csharp
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 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à
    // renderer đưa chúng vào các xuất ảnh/PDF.
    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):

LoạiGhi chú
StampAnnotationCon dấu văn bản với kích thước phông chữ, viền, màu; hỗ trợ Opacity, Rotate
NoteAnnotationGhi chú dính với văn bản, màu nền, kích thước phông chữ, TitleColor
RectangleAnnotationMàu viền + tô đầy, Title/ShowTitle
CircleAnnotationViền + tô đầy, ShowBorder
EllipseAnnotationViền + tô đầy, ShowBorder
TriangleAnnotationMàu viền, BackColor, ShowBorder
LineAnnotationĐường thẳng với độ rộng và màu
ArrowAnnotationĐường có mũi tên; có thể đặt Direction (kiểu ArrowDirection, các hướng kim đồng hồ, mặc định E)
FreehandAnnotationNét vẽ tự do từ các điểm FreehandData đã mã hoá
ImageAnnotationHình ảnh từ một URL. Một URL tương đối được giải quyết dựa trên máy chủ yêu cầu khi chú thích được thêm; máy chủ sẽ tải hình ảnh chỉ vào thời điểm đốt — xem ghi chú xuất bên dưới

API AnnotationManager

Thành viênMục đích
Add(BaseAnnotation)Đưa chú thích vào hàng đợi
GetAnnotations() / GetAnnotations(int page)Kiểm tra những gì manager đang giữ
ClearAnnotations() / ClearAnnotations(int page)Xóa tất cả / theo trang
GetAnnotationData() / GetAnnotationData(int page)Chuỗi dữ liệu chú thích đã mã hoá — một phong bì Base64 (được widget tiêu thụ)
GetAnnotationXml()Dạng XML

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 chú thích được nhúng

csharp
// PDF của tất cả các trang với chú thích được render 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 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ộ đốt 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ì tệp chứa — ngoại trừ các chú thích hình ảnh, được mô tả tiếp theo.

Chú thích hình ảnh trên máy chủ nội bộ xuất ra là "Image blocked"

Trình xem và quá trình xuất tải ảnh của ImageAnnotation từ các vị trí khác nhau:

Môi trườngAi tải ảnhTrên máy chủ nội bộ hoặc phát triển
Trình xem trong trình duyệtTrình duyệt của người dùngẢnh hiển thị
ExportAnnotationsToPdfAsync / …PngZipAsyncMáy chủMột chỗ giữ màu đỏ "Image blocked"

Khi máy chủ tải một hình ảnh để nhúng vào, nó sẽ từ chối các địa chỉ quay lại mạng nội bộ: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), các dải địa chỉ riêng 10.x, 172.16–31.x và 192.168.x, carrier‑grade NAT (100.64.0.0/10), và các địa chỉ link‑local và unique‑local của IPv6. Điều này bảo vệ máy chủ khỏi việc bị sử dụng để tiếp cận các hệ thống nội bộ thông qua một URL hình ảnh được tạo ra, và không có công tắc nào để tắt tính năng này.

Một URL hình ảnh tương đối được giải quyết dựa trên máy chủ của yêu cầu hiện tại, vì vậy trên localhost, trên máy chủ nội bộ, hoặc trên bất kỳ trang nào được truy cập qua địa chỉ riêng, hình ảnh sẽ hiển thị trong trình xem và quá trình xuất sẽ chứa chỗ giữ thay vì. Đây là cơ chế bảo vệ đang hoạt động, không phải lỗi hiển thị. Nếu việc xuất cần bao gồm hình ảnh, hãy phục vụ nó từ một máy chủ có địa chỉ công cộng và sử dụng URL tuyệt đối. Một tên máy chủ không thể phân giải sẽ bị từ chối theo cùng cách; bất kỳ lỗi tải nào khác sẽ hiển thị URL và thông báo lỗi màu đỏ ở vị trí hình ảnh.

Persistence workflow

  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 widget đọc và chỉnh sửa các chú thích của phiên.
  4. Lấy XML với 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 trình xem 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 tài liệu và các định danh phiên bản của bạn.

Security and rendering notes

  • Các yêu cầu chú thích sử dụng cùng bảo mật phiên/token như các yêu cầu trang.
  • 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 hiển thị trang trên màn hình.
  • Các payload vẽ tự do lớn và xuất độ phân giải cao làm tăng mứ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.

Troubleshooting

Triệu chứngKiểm tra
Dải chú thích bị thiếukhả năng Annotation và bốn cờ CSS/script chú thích
Callback lưu báo lỗiHết hạn token/phiên và middleware BasePath
ctlDoc_Created (hoặc hàm sự kiện khác) không bao giờ chạyTên hàm: id trình xem + _ + sự kiện, như một hàm toàn cục
Chú thích C# không hiển thịĐánh số trang bắt đầu từ 1 và dữ liệu đã được tải vào token đang hoạt động
Chú thích hình ảnh hiển thị trên màn hình nhưng không xuất raMáy chủ của hình ảnh có địa chỉ riêng hoặc loopback — xem phần trên
Tài liệu mở lại không có chú thíchLưu XML/dữ liệu bên ngoài phiên trình xem, sau đó tải vào token mới

Trang này có hữu ích không?