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ù sao chúng cũng được hiển thị trên các trang và có thể được nhúng vào các bản 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.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 // ribbon chú thích được nhúng
}))Giữ nguyên cấu trúc Viewer đầy đủ hiển thị trong markup:
<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>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>Nếu 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 phá vỡ trang.
Việc 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. Việc 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:
annBar.open();
annBar.close();API Ribbon công cộng là:
| Phương thức | Mục đích |
|---|---|
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 chế độ 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 khe 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.
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 sẽ 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.
Hai loại callback, được kết 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 kết nối theo cách ngược lại:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedlà các tùy chọn củadocViewer({...}), giống như mọi callback của trình xem.Created,Changed,Deleted, vàPropertieslà các hàm toàn cục được tìm theo tên: id của trình xem được thêm tiền tố vào sự kiện. Đối với trình xem 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ẽ 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ờ "các thay đổi chưa lưu".
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 con 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 chèn chúng vào các xuất khẩu image/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):
| Kiểu | Ghi chú |
|---|---|
StampAnnotation | Dấu văn bản với kích thước phông chữ, viền, màu; hỗ trợ Opacity, Rotate |
NoteAnnotation | Ghi chú dán với văn bản, màu nền, kích thước phông chữ, TitleColor |
RectangleAnnotation | Màu viền + màu nền, Title/ShowTitle |
CircleAnnotation | Viền + nền, ShowBorder |
EllipseAnnotation | Viền + nền, ShowBorder |
TriangleAnnotation | Mà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 chỉ, mặc định E) |
FreehandAnnotation | Nét vẽ tự do từ các điểm FreehandData đã mã hoá |
ImageAnnotation | Hình ảnh từ một URL. Một URL relative đượ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ên | Mục đích |
|---|---|
Add(BaseAnnotation) | Đặt hàng một chú thích |
GetAnnotations() / GetAnnotations(int page) | Kiểm tra những gì trình quản lý 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 hoạt động 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
// PDF của tất cả các trang với annotations đượ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ủa các PNG mỗi 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 một bộ đốt như việc 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 “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:
| Bối cảnh | Ai tải ảnh | Trên máy chủ nội bộ hoặc máy chủ phát triển |
|---|---|---|
| Trình xem trong trình duyệt | Trình duyệt của người dùng | Ảnh hiển thị |
ExportAnnotationsToPdfAsync / …PngZipAsync | Máy chủ | Một chỗ giữ chỗ màu đỏ "Image blocked" |
Khi máy chủ tải một hình ảnh để nhúng vào, nó từ chối các địa chỉ trỏ lại vào mạng riêng: loopback (localhost, 127.0.0.1), 0.0.0.0, link-local (169.254.x.x), các dải 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 để truy cập 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ữ chỗ thay vì. Đó 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ể giải quyết sẽ bị từ chối theo cùng cách; bất kỳ lỗi tải xuống nào khác sẽ hiển thị URL và thông báo lỗi màu đỏ ở vị trí hình ảnh.
Quy trình duy trì
- Mở tài liệu và lấy token của nó.
- Tải XML hoặc dữ liệu đã mã hoá đã lưu trước vào token đó.
- Cho widget đọc và chỉnh sửa các chú thích phiên.
- Lấy XML với
GetAnnotationXML(token)khi ứng dụng của bạn quyết định lưu trữ. - Xuất PDF/PNG khi cần một tài liệu đã được làm phẳng.
- Đó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 gắn 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.
Ghi chú bảo mật và hiển thị
- Các yêu cầu chú thích sử dụng cùng bảo mật session/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 request forgery 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 tự vẽ lớn và xuất độ 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ị phóng to.
Khắc phục sự cố
| Triệu chứng | Kiểm tra |
|---|---|
| Dải chú thích bị thiếu | khả năng Annotation và bốn cờ CSS/script của chú thích |
| Callback lưu báo lỗi | Hết hạn token/phiên và middleware BasePath |
ctlDoc_Created (hoặc một hàm sự kiện khác) không bao giờ chạy | Tên hàm: id trình xem + _ + event, 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 ra | Má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ích | Lư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?