Anmärkningar

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

Stöd för annotationer styrs av licensfunktionen Annotation (tilldelas automatiskt under en aktiv temporär licens).

Aktivera annoterings‑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 monteras sedan och fästs på samma instans.

Skicka ut annoteringspaketen 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">
    <!-- Viewer controls, including the button that opens Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Annoteringspaketet genererar Ribbon‑DOM‑elementet inuti 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: '/',
        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 skickar data via middleware (AnnSave), som lagrar den i dokumentsessionen per sida. Laddning (AnnLoad) sker automatiskt när en sida med annoteringar 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.

Annoteringspaketet 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 annoterings‑omslag i din applikation om annoteringar måste överleva längre än sessionens livstid.

Skapa 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) =>
{
    // Bound to the open session's page dimensions
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // One stamp per page
    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));

    // Load into the session — the widget fetches them via AnnLoad and the
    // renderer burns them into image/PDF exports.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Annotationstyper

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

AnnotationManager API

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

Export med annotationer inbrända

// PDF of all pages with annotations rendered onto them
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");
});

// Or a ZIP of per-page 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");
});

Export använder samma brännare som rendering på skärmen, så det som användarna ser är det som 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 opaka viewer-token som en permanent identifierare för annotationer. Koppla beständig annotationdata till dina egna dokument- och versionsidentifierare.

Säkerhet och renderingsanteckningar

• Annoteringsförfrågningar använder samma session-/token-säkerhet som sidförfrågningar.
• En relativ ImageAnnotation-URL löses upp från begärans värd 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‑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