Anotace

Anotace v Doconut fungují ve dvou směrech: uživatelé je kreslí v widgetu prohlížeče a server je ukládá per stránku, nebo váš kód je vytváří programově a načítá je do otevřené relace. V obou případech se vykreslují na stránkách a mohou být vloženy do exportů PDF/PNG.

Podpora anotací je řízena licenční schopností Annotation (udělenou automaticky při aktivní dočasné licenci).

Povolit UI anotací

Anotace jsou modul Vieweru, nikoli samostatná lišta nástrojů. Celá stránka musí zahrnovat zdroje Vieweru, lištu nástrojů Vieweru, umístění Vieweru a inicializovaný objViewer; poté je Ribbon anotací připojen a připojen k téže instanci.

Vydávejte balíky anotací spolu s balíky vieweru — jsou řízeny licencí, takže značky se zobrazí pouze když je schopnost dostupná:

@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
}))

Udržujte kompletní kompozici Vieweru viditelnou v markupu:

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

Balík anotací generuje Ribbon DOM uvnitř annBarMount; není potřeba kopírovat jeho tlačítka nebo markup dialogu. Nejprve inicializujte docViewer, pak vytvořte Ribbon pouze když server potvrdí, že anotace jsou licencovány:

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

Ukládání z Ribbonu odesílá data přes middleware (AnnSave), který je ukládá do relace dokumentu per stránka. Načítání (AnnLoad) probíhá automaticky, když se vykreslí stránka s anotacemi. Čtyři zpětné volání onAnn* udržují Ribbon synchronizovaný s životním cyklem vieweru.

Otevřete a zavřete jej z libovolné lišty nástrojů Vieweru vlastněné hostitelem:

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

Veřejné API Ribbonu je:

onStatus, onToast, onLayout, onEditStart a onEditEnd jsou volitelné zpětné volání hosta. Objekt endpoints může navíc poskytovat exportPdf, exportPng, imageUpload a imageList; ovládací prvky bez nakonfigurovaného koncového bodu zůstávají skryté. Pro sekvenci spouštění kombinovaného Vieweru, Search a Annotation viz Rychlý start.

Balík anotací přidává nástroje pro tvorbu v prohlížeči, ale data stále patří serverové relaci dokumentu identifikované tokenem. Znovuotevření zdroje vytvoří novou relaci; pokud anotace musí přežít po ukončení relace, uložte XML nebo kódovaný obálku anotací ve své aplikaci.

Vytvořit anotace v C#

Získejte správce vázaného na otevřenou relaci, přidejte anotace a načtěte je (s using Doconut.Annotations; pro typy a using System.Drawing; pro 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();
});

Typy anotací

Všechny typy jsou v Doconut.Annotations a dědí z BaseAnnotation (číslo stránky + ohraničující Rectangle):

API AnnotationManageru

Viewer zrcadlí operace načítání/čtení vůči relaci: LoadAnnotationData(token, manager) nebo LoadAnnotationData(token, encodedData) (Base64 obálka z GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Export s vloženými anotacemi

Exporty používají stejný proces jako renderování na obrazovce, takže to, co uživatelé vidí, je to, co soubor obsahuje.

// 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");
});

Pracovní postup uchovávání

1. Otevřete dokument a získejte jeho token.
2. Načtěte dříve uložené XML nebo kódovaná data do tohoto tokenu.
3. Nechte widget číst a upravovat anotace v relaci.
4. Získejte XML pomocí GetAnnotationXML(token), když se vaše aplikace rozhodne data uchovat.
5. Exportujte PDF/PNG, když je vyžadován plochý výstup.
6. Uzavřete relaci dokumentu.

Neužívejte neprůhledný token vieweru jako trvalý identifikátor anotace. Spojte uložená data anotací s vlastními identifikátory dokumentu a verzí.

Bezpečnostní a renderovací poznámky

• Požadavky na anotace používají stejnou bezpečnost relace/tokenu jako požadavky na stránky.
• Relativní URL ImageAnnotation je řešeno z hosta požadavku a musí být během vkládání dosažitelné pro server.
• Ověřujte a kontrolujte jakékoli uživatelem dodané URL obrázku, aby nedošlo k podvržení požadavku na server.
• Exporty používají stejné rozhodnutí o licenci/vlastní vodoznaku jako renderování stránek na obrazovce.
• Velké volné kresby a exporty ve vysokém rozlišení zvyšují využití paměti; testujte realistické dokumenty a hodnoty přiblížení.

Řešení problémů