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):

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   // das eingebettete Annotationsband
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Die vollständige Viewer‑Zusammensetzung im Markup beibehalten:

html
<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
@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:

MethodeZweck
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, onAnnClosed sind Optionen von docViewer({...}), wie jeder Viewer-Callback.
  • Created, Changed, Deleted, und Properties sind globale Funktionen, die nach Namen gefunden werden: die Viewer-ID wird dem Ereignis vorangestellt. Für den Viewer in #div_ctlDoc ist die ID ctlDoc, sodass die Funktionen ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted und ctlDoc_Properties sind. 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):

csharp
// 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):

TypeHinweise
StampAnnotationTextstempel mit Schriftgröße, Rand, Farbe; unterstützt Opacity, Rotate
NoteAnnotationKlebezettel mit Text, Hintergrundfarbe, Schriftgröße, TitleColor
RectangleAnnotationRand- und Füllfarben, Title/ShowTitle
CircleAnnotationRand und Füllung, ShowBorder
EllipseAnnotationRand und Füllung, ShowBorder
TriangleAnnotationRandfarbe, BackColor, ShowBorder
LineAnnotationGerade Linie mit Breite und Farbe
ArrowAnnotationLinie mit Pfeilspitze; einstellbares Direction (ArrowDirection, Kompasspunkte, Standard E)
FreehandAnnotationFreier Strich aus codierten FreehandData Punkten
ImageAnnotationBild 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

MemberZweck
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

csharp
// 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ächeWer lädt das Bild herunterAuf einem Intranet- oder Entwicklungs-Host
Der Viewer im BrowserDer Browser des BenutzersDas Bild erscheint
ExportAnnotationsToPdfAsync / …PngZipAsyncDer ServerEin 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

  1. Öffnen Sie das Dokument und erhalten Sie dessen Token.
  2. Laden Sie zuvor gespeichertes XML oder kodierte Daten in diesen Token.
  3. Lassen Sie das Widget die Sitzungsanmerkungen lesen und bearbeiten.
  4. Rufen Sie XML mit GetAnnotationXML(token) ab, wenn Ihre Anwendung entscheidet, zu persistieren.
  5. Exportieren Sie PDF oder PNG, wenn ein flaches Lieferformat erforderlich ist.
  6. 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

SymptomPrüfung
Die Annotationsleiste fehltDie Annotation‑Fähigkeit und die vier Annotations‑CSS/Script‑Flags
Speichern meldet einen FehlerToken‑ oder Sitzungsablauf und das BasePath des Widgets
ctlDoc_Created (oder eine andere Ereignisfunktion) wird nie ausgeführtDer Funktionsname: Viewer‑ID + _ + Ereignis, als globale Funktion
C#-Anmerkungen erscheinen nichtSeitenzahlen beginnen bei eins und die Daten wurden in den aktiven Token geladen
Eine Bildanmerkung wird auf dem Bildschirm angezeigt, aber nicht im ExportDer Host des Bildes hat eine private oder Loopback‑Adresse – siehe oben
Ein erneut geöffnetes Dokument hat keine AnmerkungenPersistieren Sie XML oder Daten außerhalb der Viewer‑Sitzung und laden Sie sie dann in den neuen Token

War diese Seite hilfreich?