Anmärkningar

Lägg till stöd för anmärkningar i visaren

Anmärkningar i Doconut fungerar i två riktningar: användare ritar dem i webbläsar‑widgeten och servern sparar dem per sida, eller så bygger din kod dem programatiskt och laddar dem i en öppen session. I båda fallen renderas de på sidorna och kan brännas in i PDF/PNG‑exporter.

Stöd för anmärkningar styrs av licensfunktionen Annotation (tilldelas automatiskt under en aktiv Tillfällig licens).

Aktivera UI för anmärkningar

Anmärkning är en Viewer‑modul, inte ett fristående verktygsfält. Den kompletta sidan måste inkludera Viewer‑resurserna, Viewer‑verktygsfältet, Viewer‑monteringen och den initierade objViewer; Annotations‑Ribbonen monteras sedan och fästs på samma instans.

Sänd anmärkningspaketen tillsammans med visarpaketen — de är licensstyrda, så taggarna visas endast när funktionen är tillgänglig:

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  // det inbäddade annoteringsbandet
}))

Behåll den kompletta Viewer‑kompositionen synlig i markupen:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Visningskontroller, inklusive knappen som öppnar Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Annotations‑paketet genererar Ribbon‑DOM:en inuti annBarMount; du behöver inte kopiera dess knappar eller dialog‑markup. Initiera docViewer först, skapa sedan Ribbonen endast när servern bekräftar att Anmärkning är licensierad:

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>

Utan funktionen utelämnar ReferenceScripts Ribbon‑skriptet, så server‑if skyddar ett oskyddat doconutAnnotationBar(...)‑anrop från att bryta sidan.

Sparande från Ribbonen postar data via middleware (AnnSave), som lagrar den i dokument‑sessionen per sida. Laddning (AnnLoad) sker automatiskt när en sida med anmärkningar renderas. De fyra onAnn*‑återanropen håller Ribbonen synkroniserad med visarens livscykel.

Öppna och stäng den från vilket host‑ägt Viewer‑verktygsfält som helst:

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

Det offentliga Ribbon‑API‑et är:

MetodSyfte
attach(objViewer)Koppla Ribbon till den initierade visaren; krävs en gång
open() / close()Starta eller avsluta redigering av anmärkningar
reset()Återställ Ribbon till dess stängda, icke‑redigerande tillstånd
isOpen() / annotating()Läs Ribbon‑tillstånd / visarens anmärkning‑redigeringstillstånd
reopenEditable()Ladda om den aktuella sidans anmärkningar som redigerbara objekt
updateActionState()Uppdatera tillgänglighet för spara/ta‑bort‑kontroller efter host‑ändringar
headerSlot()Hämta den valfria header‑utökningens plats för host‑ägda kontroller

onStatus, onToast, onLayout, onEditStart och onEditEnd är valfria host‑återanrop. endpoints‑objektet kan dessutom tillhandahålla exportPdf, exportPng, imageUpload och imageList; kontroller utan en konfigurerad endpoint förblir dolda.

För den kombinerade Viewer‑, Search‑ och Annotation‑uppstartssekvensen, se Snabbstart.

Annotations‑paketet lägger till webbläsarens författarverktyg, men data tillhör fortfarande server‑sidans dokument‑session som identifieras av token. Att öppna källan igen skapar en ny session; persista XML‑ eller kodad anmärknings‑omslag i din applikation om anmärkningar måste överleva bortom sessionens livstid.

Två typer av callback, anslutna på två sätt

Annotationskoden använder två callback‑stilar, och varje misslyckas tyst när den är ansluten på det andra sättet:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed är alternativ till docViewer({...}), precis som varje viewer‑callback.
  • Created, Changed, Deleted, och Properties är globala funktioner som hittas med namn: viewer‑id:t prefixas till händelsen. För viewern i #div_ctlDoc är id:t ctlDoc, så funktionerna är ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted och ctlDoc_Properties. En felstavad eller omdöpt funktion anropas helt enkelt aldrig.

SaveAnnotations() returnerar inte om den sparades: resultatet kommer via onAnnSaved eller onAnnSaveError. Kod som läser dess returvärde rensar aldrig flaggan för "osparade ändringar".

Skapa annotationer i C#

Hämta en manager bunden till den öppna sessionen, lägg till annotationer och ladda dem (med using Doconut.Annotations; för typerna och using System.Drawing; för Rectangle/Color):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Bunden till den öppna sessionens siddimensioner
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // En stämpel per sida
    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));

    // Ladda in i sessionen — widgeten hämtar dem via AnnLoad och
    // renderaren bränner dem i bild/PDF-exporter.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Annotationstyper

Alla typer finns i Doconut.Annotations och ärver från BaseAnnotation (sidnummer + begränsande Rectangle):

TypNoteringar
StampAnnotationTextstämpel med teckenstorlek, ram, färg; stöder Opacity, Rotate
NoteAnnotationKlistermärke med text, bakgrundsfärg, teckenstorlek, TitleColor
RectangleAnnotationRam + fyllnadsfärger, Title/ShowTitle
CircleAnnotationRam + fyllnad, ShowBorder
EllipseAnnotationRam + fyllnad, ShowBorder
TriangleAnnotationRamfärg, BackColor, ShowBorder
LineAnnotationRaka linjen med bredd och färg
ArrowAnnotationLinje med pilspets; inställningsbar Direction (typ ArrowDirection, kompasspunkter, standard E)
FreehandAnnotationFri penseldrag från kodade FreehandData punkter
ImageAnnotationBild från en URL. En relativ URL löses upp mot begärans värd när annotationen läggs till; servern hämtar bilden endast vid bränning — se exportnoteringen nedan

AnnotationManager‑API:t

MedlemSyfte
Add(BaseAnnotation)Köa en annotation
GetAnnotations() / GetAnnotations(int page)Inspektera vad managern innehåller
ClearAnnotations() / ClearAnnotations(int page)Ta bort alla / per sida
GetAnnotationData() / GetAnnotationData(int page)Kodad annotation‑data sträng — ett Base64‑paket (vad widgeten konsumerar)
GetAnnotationXml()XML‑formulär

Viewer speglar laddnings-/läsningsoperationerna mot en session: LoadAnnotationData(token, manager) eller LoadAnnotationData(token, encodedData) (Base64‑paketet från GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Export med inbrända annotationer

csharp
// PDF av alla sidor med annotationer renderade på dem
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");
});

// Eller en ZIP med PNG-filer per sida
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");
});

Export använder samma brännare som skärmrendering, så vad användarna ser är vad filen innehåller — förutom bildannotationer, som beskrivs nedan.

Bildanteckningar på en intranätvärd exporteras som "Image blocked"

Visaren och exporten hämtar en ImageAnnotations bild från olika platser:

YtaVem laddar ner bildenPå en intranät- eller utvecklingsvärd
Visaren i webbläsarenAnvändarens webbläsareBilden visas
ExportAnnotationsToPdfAsync / …PngZipAsyncServernEn röd "Image blocked" platshållare

När servern hämtar en bild för att bränna in den, vägrar den adresser som pekar tillbaka till privata nätverk: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), de privata intervallen 10.x, 172.16–31.x och 192.168.x, carrier‑grade NAT (100.64.0.0/10) samt IPv6 link‑local och unique‑local adresser. Detta skyddar servern från att användas för att nå interna system via en manipulerad bild‑URL, och det finns ingen omkopplare för att stänga av det.

En relativ bild‑URL löses mot värden för den aktuella begäran, så på localhost, på en intranät‑server eller på någon webbplats som nås via en privat adress, visas bilden i visaren och exporten innehåller i stället platshållaren. Det är skyddet som fungerar, inte ett renderingsfel. Om exporten måste innehålla bilden, servera den från en värd med en publik adress och använd en absolut URL. Ett värdnamn som inte kan lösas avvisas på samma sätt; alla andra nedladdningsfel visar URL‑en och felmeddelandet i rött där bilden skulle vara.

Arbetsflöde för beständighet

  1. Öppna dokumentet och hämta dess token.
  2. Läs in tidigare lagrad XML eller kodad data i den token.
  3. Låt widgeten läsa och redigera sessionsanteckningarna.
  4. Hämta XML med GetAnnotationXML(token) när din applikation beslutar att spara.
  5. Exportera PDF/PNG när en platt leverans krävs.
  6. Stäng dokumentsessionen.

Använd inte den ogenomskinliga visartoken som en permanent identifierare för anteckningar. Knyt sparad anteckningsdata till ditt eget dokument‑ och versionsidentifierare.

Säkerhets- och renderingsanteckningar

  • Anteckningsförfrågningar använder samma session/token‑säkerhet som sidförfrågningar.
  • Validera och kontrollera alla användargenererade bild‑URL:er för att undvika server‑sidans förfrågningsförfalskning.
  • Export använder samma licens‑/anpassade vattenstämpelbeslut som rendering av sidan på skärmen.
  • Stora handritade data och högupplösta export ökar minnesanvändningen; testa realistiska dokument och zoomvärden.

Felsökning

SymptomKontroll
Anteckningsbandet saknasAnnotation‑kapacitet och de fyra antecknings‑CSS/script‑flaggorna
Spara‑återuppringning rapporterar ett felToken-/session‑utgång och middleware BasePath
ctlDoc_Created (eller en annan händelsefunktion) körs aldrigFunktionsnamnet: visare‑id + _ + händelse, som en global funktion
C#‑anteckningar visas inteSidnumrering är ett‑baserad och data laddades in i den aktiva token
Bildanteckning visas på skärmen men inte i exportBildens värd har en privat eller loopback‑adress — se ovan
Återöppnat dokument har inga anteckningarSpara XML/data utanför visarsessionen, ladda sedan in den i den nya token

Var den här sidan hjälpsam?