Anmerkungen
Unterstützung für Anmerkungen im Viewer hinzufügen
Anmerkungen in Doconut funktionieren in zwei Richtungen: Benutzer zeichnen sie im Browser-Widget und der Server speichert sie pro Seite, oder Ihr Code erstellt sie programmgesteuert und lädt sie in eine offene Sitzung. In beiden Fällen werden sie auf den Seiten dargestellt und können in PDF/PNG-Exporte eingebettet werden.
Die Unterstützung für Anmerkungen ist durch die Lizenzfähigkeit Annotation geschützt (wird automatisch bei einer aktiven temporären Lizenz gewährt).
Anmerkungs‑UI aktivieren
Anmerkungen sind ein Viewer‑Modul, nicht eine eigenständige Symbolleiste. Die komplette Seite muss die Viewer‑Ressourcen, die Viewer‑Symbolleiste, die Viewer‑Einbindung und das initialisierte objViewer enthalten; das Anmerkungs‑Ribbon wird dann eingebunden und an dieselbe Instanz angehängt.
Geben Sie die Anmerkungs‑Bundles zusammen mit den Viewer‑Bundles aus – sie sind lizenzgesteuert, sodass die Tags nur erscheinen, wenn die Fähigkeit verfügbar ist:
@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 // das eingebettete Annotationsband
}))Halten Sie die komplette Viewer‑Zusammensetzung im Markup sichtbar:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer-Steuerelemente, einschließlich der Schaltfläche, die Annotation öffnet -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Das Anmerkungs‑Bundle erzeugt das Ribbon‑DOM innerhalb von annBarMount; Sie müssen dessen Schaltflächen oder Dialog‑Markup nicht kopieren. Initialisieren Sie zuerst docViewer und erstellen Sie das Ribbon erst, wenn der Server bestätigt, dass Anmerkungen lizenziert sind:
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
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>Ohne die Fähigkeit lässt ReferenceScripts das Ribbon‑Script weg, sodass das serverseitige if einen ungeschützten doconutAnnotationBar(...)‑Aufruf davon abhält, die Seite zu beschädigen.
Das Speichern über das Ribbon sendet Daten durch die Middleware (AnnSave), die sie pro Seite in der Dokument‑Sitzung speichert. Das Laden (AnnLoad) erfolgt automatisch, wenn eine Seite mit Anmerkungen gerendert wird. Die vier onAnn*‑Callbacks halten das Ribbon mit dem Lebenszyklus des Viewers synchronisiert.
Öffnen und schließen Sie es über jede host‑eigene Viewer‑Symbolleiste:
annBar.open();
annBar.close();Die öffentliche Ribbon‑API ist:
| Methode | Zweck |
|---|---|
attach(objViewer) | Verbinden Sie das Ribbon mit dem initialisierten Viewer; einmalig erforderlich |
open() / close() | Beginnen oder beenden Sie die Anmerkungsbearbeitung |
reset() | Setzt das Ribbon in den geschlossenen, nicht‑bearbeitenden Zustand zurück |
isOpen() / annotating() | Liest den Ribbon‑Zustand / den Anmerkungs‑Bearbeitungszustand des Viewers |
reopenEditable() | Lädt die Anmerkungen der aktuellen Seite als bearbeitbare Objekte neu |
updateActionState() | Aktualisiert die Verfügbarkeit von Speicher‑/Lösch‑Steuerelementen nach Host‑Änderungen |
headerSlot() | Ermittelt den optionalen Header‑Erweiterungs‑Slot für host‑eigene Steuerelemente |
onStatus, onToast, onLayout, onEditStart und onEditEnd sind optionale Host‑Callbacks. Das Objekt endpoints kann zusätzlich exportPdf, exportPng, imageUpload und imageList bereitstellen; Steuerelemente ohne konfigurierten Endpunkt bleiben verborgen.
Für die kombinierte Viewer-, Such‑ und Anmerkungs‑Startsequenz siehe Schnellstart.
Das Anmerkungs‑Bundle fügt die Browser‑Autorentools hinzu, aber die Daten gehören weiterhin zur serverseitigen Dokument‑Sitzung, die durch das Token identifiziert wird. Das erneute Öffnen der Quelle erzeugt eine neue Sitzung; speichern Sie das XML oder den codierten Anmerkungs‑Umfang in Ihrer Anwendung, wenn Anmerkungen über die Lebensdauer der Sitzung hinaus erhalten bleiben müssen.
Zwei Arten von Callback, auf zwei Arten verdrahtet
Der Anmerkungscode verwendet zwei Callback‑Stile, und jeder schlägt stillschweigend fehl, wenn er auf die andere Weise verdrahtet wird:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedsind Optionen vondocViewer({...}), wie jeder Viewer‑Callback.Created,Changed,Deleted, undPropertiessind globale Funktionen, die per Namen gefunden werden: die Viewer‑ID wird dem Ereignis vorangestellt. Für den Viewer in#div_ctlDocist die IDctlDoc, sodass die FunktionenctlDoc_Created,ctlDoc_Changed,ctlDoc_DeletedundctlDoc_Propertiessind. Eine falsch geschriebene oder umbenannte Funktion wird einfach nie aufgerufen.
SaveAnnotations() gibt nicht zurück, ob es gespeichert wurde: das Ergebnis kommt über onAnnSaved oder onAnnSaveError. Code, der seinen Rückgabewert liest, löscht niemals das Flag für „ungenespeicherte Änderungen“.
Anmerkungen in C# erstellen
Erhalte einen Manager, der an die offene Sitzung gebunden ist, füge Anmerkungen hinzu und lade sie (mit using Doconut.Annotations; für die Typen und using System.Drawing; für Rectangle/Color):
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// Gebunden an die Seitenabmessungen der offenen Sitzung
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// Ein Stempel pro Seite
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));
// In die Sitzung laden — das Widget holt sie über AnnLoad und das
// renderer brennt sie in Bild-/PDF-Exporte ein.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});Anmerkungstypen
Alle Typen befinden sich in Doconut.Annotations und erben von BaseAnnotation (Seitennummer + begrenzendes Rectangle):
| Typ | Hinweis |
|---|---|
StampAnnotation | Textstempel mit Schriftgröße, Rand, Farbe; unterstützt Opacity, Rotate |
NoteAnnotation | Haftnotiz mit Text, Hintergrundfarbe, Schriftgröße, TitleColor |
RectangleAnnotation | Rand- + Füllfarben, Title/ShowTitle |
CircleAnnotation | Rand + Füllung, ShowBorder |
EllipseAnnotation | Rand + Füllung, ShowBorder |
TriangleAnnotation | Randfarbe, BackColor, ShowBorder |
LineAnnotation | Gerade Linie mit Breite und Farbe |
ArrowAnnotation | Linie mit Pfeilspitze; einstellbares Direction (Typ ArrowDirection, Kompasspunkte, Standard E) |
FreehandAnnotation | Freier Strich aus codierten FreehandData Punkten |
ImageAnnotation | Bild von einer URL. Eine relative URL wird beim Hinzufügen der Anmerkung gegen den Anforderungs‑Host aufgelöst; der Server holt das Bild erst zur Brennzeit — siehe die Export‑Hinweis unten |
Die AnnotationManager-API
| Mitglied | Zweck |
|---|---|
Add(BaseAnnotation) | Anmerkung in die Warteschlange stellen |
GetAnnotations() / GetAnnotations(int page) | Untersuchen, was der Manager hält |
ClearAnnotations() / ClearAnnotations(int page) | Alles / pro Seite entfernen |
GetAnnotationData() / GetAnnotationData(int page) | Kodierter Anmerkungs‑Daten‑String — ein Base64‑Datenpaket (was das Widget verbraucht) |
GetAnnotationXml() | XML‑Formular |
Viewer spiegelt die Lade‑/Lese‑Operationen gegen eine Sitzung: LoadAnnotationData(token, manager) oder LoadAnnotationData(token, encodedData) (das Base64‑Datenpaket von GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
Export mit eingebrannten Anmerkungen
// PDF aller Seiten mit darauf gerenderten Anmerkungen
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");
});
// Oder ein ZIP mit pro Seite PNGs
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");
});Exporte verwenden denselben Brenner wie die Bildschirmausgabe, sodass das, was die Benutzer sehen, dem Inhalt der Datei entspricht — mit Ausnahme von Bild‑Anmerkungen, die im Folgenden beschrieben werden.
Bildanmerkungen auf einem Intranet-Host exportieren als "Bild blockiert"
Der Viewer und der Export holen das Bild eines ImageAnnotation aus unterschiedlichen Quellen:
| Oberfläche | Wer das Bild herunterlädt | Auf einem Intranet- oder Entwicklungs-Host |
|---|---|---|
| Der Viewer im Browser | Der Browser des Benutzers | Das Bild erscheint |
ExportAnnotationsToPdfAsync / …PngZipAsync | Der Server | Ein roter "Bild blockiert" Platzhalter |
Wenn der Server ein Bild abruft, um es einzubetten, verweigert er Adressen, die zurück in private Netze zeigen: Loopback (localhost, 127.0.0.1), 0.0.0.0, Link‑Local (169.254.x.x), die privaten Bereiche 10.x, 172.16–31.x und 192.168.x, Carrier‑Grade NAT (100.64.0.0/10) sowie IPv6‑Link‑Local‑ und Unique‑Local‑Adressen. Dies schützt den Server davor, über eine manipulierte Bild‑URL interne Systeme zu erreichen, und es gibt keinen Schalter, um dies zu deaktivieren.
Eine relative Bild‑URL wird relativ zum Host der aktuellen Anfrage aufgelöst, sodass bei localhost, auf einem Intranet‑Server oder auf jeder über eine private Adresse erreichbaren Seite das Bild im Viewer angezeigt wird und der Export stattdessen den Platzhalter enthält. Das ist die Schutzfunktion, kein Rendering‑Fehler. Wenn Exporte das Bild enthalten müssen, stellen Sie es von einem Host mit öffentlicher Adresse bereit und verwenden Sie eine absolute URL. Ein Host‑Name, der nicht aufgelöst werden kann, wird auf dieselbe Weise abgelehnt; jeder andere Download‑Fehler zeigt die URL und die Fehlermeldung in Rot dort an, wo das Bild stehen würde.
Persistenz‑Workflow
- Öffnen Sie das Dokument und erhalten Sie dessen Token.
- Laden Sie zuvor gespeicherte XML‑ oder kodierte Daten in diesen Token.
- Lassen Sie das Widget die Sitzungs‑Anmerkungen lesen und bearbeiten.
- Rufen Sie XML mit
GetAnnotationXML(token)ab, wenn Ihre Anwendung entscheidet, zu persistieren. - Exportieren Sie PDF/PNG, wenn ein flaches Lieferformat erforderlich ist.
- Schließen Sie die Dokumentsitzung.
Verwenden Sie den undurchsichtigen Viewer‑Token nicht als dauerhaften Anmerkungs‑Identifier. Verknüpfen Sie persistente Anmerkungsdaten mit Ihren eigenen Dokument‑ und Versions‑Identifikatoren.
Sicherheits‑ und Rendering‑Hinweise
- Anmerkungs‑Anfragen verwenden dieselbe Sitzungs‑/Token‑Sicherheit wie Seiten‑Anfragen.
- Validieren und kontrollieren Sie jede vom Benutzer bereitgestellte Bild‑URL, um Server‑Side‑Request‑Forgery zu vermeiden.
- Exporte wenden dieselbe Lizenz‑/Benutzerdefiniert‑Wasserzeichen‑Entscheidung wie die Bildschirm‑Seiten‑Renderung an.
- Große Freihand‑Payloads und hochauflösende Exporte erhöhen den Speicherverbrauch; testen Sie realistische Dokumente und Zoom‑Werte.
Fehlersuche
| Symptom | Prüfung |
|---|---|
| Anmerkungs‑Leiste fehlt | Annotation‑Fähigkeit und die vier Anmerkungs‑CSS/Script‑Flags |
| Speicher‑Callback meldet einen Fehler | Token‑/Sitzungs‑Ablauf und Middleware BasePath |
ctlDoc_Created (oder eine andere Ereignis‑Funktion) wird nie ausgeführt | Der Funktionsname: Viewer‑ID + _ + Ereignis, als globale Funktion |
| C#‑Anmerkungen werden nicht angezeigt | Die Seitennummerierung beginnt bei eins und Daten wurden in den aktiven Token geladen |
| Bild‑Anmerkung erscheint auf dem Bildschirm, aber nicht im Export | Der Host des Bildes hat eine private oder Loopback‑Adresse — siehe oben |
| Wieder geöffnetes Dokument hat keine Anmerkungen | Persistieren Sie XML/Daten außerhalb der Viewer‑Sitzung und laden Sie sie dann in den neuen Token |
War diese Seite hilfreich?