Anmärkningar

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 temporär licens).

Aktivera anmärkning UI

Annotation ä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; Annotation‑Ribbon‑en monteras sedan och fästs på samma instans.

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

@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  // the embedded annotation ribbon
}))

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

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

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

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

Sparande från Ribbon postar data via middleware (AnnSave), som lagrar det i dokumentsessionen per sida. Laddning (AnnLoad) sker automatiskt när en sida med anmärkningar renderas. De fyra onAnn*‑återanropen håller Ribbon synkroniserad med viewer‑livscykeln.

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

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

Det offentliga Ribbon‑API‑et är:

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.

Annotation‑paketet lägger till webbläsarens författarverktyg, men datan tillhör fortfarande server‑sidans dokumentsession 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 längre än sessionens livstid.

Bygg annotationer i C#

Hämta en manager som är 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):

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();
});

Annotations typer

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

AnnotationManager‑API

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

Exportera med inbrända annotationer

// 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 per-sida PNG-filer
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å det som användarna ser är vad filen innehåller.

Arbetsflöde för beständighet

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

Använd inte den ogenomskinliga viewer‑token som en permanent identifierare för annotationer. Koppla beständig annotation‑data till dina egna dokument‑ och versionsidentifierare.

Säkerhet och renderingsanteckningar

• Annotationsförfrågningar använder samma session/token‑säkerhet som sidförfrågningar.
• En relativ ImageAnnotation‑URL löses upp från förfrågningsvärden och måste förbli åtkomlig för servern vid bränningstid.
• Validera och kontrollera alla användargenererade bild‑URL:er för att undvika server‑sidig förfrågningsförfalskning.
• Export använder samma licens-/anpassade vattenstämpelbeslut som rendering av sidan på skärmen.
• Stora frihandspayloads och högupplösta export ökar minnesanvändningen; testa realistiska dokument och zoomvärden.

Felsökning