Adnotacje

Dodaj obsługę adnotacji do przeglądarki

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

Wsparcie adnotacji jest uzależnione od możliwości licencyjnej Annotation (przyznawane automatycznie w ramach aktywnej tymczasowej licencji).

Włącz interfejs UI adnotacji

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

Emituj pakiety adnotacji razem z pakietami viewer — są one uzależnione od licencji, więc tagi pojawiają się tylko wtedy, gdy możliwość jest dostępna:

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  // wbudowany pasek adnotacji
}))

Utrzymaj pełną kompozycję Viewer widoczną w znacznikach:

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

Pakiet Adnotacji generuje DOM wstążki wewnątrz annBarMount; nie musisz kopiować jego przycisków ani znaczników dialogu. Najpierw zainicjuj docViewer, a następnie utwórz wstążkę tylko wtedy, gdy serwer potwierdzi, że Adnotacja jest licencjonowana:

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>

Bez tej możliwości, ReferenceScripts pomija skrypt wstążki, więc po stronie serwera if chroni niechronione wywołanie doconutAnnotationBar(...) przed uszkodzeniem strony.

Zapisywanie z wstążki wysyła dane przez warstwę pośrednią (AnnSave), która przechowuje je w sesji dokumentu per strona. Ładowanie (AnnLoad) odbywa się automatycznie, gdy strona z adnotacjami jest renderowana. Cztery wywołania zwrotne onAnn* utrzymują wstążkę zsynchronizowaną z cyklem życia viewer.

Otwórz i zamknij ją z dowolnego paska narzędzi Viewer zarządzanego przez hosta:

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

Publiczne API wstążki to:

MetodaCel
attach(objViewer)Połącz wstążkę z zainicjowanym viewer; 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 viewer
reopenEditable()Przeładuj adnotacje bieżącej strony jako edytowalne obiekty
updateActionState()Odśwież dostępność kontroli zapisu/usuwania po zmianach hosta
headerSlot()Uzyskaj opcjonalny slot rozszerzenia nagłówka dla kontrolek zarządzanych przez hosta

onStatus, onToast, onLayout, onEditStart i onEditEnd są opcjonalnymi wywołaniami zwrotnymi hosta. Obiekt endpoints może dodatkowo dostarczyć exportPdf, exportPng, imageUpload i imageList; kontrolki bez skonfigurowanego punktu końcowego pozostają ukryte. Dla połączonej sekwencji uruchamiania Viewer, Search i Annotation, zobacz Szybki start.

Pakiet adnotacji dodaje narzędzia autorskie przeglądarki, ale dane nadal należą do sesji dokumentu po stronie serwera, identyfikowanej tokenem. Ponowne otwarcie źródła tworzy nową sesję; zachowaj XML lub zakodowaną kopertę adnotacji w swojej aplikacji, jeśli adnotacje muszą przetrwać poza okresem życia sesji.

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

Kod adnotacji używa dwóch stylów wywołań zwrotnych, a każdy z nich milcząco 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ą globalnymi funkcjami znajdowanymi 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 wczytaj je (z using Doconut.Annotations; dla typów i using System.Drawing; dla Rectangle/Color):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer 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 — widget pobiera je przez AnnLoad i
    // renderer wypala je do eksportów obraz/PDF.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Typy adnotacji

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

TypUwagi
StampAnnotationPieczątka tekstowa 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 + wypełnienie, ShowBorder
EllipseAnnotationObramowanie + wypełnienie, ShowBorder
TriangleAnnotationKolor obramowania, BackColor, ShowBorder
LineAnnotationProsta linia o szerokości i kolorze
ArrowAnnotationLinia z grotami; konfigurowalny Direction (typ ArrowDirection, punkty kompasu, domyślnie E)
FreehandAnnotationSwobodne pociągnięcie z zakodowanych punktów FreehandData
ImageAnnotationObraz z URL. Względny URL jest rozwiązywany względem hosta żądania, gdy adnotacja jest dodawana; serwer pobiera obraz dopiero w czasie wypalania — zobacz notatkę o eksporcie poniżej

API AnnotationManager

CzłonekCel
Add(BaseAnnotation)Umieść adnotację w kolejce
GetAnnotations() / GetAnnotations(int page)Sprawdź, co menedżer przechowuje
ClearAnnotations() / ClearAnnotations(int page)Usuń wszystkie / per-strona
GetAnnotationData() / GetAnnotationData(int page)Zakodowany ciąg danych adnotacji — envelope Base64 (co konsumuje widget)
GetAnnotationXml()Forma XML

Viewer odzwierciedla operacje ładowania/odczytu względem sesji: LoadAnnotationData(token, manager) lub LoadAnnotationData(token, encodedData) (envelope Base64 z GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Eksport z wbudowanymi adnotacjami

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

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

Eksporty używają tego samego wypalacza co renderowanie na ekranie, więc to, co widzą użytkownicy, jest tym, co zawiera plik — z wyjątkiem adnotacji obrazowych, opisanych poniżej.

Adnotacje obrazu na hoście intranetowym eksportują jako "Image blocked"

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ę wyświetla
ExportAnnotationsToPdfAsync / …PngZipAsyncSerwerCzerwony "Image blocked" placeholder

Gdy 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 wykorzystaniem 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 osiągniętej przez prywatny adres, obraz wyświetla się w podglądzie, a eksport zamiast niego zawiera placeholder. To działanie ochrony, a nie błąd renderowania. Jeśli eksporty muszą zawierać obraz, udostępnij go z hosta o publicznym adresie i użyj pełnego (absolutnego) 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.

Proces zachowywania

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

Nie używaj nieprzezroczystego tokena podglądu jako stałego identyfikatora adnotacji. Powiąż utrwalone dane adnotacji z własnymi identyfikatorami dokumentu i wersji.

Uwagi dotyczące bezpieczeństwa i renderowania

  • Żądania adnotacji używają takiego samego zabezpieczenia sesji/tokenu jak żądania stron.
  • Waliduj i kontroluj każdy dostarczony przez użytkownika URL obrazu, aby uniknąć ataków typu server‑side request forgery.
  • Eksporty stosują tę samą decyzję o licencji/dostosowanym znaku wodnym, co renderowanie stron na ekranie.
  • Duże ładunki ręcznego rysowania i eksporty w wysokiej rozdzielczości zwiększają zużycie pamięci; testuj realistyczne dokumenty i wartości powiększenia.

Rozwiązywanie problemów

ObjawSprawdź
Wstążka adnotacji jest nieobecnamożliwość Annotation oraz cztery flagi CSS/skryptu adnotacji
Callback zapisu zgłasza błądwygaśnięcie tokena/sesji oraz middleware BasePath
ctlDoc_Created (lub inna funkcja zdarzenia) nigdy nie uruchamia sięnazwa funkcji: id podglądu + _ + zdarzenie, jako funkcja globalna
Adnotacje C# nie pojawiają sięnumeracja stron zaczyna się od 1 i dane zostały wczytane do aktywnego tokena
Adnotacja obrazu pojawia się na ekranie, ale nie w eksporciehost obrazu ma prywatny lub adres loopback — patrz wyżej
Ponownie otwarty dokument nie ma adnotacjiutrwal XML/dane poza sesją podglądu, a następnie wczytaj je do nowego tokena

Czy ta strona była pomocna?