Anmerkungen
Unterstützung für Anmerkungen zum 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 und lädt sie in eine offene Sitzung. In beiden Fällen werden sie auf den Seiten gerendert und können in PDF‑ oder PNG‑Exporte eingebettet werden.
Die Unterstützung für Anmerkungen ist durch die Annotation Lizenz‑Funktion gesperrt (automatisch gewährt bei einer aktiven temporären Lizenz).
Aktivieren der Anmerkungs‑UI
Anmerkungen sind ein Viewer‑Modul, nicht eine eigenständige Symbolleiste. Die Seite muss die Viewer‑Ressourcen, die Viewer‑Symbolleiste, die Viewer‑Einbindung und ein initialisiertes objViewer enthalten; das Anmerkungs‑Ribbon wird dann eingebunden und an dieselbe Instanz angehängt.
Die Anmerkungsdateien zusammen mit den Viewer‑Dateien ausgeben. Sie sind lizenzgebunden, sodass ihre Tags nur erscheinen, wenn die Fähigkeit gewährt ist. In MVC 5 bauen Sie die Tags im Controller (Ansichten haben kein @inject):
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 // das eingebettete Annotationsband
});
ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
return View();
}
}Die vollständige Viewer‑Zusammensetzung im Markup beibehalten:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer-Steuerungen, einschließlich der Schaltfläche, die Annotation öffnet -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Die Anmerkungsdateien erzeugen das Ribbon innerhalb von annBarMount; Sie kopieren dessen Schaltflächen oder Dialoge nicht. Initialisieren Sie zuerst docViewer und erstellen Sie das Ribbon nur, wenn der Server bestätigt, dass Anmerkungen lizenziert sind:
@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>Ohne die Fähigkeit lässt ReferenceScripts das Ribbon‑Skript weg, sodass das serverseitige if einen ungeschützten doconutAnnotationBar(...) Aufruf davon abhält, die Seite zu beschädigen. In Web Forms schreiben Sie dieselbe Schutzmaßnahme als <% if (IsAnnotationEnabled) { %> … <% } %>.
Das Speichern über das Ribbon sendet die Daten an DocImage.axd (AnnSave), das sie in der Dokument‑Sitzung pro Seite speichert. Das Laden (AnnLoad) erfolgt automatisch, wenn eine Seite mit Anmerkungen gerendert wird.
Öffnen und schließen Sie das Ribbon über Ihre eigene Symbolleiste mit annBar.open() und annBar.close(). Seine öffentliche API:
| Methode | Zweck |
|---|---|
attach(objViewer) | Das Ribbon mit dem initialisierten Viewer verbinden; einmal erforderlich |
open() / close() | Anmerkungs‑Bearbeitung starten oder beenden |
reset() | Das Ribbon in den geschlossenen, nicht‑bearbeitenden Zustand zurücksetzen |
isOpen() / annotating() | Den Ribbon‑Zustand / den Anmerkungs‑Bearbeitungs‑Zustand des Viewers lesen |
reopenEditable() | Die Anmerkungen der aktuellen Seite als bearbeitbare Objekte neu laden |
updateActionState() | Die Speicher‑ und Lösch‑Steuerelemente nach Host‑Änderungen aktualisieren |
headerSlot() | Der optionale Header‑Slot für host‑eigene Steuerelemente |
onStatus, onToast, onLayout, onEditStart und onEditEnd sind optionale Host‑Callbacks. Das endpoints Objekt kann außerdem exportPdf, exportPng, imageUpload und imageList bereitstellen; Steuerelemente ohne konfigurierten Endpunkt bleiben verborgen.
Zwei Arten von Callback, auf zwei Arten verdrahtet
Der Annotationscode 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 nach 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 nie das Flag für „ungespeicherte Ä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 und Color):
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<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 - der Viewer holt sie ab und der Renderer brennt sie ein
// image/PDF-Exporte.
viewer.LoadAnnotationData(token, manager);
return new HttpStatusCodeResult(200);
}Anmerkungstypen
Alle Typen befinden sich in Doconut.Annotations und erben von BaseAnnotation (Seitenzahl plus begrenzende Rectangle):
| Type | Hinweise |
|---|---|
StampAnnotation | Textstempel mit Schriftgröße, Rand, Farbe; unterstützt Opacity, Rotate |
NoteAnnotation | Klebezettel mit Text, Hintergrundfarbe, Schriftgröße, TitleColor |
RectangleAnnotation | Rand- und Füllfarben, Title/ShowTitle |
CircleAnnotation | Rand und Füllung, ShowBorder |
EllipseAnnotation | Rand und Füllung, ShowBorder |
TriangleAnnotation | Randfarbe, BackColor, ShowBorder |
LineAnnotation | Gerade Linie mit Breite und Farbe |
ArrowAnnotation | Linie mit Pfeilspitze; einstellbares Direction (ArrowDirection, Kompasspunkte, Standard E) |
FreehandAnnotation | Freier Strich aus codierten FreehandData Punkten |
ImageAnnotation | Bild von einer URL. Eine relative URL wird gegen den Host der aktuellen Anfrage aufgelöst, wenn die Anmerkung hinzugefügt wird — siehe den Exporthinweis unten |
Die AnnotationManager-API
| Member | Zweck |
|---|---|
Add(BaseAnnotation) | Anmerkung einreihen |
GetAnnotations() / GetAnnotations(int page) | Untersuchen, was der Manager hält |
ClearAnnotations() / ClearAnnotations(int page) | Alle entfernen / pro Seite |
GetAnnotationData() / GetAnnotationData(int page) | Kodierte Anmerkungsdaten — der Umschlag, den das Widget verbraucht |
GetAnnotationXml() | XML-Form |
Viewer spiegelt die Lade- und Lesevorgänge gegen eine Sitzung: LoadAnnotationData(token, manager) oder LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml) und GetAnnotationXML(token).
Export mit eingebrannten Anmerkungen
// PDF aller Seiten mit darauf gerenderten Anmerkungen
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");
}
// Oder ein ZIP von PNGs pro Seite
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");
}Exporte verwenden denselben Brenner wie die Bildschirmausgabe und dieselbe Lizenz- und benutzerdefinierte Wasserzeichen-Entscheidung.
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 lädt das Bild herunter | 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. Das schützt den Server davor, über eine manipulierte Bild‑URL interne Systeme zu erreichen, und es gibt keinen Schalter, um das zu deaktivieren.
Eine relative Bild‑URL wird gegen den 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, nicht ein 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 Hostname, 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 gespeichertes XML oder kodierte Daten in diesen Token.
- Lassen Sie das Widget die Sitzungsanmerkungen lesen und bearbeiten.
- Rufen Sie XML mit
GetAnnotationXML(token)ab, wenn Ihre Anwendung entscheidet, zu persistieren. - Exportieren Sie PDF oder PNG, wenn ein flaches Lieferformat erforderlich ist.
- Schließen Sie die Dokumentsitzung.
Verwenden Sie das Viewer‑Token nicht als permanente Anmerkungs‑Kennung – es verfällt mit der Sitzung, und ein Recyceln des Anwendungspools beendet jede Sitzung auf einem einzelnen Server. Speichern Sie Anmerkungsdaten zusammen mit Ihren eigenen Dokument‑ und Versionskennungen.
Sicherheits- und Rendering-Hinweise
- Anmerkungs-Anfragen verwenden dieselbe Sitzungs- und Token-Sicherheit wie Seiten-Anfragen.
- Validieren und kontrollieren Sie jede vom Benutzer bereitgestellte Bild-URL.
- Große Freihand-Payloads und hochauflösende Exporte erhöhen den Speicherverbrauch; testen Sie realistische Dokumente und Zoom-Werte.
Fehlersuche
| Symptom | Prüfung |
|---|---|
| Die Annotationsleiste fehlt | Die Annotation‑Fähigkeit und die vier Annotations‑CSS/Script‑Flags |
| Speichern meldet einen Fehler | Token‑ oder Sitzungsablauf und das BasePath des Widgets |
ctlDoc_Created (oder eine andere Ereignisfunktion) wird nie ausgeführt | Der Funktionsname: Viewer‑ID + _ + Ereignis, als globale Funktion |
| C#-Anmerkungen erscheinen nicht | Seitenzahlen beginnen bei eins und die Daten wurden in den aktiven Token geladen |
| Eine Bildanmerkung wird auf dem Bildschirm angezeigt, aber nicht im Export | Der Host des Bildes hat eine private oder Loopback‑Adresse – siehe oben |
| Ein erneut geöffnetes Dokument hat keine Anmerkungen | Persistieren Sie XML oder Daten außerhalb der Viewer‑Sitzung und laden Sie sie dann in den neuen Token |
War diese Seite hilfreich?