Adnotacje

Dodaj obsługę adnotacji w przeglądarce

Adnotacje w Doconut działają w dwóch kierunkach: użytkownicy rysują je w widżecie przeglądarki, a serwer przechowuje je per strona, lub Twój kod tworzy je i ładuje do otwartej sesji. W obu przypadkach są renderowane na stronach i mogą być włączone do eksportów PDF lub PNG.

Obsługa adnotacji jest uzależniona od możliwości licencyjnej Annotation (przyznawanej automatycznie przy aktywnej licencji tymczasowej).

Włącz interfejs UI adnotacji

Adnotacja jest modułem Viewer, a nie samodzielnym paskiem narzędzi. Strona musi zawierać zasoby Viewer, pasek narzędzi Viewer, montaż Viewer oraz zainicjowany objViewer; wówczas wstążka Annotation jest montowana i podłączana do tej samej instancji.

Emituj pliki adnotacji razem z plikami przeglądarki. Są one uzależnione od licencji, więc ich tagi pojawiają się tylko wtedy, gdy możliwość jest przyznana. W MVC 5 buduj tagi w kontrolerze (widoki nie mają @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   // wbudowany pasek adnotacji
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Zachowaj pełną kompozycję Viewer w znacznikach:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Elementy sterujące przeglądarką, w tym przycisk otwierający Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Pliki Annotation generują wstążkę wewnątrz annBarMount; nie kopiujesz jej przycisków ani dialogów. Najpierw zainicjuj docViewer, a następnie utwórz wstążkę tylko wtedy, gdy serwer potwierdzi, że Annotation jest licencjonowane:

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>

Bez tej możliwości, ReferenceScripts pomija skrypt wstążki, więc po stronie serwera if chroni nieosłonięte wywołanie doconutAnnotationBar(...) przed zepsuciem strony. W Web Forms napisz tę samą ochronę jako <% if (IsAnnotationEnabled) { %> … <% } %>.

Zapisywanie z wstążki wysyła dane do DocImage.axd (AnnSave), które przechowuje je w sesji dokumentu per strona. Ładowanie (AnnLoad) odbywa się automatycznie, gdy strona z adnotacjami jest renderowana.

Otwieraj i zamykaj wstążkę z własnego paska narzędzi przy użyciu annBar.open() i annBar.close(). Jej publiczne API:

MetodaCel
attach(objViewer)Połącz wstążkę z zainicjowanym przeglądarką; wymagane jednorazowo
open() / close()Rozpocznij lub zakończ edycję adnotacji
reset()Przywróć wstążkę do zamkniętego, nieedytującego stanu
isOpen() / annotating()Odczytaj stan wstążki / stan edycji adnotacji w przeglądarce
reopenEditable()Przeładuj adnotacje bieżącej strony jako edytowalne obiekty
updateActionState()Odśwież kontrolki zapisu i usuwania po zmianach hosta
headerSlot()Opcjonalny slot nagłówka dla kontrolek zarządzanych przez hosta

onStatus, onToast, onLayout, onEditStart i onEditEnd są opcjonalnymi wywołaniami zwrotnymi hosta. Obiekt endpoints może także dostarczyć exportPdf, exportPng, imageUpload i imageList; kontrolki bez skonfigurowanego punktu końcowego pozostają ukryte.

Dwa rodzaje wywołań zwrotnych, podłączone na dwa sposoby

Kod adnotacji używa dwóch stylów wywołań zwrotnych, a każdy z nich cicho nie działa, gdy jest podłączony w odwrotny sposób:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed są opcjami docViewer({...}), jak każde wywołanie zwrotne przeglądarki.
  • Created, Changed, Deleted, i Properties są globalne funkcje odnajdywane po nazwie: identyfikator przeglądarki jest prefiksem zdarzenia. Dla przeglądarki w #div_ctlDoc identyfikator to ctlDoc, więc funkcje to ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted i ctlDoc_Properties. Błędnie napisana lub przemianowana funkcja po prostu nigdy nie zostaje wywołana.

SaveAnnotations() nie zwraca, czy zapisano: wynik przychodzi przez onAnnSaved lub onAnnSaveError. Kod, który odczytuje jego wartość zwrotną, nigdy nie czyści flagi „niezapisane zmiany”.

Tworzenie adnotacji w C#

Uzyskaj menedżera powiązanego z otwartą sesją, dodaj adnotacje i załaduj je (z using Doconut.Annotations; dla typów oraz using System.Drawing; dla Rectangle i Color):

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

    // Powiązane z wymiarami strony otwartej sesji
    var manager   = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Jedna pieczątka na stronę
    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));

    // Załaduj do sesji - przeglądarka pobiera je, a renderer wstawia je do
    // eksporty obrazów/PDF.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

Typy adnotacji

Wszystkie typy znajdują się w Doconut.Annotations i dziedziczą po BaseAnnotation (numer strony plus ograniczające Rectangle):

TypeNotes
StampAnnotationStempel tekstowy z rozmiarem czcionki, obramowaniem, kolorem; obsługuje Opacity, Rotate
NoteAnnotationNotatka samoprzylepna z tekstem, kolorem tła, rozmiarem czcionki, TitleColor
RectangleAnnotationKolory obramowania i wypełnienia, Title/ShowTitle
CircleAnnotationObramowanie i wypełnienie, ShowBorder
EllipseAnnotationObramowanie i wypełnienie, ShowBorder
TriangleAnnotationKolor obramowania, BackColor, ShowBorder
LineAnnotationProsta linia o szerokości i kolorze
ArrowAnnotationLinia z grotami; konfigurowalny Direction (ArrowDirection, punkty kompasowe, domyślny E)
FreehandAnnotationSwobodny odcisk z zakodowanych punktów FreehandData
ImageAnnotationObraz z URL. Względny URL jest rozwiązywany względem hosta bieżącego żądania, gdy adnotacja jest dodawana — zobacz notatkę o eksporcie poniżej

API AnnotationManagera

MemberPurpose
Add(BaseAnnotation)Kolejkuj adnotację
GetAnnotations() / GetAnnotations(int page)Sprawdź, co przechowuje menedżer
ClearAnnotations() / ClearAnnotations(int page)Usuń wszystkie / na stronę
GetAnnotationData() / GetAnnotationData(int page)Zakodowane dane adnotacji — koperta, którą konsumuje widżet
GetAnnotationXml()Forma XML

Viewer odzwierciedla operacje ładowania i odczytu względem sesji: LoadAnnotationData(token, manager) lub LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml) i GetAnnotationXML(token).

Eksport z wbudowanymi adnotacjami

csharp
// PDF wszystkich stron z nałożonymi adnotacjami
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");
}

// Lub ZIP z PNG‑ami poszczególnych stron
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");
}

Eksporty używają tego samego wypalacza co renderowanie na ekranie oraz tej samej licencji i decyzji o niestandardowym znaku wodnym.

Adnotacje obrazów na hoście intranetowym eksportują się jako „Obraz zablokowany”

Podgląd i eksport pobierają obraz ImageAnnotation z różnych miejsc:

PowierzchniaKto pobiera obrazNa hoście intranetowym lub deweloperskim
Podgląd w przeglądarcePrzeglądarka użytkownikaObraz się pojawia
ExportAnnotationsToPdfAsync / …PngZipAsyncSerwerCzerwony "Obraz zablokowany" znacznik

Kiedy serwer pobiera obraz, aby go wbudować, odrzuca adresy prowadzące z powrotem do prywatnych sieci: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), prywatne zakresy 10.x, 172.16–31.x i 192.168.x, carrier‑grade NAT (100.64.0.0/10) oraz adresy IPv6 link‑local i unique‑local. Chroni to serwer przed użyciem do dotarcia do wewnętrznych systemów poprzez spreparowany URL obrazu i nie ma przełącznika, który można wyłączyć.

Względny URL obrazu jest rozwiązywany względem hosta bieżącego żądania, więc na localhost, na serwerze intranetowym lub na dowolnej stronie dostępnej przez prywatny adres, obraz wyświetla się w podglądzie, a eksport zamiast niego zawiera znacznik. To działanie ochrony, a nie błąd renderowania. Jeśli eksporty muszą zawierać obraz, należy go udostępnić z hosta o publicznym adresie i użyć bezwzględnego URL. Nazwa hosta, której nie można rozwiązać, jest odrzucana w ten sam sposób; każdy inny błąd pobierania wyświetla URL i komunikat o błędzie na czerwono w miejscu obrazu.

Przebieg utrwalania

  1. Otwórz dokument i uzyskaj jego token.
  2. Załaduj wcześniej zapisane XML lub zakodowane dane do tego tokena.
  3. Pozwól widgetowi odczytać i edytować adnotacje sesji.
  4. Pobierz XML przy użyciu GetAnnotationXML(token), gdy aplikacja zdecyduje się na utrwalenie.
  5. Eksportuj PDF lub PNG, gdy wymagany jest spłaszczony plik wyjściowy.
  6. Zamknij sesję dokumentu.

Nie używaj tokena podglądu jako trwałego identyfikatora adnotacji — wygasa wraz z sesją, a recykling puli aplikacji kończy każdą sesję na pojedynczym serwerze. Przechowuj dane adnotacji w odniesieniu do własnych identyfikatorów dokumentu i wersji.

Uwagi dotyczące bezpieczeństwa i renderowania

  • Żądania adnotacji używają takiego samego bezpieczeństwa sesji i tokena jak żądania stron.
  • Waliduj i kontroluj każdy URL obrazu dostarczony przez użytkownika.
  • Duże ładunki ręcznego rysowania i eksporty w wysokiej rozdzielczości zwiększają zużycie pamięci; testuj realistyczne dokumenty i wartości przybliżenia.

Rozwiązywanie problemów

ObjawSprawdź
Wstążka adnotacji jest nieobecnaFunkcjonalność Annotation oraz cztery flagi CSS/skryptu adnotacji
Zapisywanie zgłasza błądWygaszenie tokena lub sesji oraz BasePath widgetu
ctlDoc_Created (lub inna funkcja zdarzenia) nigdy nie uruchamia sięNazwa funkcji: id podglądu + _ + zdarzenie, jako funkcja globalna
Adnotacje C# nie pojawiają sięNumery stron zaczynają się od 1, a dane zostały załadowane do aktywnego tokena
Adnotacja obrazu wyświetla się na ekranie, ale nie w eksporcieHost obrazu ma prywatny lub loopback adres — zobacz powyżej
Ponownie otwarty dokument nie ma adnotacjiUtrwal XML lub dane poza sesją podglądu, a następnie załaduj je do nowego tokena

Czy ta strona była pomocna?