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 chúng theo trang, hoặc mã của bạn tạo chúng 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 tệp xuất PDF hoặc 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à thanh công cụ độc lập. Trang phải bao gồm các tài nguyên Viewer, thanh công cụ Viewer, phần gắn Viewer, và một objViewer đã được khởi tạo; Ribbon Chú thích sau đó được gắn và đính kèm vào cùng một thể hiện.

Phát ra các tệp chú thích cùng với các tệp viewer. Chúng được kiểm soát bằng giấy phép, vì vậy các thẻ của chúng chỉ xuất hiện khi khả năng được cấp. Trong MVC 5, xây dựng các thẻ trong controller (các view không có @inject):

csharp
public class ViewerController : Controller
{
    public ActionResult Index()
    {
        var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
        ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
        {
            IncludeViewerCss     = true,
            IncludeAnnotationCss = true    // jquery-ui.min.css + annotationBar.css
        });
        ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
        {
            IncludeJQuery            = true,
            IncludeViewerScripts     = true,
            IncludeAnnotationScripts = true,  // jquery-ui, raphael.js, annotation.js
            IncludeAnnotationBar     = true   // dải ruy băng chú thích được nhúng
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Giữ toàn bộ cấu trúc Viewer trong markup:

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

Các tệp Chú thích tạo Ribbon bên trong annBarMount; bạn không cần sao chép các nút hoặc 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
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
    var annBar = null;
    var currentToken = '';

    var objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        ResPath:  'doconut-res/images',
        onAnnLoaded:    function () { if (annBar) annBar.handleAnnLoaded(); },
        onAnnSaved:     function () { if (annBar) annBar.handleAnnSaved(); },
        onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
        onAnnClosed:    function () { if (annBar) annBar.handleAnnClosed(); },
        onError:        function (message) { console.error('Viewer error:', message); }
    });

    @if ((bool)ViewBag.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: function () { return { token: currentToken }; },
        onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

Nếu không có khả năng này, ReferenceScripts 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. Trong Web Forms, viết cùng một biện pháp bảo vệ như <% if (IsAnnotationEnabled) { %> … <% } %>.

Lưu từ Ribbon sẽ gửi dữ liệu tới DocImage.axd (AnnSave), nơi lưu trữ nó trong phiên tài liệu theo trang. Tải (AnnLoad) diễn ra tự động khi một trang có chú thích được hiển thị.

Mở và đóng Ribbon từ thanh công cụ của bạn bằng annBar.open() và annBar.close(). API công cộng của nó:

Phương thứcMục đích
attach(objViewer)Kết nối Ribbon với viewer đã 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 của 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 các điều khiển lưu và xóa sau khi máy chủ thay đổi
headerSlot()Vị trí tiêu đề tùy chọn cho các điều khiển do máy chủ sở hữu

onStatus, onToast, onLayout, onEditStart, và onEditEnd là các callback tùy chọn của máy chủ. Đối tượng endpoints cũng có thể cung cấp exportPdf, exportPng, imageUpload, và imageList; các điều khiển không có endpoint được cấu hình sẽ ẩ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 âm thầm 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 tiền tố vào 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ẽ 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 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 và Color):

csharp
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // Ràng buộc với kích thước trang của phiên làm việc đang 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 - trình xem sẽ lấy chúng, và bộ render sẽ chèn chúng vào
    // Xuất image/PDF.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

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 cộng với Rectangle bao quanh):

TypeGhi 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 và tô, Title/ShowTitle
CircleAnnotationViền và tô, ShowBorder
EllipseAnnotationViền và tô, 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 (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 host của yêu cầu hiện tại khi chú thích được thêm — xem ghi chú xuất bên dưới

API AnnotationManager

MemberMục đích
Add(BaseAnnotation)Đặt hàng đợi một chú thích
GetAnnotations() / GetAnnotations(int page)Kiểm tra những gì manager chứa
ClearAnnotations() / ClearAnnotations(int page)Xóa tất cả / theo trang
GetAnnotationData() / GetAnnotationData(int page)Dữ liệu chú thích đã mã hoá — phong bì mà widget tiêu thụ
GetAnnotationXml()Dạng XML

Viewer phản chiếu các thao tác tải và đọc đối với một phiên: LoadAnnotationData(token, manager) hoặc LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml), và 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
public async Task<ActionResult> ExportPdf(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", "export.pdf");
}

// Hoặc một ZIP của các PNG theo trang
public async Task<ActionResult> ExportPngZip(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(zip, "application/zip", "annotations-png.zip");
}

Xuất sử dụng cùng bộ đốt như việc render trên màn hình, và cùng giấy phép và quyết định watermark tùy chỉnh.

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 lấy hình ảnh của ImageAnnotation từ các vị trí khác nhau:

Bề mặtAi tải ảnhTrên máy chủ nội bộ hoặc máy chủ phát triển
Trình xem trong trình duyệtTrình duyệt của người dùngHình ảnh xuất hiện
ExportAnnotationsToPdfAsync / …PngZipAsyncMá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 nội bộ: 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 phải 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 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ì

  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 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 hoặc 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 của trình xem làm định danh chú thích cố định — nó sẽ hết hiệu lực cùng phiên, và việc tái tạo pool ứng dụng sẽ kết thúc mọi phiên trên một máy chủ duy nhất. Lưu dữ liệu chú thích đối với tài liệu và đị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 và 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.
  • Các payload tự do lớn và các xuất độ phân giải cao tăng mứ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ứngKiểm tra
Thanh Ribbon Chú thích bị thiếuKhả năng Annotation và bốn cờ CSS/script của chú thích
Lưu báo cáo lỗiToken hoặc hết hạn phiên, và BasePath của widget
ctlDoc_Created (hoặc một hàm sự kiện khác) không bao giờ chạyTên hàm: id của trình xem + _ + sự kiện, như một hàm toàn cục
Các chú thích C# không hiển thịSố trang bắt đầu từ 1, và dữ liệu đã được tải vào token đang hoạt động
Một chú thích hình ảnh hiển thị trên màn hình nhưng không có trong xuấtMáy chủ của hình ảnh có địa chỉ riêng hoặc loopback — xem phần trên
Tài liệu được mở lại không có chú thíchLưu XML hoặc 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?