Anmärkningar

Annotationer 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. I båda fallen 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-resurser, Viewer-verktygsfält, Viewer-montage och initierad objViewer; Annotation‑ribbonen monteras sedan och fästs på samma instans.

Skicka ut annoteringspaketen tillsammans med visarpaketen — 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: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 skickar data via middleware (AnnSave), som lagrar den i dokumentsessionen per sida. Laddning (AnnLoad) sker automatiskt när en sida med annotationer 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:t ä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‑startsekvensen, se Snabbstart.

Annoteringspaketet lägger till verktygen för författande i webbläsaren, men datan tillhör fortfarande server‑sidans dokumentsession identifierad av token. Att öppna källan igen skapar en ny session; spara XML‑ eller kodad annoterings‑omslag i din applikation om annotationer måste överleva bortom sessionens livstid.

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

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

Viewer speglar ladd‑/läsningsoperationerna 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å vad 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 oklara viewer‑token som en permanent annoteringsidentifierare. Koppla beständig annoteringsdata till dina egna dokument‑ och versionsidentifierare.

Säkerhets‑ 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 vara nåbar för servern vid bränning.
• 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 på skärmen.
• Stora frihands‑payloads och högupplösta export ökar minnesanvändning; testa realistiska dokument och zoomvärden.

Felsökning