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 programmässigt 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 är begränsat av licensfunktionen Annotation (tilldelas automatiskt under en aktiv temporär licens).

Aktivera anmärknings‑UI

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

Skicka ut anmärkningspaketen tillsammans med visarpaketen — de är licensbegränsade, 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>

Annotations‑paketet genererar Ribbon‑DOM:en 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 Annotations ä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 anmärkningar renderas. De fyra onAnn*‑återuppringningarna håller Ribbon synkroniserad med visarens livscykel.

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

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

Den publika Ribbon‑API:n är:

onStatus, onToast, onLayout, onEditStart och onEditEnd är valfria host‑återuppringningar. 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 dokumentsession som identifieras av token. Att återöppna källan skapar en ny session; persistera XML‑ eller kodade anmärknings‑omslaget i din applikation om anmärkningar 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) =>
{
    // Bundet till den öppna sessionens sidimensioner
    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
    // renderer 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 + 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 av 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. Läs in 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 begärans värd och måste förbli nåbar för servern vid bränningstid.
• Validera och kontrollera alla användargenererade bild-URL:er för att undvika server‑side request forgery.
• Exporter tillämpar samma licens-/anpassade vattenstämpelbeslut som rendering av sidor på skärmen.
• Stora handritade data och högupplösta export ökar minnesanvändningen; testa realistiska dokument och zoomvärden.

Felsökning