Anotace

Anotace v Doconut fungují ve dvou směrech: uživatelé je kreslí v prohlížečovém widgetu 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 (přidělenou automaticky při aktivní dočasné licenci).

Povolení uživatelského rozhraní anotací

Anotace je modul Viewer, 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í namontován 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íček anotací generuje Ribbon DOM uvnitř annBarMount; nemusíte kopírovat jeho tlačítka ani 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 prohlížeče.

Otevřete a zavřete jej z libovolné hostitelské lišty Vieweru:

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 spuštění kombinovaného Vieweru, Search a Annotation viz Rychlý start.

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

Vytváření anotací v C#

Získejte správce svázaného s otevřenou relací, 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 se nacházejí 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 vypalování jako vykreslová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 přečíst a upravit 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.

Nepoužívejte neprůhledný token vieweru jako trvalý identifikátor anotace. Spojte uložená data anotací s vašimi 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 vyřešena z hostitele požadavku a musí být během vypalování přístupná serveru.
• Ověřte a kontrolujte jakoukoli uživatelem dodanou URL obrázku, aby se zabránilo podvodům s požadavky na server.
• Exporty používají stejná rozhodnutí o licenci/vlastní vodoznaku jako vykreslování stránek na obrazovce.
• Velké payloady volné ruky 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ů