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 podmíněna licenční schopností Annotation (udělenou automaticky při aktivní dočasné licenci).

Povolení UI 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í připojen a připojen k téže instanci.

Vydávejte balíčky anotací spolu s balíčky prohlížeče — jsou podmíněny licencí, takže značky se zobrazí pouze když je schopnost k dispozici:

@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">
    <!-- Ovládací prvky prohlížeče, včetně tlačítka, které otevírá Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Balíček anotací generuje DOM Ribbonu uvnitř annBarMount; není nutné 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: '/',
        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ánku. 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é hostitelské zpětné volání. 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ří serverové relaci dokumentu identifikované tokenem. Opětovné otevření zdroje vytvoří novou relaci; pokud anotace musí přežít po ukončení relace, uložte XML nebo kódovaný obal anotací ve své aplikaci.

Vytvoření anotací 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) =>
{
    // Vázáno na rozměry stránky otevřené relace
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Jedno razítko na stránku
    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));

    // Načíst do relace — widget je načte přes AnnLoad a
    // renderer je zapracuje do exportů obrázku/PDF.
    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 vypálenými anotacemi

// PDF všech stránek s anotacemi vykreslenými na nich
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");
});

// Nebo ZIP s PNG soubory po jednotlivých stránkách
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");
});

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

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 načíst a upravit anotace relace.
4. Získejte XML pomocí GetAnnotationXML(token), když se vaše aplikace rozhodne data uložit.
5. Exportujte PDF/PNG, pokud 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í.

Poznámky k zabezpečení a vykreslování

• Požadavky na anotaci používají stejnou bezpečnost relace/tokenu jako požadavky na stránky.
• Relativní ImageAnnotation URL je řešeno z hostitele požadavku a musí zůstat přístupné serveru během vypalování.
• Ověřujte a kontrolujte jakoukoli uživatelem dodanou URL obrázku, aby se předešlo podvržení požadavku na straně serveru.
• Exporty používají stejné rozhodnutí o licenci/vlastní vodoznaku jako vykreslování stránky na obrazovce.
• Velké payloady volného kreslení a exporty ve vysokém rozlišení zvyšují spotřebu paměti; testujte realistické dokumenty a hodnoty přiblížení.

Řešení problémů