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 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.
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. Pełna 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 pakiety adnotacji razem z pakietami przeglądarki — są one uzależnione od licencji, więc tagi pojawiają się tylko wtedy, gdy możliwość jest dostępna:
@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:
<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 Annotation 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 Annotation jest licencjonowane:
<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 przeglądarki.
Otwórz i zamknij ją z dowolnego paska narzędzi Viewer zarządzanego przez hosta:
annBar.open();
annBar.close();Publiczne API wstążki to:
| Metoda | Cel |
|---|---|
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() | Ponownie zał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.
Aby zobaczyć sekwencję uruchamiania połączonych modułów 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ą powłokę adnotacji w swojej aplikacji, jeśli adnotacje mają przetrwać poza okresem życia sesji.
Dwa rodzaje wywołań zwrotnych, podłączone na dwa sposoby
Kod adnotacji używa dwóch stylów wywołań zwrotnych i każdy z nich milcząco zawodzi, gdy jest podłączony w odwrotny sposób:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedsą opcjedocViewer({...}), jak każde wywołanie zwrotne przeglądarki.Created,Changed,Deleted, iPropertiessą globalnymi funkcjami znajdowanymi po nazwie: identyfikator przeglądarki jest prefiksem zdarzenia. Dla przeglądarki w#div_ctlDocidentyfikator toctlDoc, więc funkcje toctlDoc_Created,ctlDoc_Changed,ctlDoc_DeletedictlDoc_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 „unsaved changes”.
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):
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 image/PDF.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});Typy adnotacji
Wszystkie typy znajdują się w Doconut.Annotations i dziedziczą po BaseAnnotation (numer strony + ograniczające Rectangle):
| Type | Notes |
|---|---|
StampAnnotation | Stempel tekstowy z rozmiarem czcionki, obramowaniem, kolorem; obsługuje Opacity, Rotate |
NoteAnnotation | Notatka samoprzylepna z tekstem, kolorem tła, rozmiarem czcionki, TitleColor |
RectangleAnnotation | Kolory obramowania i wypełnienia, Title/ShowTitle |
CircleAnnotation | Obramowanie + wypełnienie, ShowBorder |
EllipseAnnotation | Obramowanie + wypełnienie, ShowBorder |
TriangleAnnotation | Kolor obramowania, BackColor, ShowBorder |
LineAnnotation | Prosta linia o szerokości i kolorze |
ArrowAnnotation | Linia z grotami; konfigurowalny Direction (typ ArrowDirection, punkty kompasowe, domyślny E) |
FreehandAnnotation | Swobodny pociągnięcie z zakodowanych punktów FreehandData |
ImageAnnotation | Obraz 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
| Member | Purpose |
|---|---|
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) | Zakodowany ciąg danych adnotacji — koperta Base64 (co konsumuje widget) |
GetAnnotationXml() | Formularz XML |
Viewer odzwierciedla operacje ładowania/odczytu względem sesji: LoadAnnotationData(token, manager) lub LoadAnnotationData(token, encodedData) (koperta Base64 z GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
Eksport z wbudowanymi adnotacjami
// 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 dla każdej strony
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 obrazów na hoście intranetowym eksportowane jako "Obraz zablokowany"
Podgląd i eksport pobierają obraz ImageAnnotation z różnych miejsc:
| Powierzchnia | Kto pobiera obraz | Na hoście intranetowym lub deweloperskim |
|---|---|---|
| Podgląd w przeglądarce | Przeglądarka użytkownika | Obraz się pojawia |
ExportAnnotationsToPdfAsync / …PngZipAsync | Serwer | Czerwony "Obraz zablokowany" symbol zastępczy |
Gdy serwer pobiera obraz, aby go wstawić, 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 link‑local i unique‑local IPv6. 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 tego zawiera symbol zastępczy. To jest 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.
Przebieg utrwalania
- Otwórz dokument i uzyskaj jego token.
- Wczytaj wcześniej zapisane XML lub zakodowane dane do tego tokena.
- Pozwól widżetowi odczytać i edytować adnotacje sesji.
- Pobierz XML przy użyciu
GetAnnotationXML(token), gdy aplikacja zdecyduje się na utrwalenie. - Wyeksportuj PDF/PNG, gdy wymagany jest spłaszczony produkt końcowy.
- 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 podany przez użytkownika URL obrazu, aby uniknąć fałszowania żądania po stronie serwera.
- Eksporty stosują tę samą decyzję o licencji/niestandardowym 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 przybliżenia.
Rozwiązywanie problemów
| Objaw | Sprawdź |
|---|---|
| Brak wstążki adnotacji | Annotation możliwość i cztery flagi CSS/skryptu adnotacji |
| Callback zapisu zgłasza błąd | Wygaś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 eksporcie | Host obrazu ma prywatny lub adres loopback — patrz powyżej |
| Ponownie otwarty dokument nie ma adnotacji | Utrwal XML/dane poza sesją podglądu, a następnie wczytaj je do nowego tokena |
Czy ta strona była pomocna?