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ělována 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 páska Anotací namontována a připojena k téže instanci.

Vydávejte balíčky anotací spolu s balíčky prohlížeče — 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">
    <!-- Ovládací prvky Vieweru, včetně tlačítka, které otevírá anotaci -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Balíček Anotací generuje DOM pásky uvnitř annBarMount; nemusíte kopírovat jeho tlačítka ani markup dialogu. Nejprve inicializujte docViewer, pak vytvořte pásku 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 pásky 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í pásku synchronizovanou s životním cyklem prohlížeče.

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

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

Veřejné API pásky 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 spouš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; v aplikaci uchovejte XML nebo kódovaný obal anotací, pokud anotace musí přežít po dobu životnosti relace.

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) =>
{
    // Svázáno s 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 pomocí AnnLoad a
    // renderér je vloží do exportů obrázku/PDF.
    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

// PDF všech stránek s vykreslenými anotacemi
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 soubor s PNG obrázky po 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ý proces vypálení jako vykreslování na obrazovce, takže to, co uživatelé vidí, je to, co soubor obsahuje.

Pracovní postup pro perzistenci

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 v relaci.
4. Získejte XML pomocí GetAnnotationXML(token), když se vaše aplikace rozhodne data perzistentně uložit.
5. Exportujte PDF/PNG, když je požadován plochý výstup.
6. Uzavřete relaci dokumentu.

Neužívejte neprůhledný token vieweru jako trvalý identifikátor anotace. Propojte perzistentní data anotací s vašimi vlastními identifikátory dokumentu a verzí.

Bezpečnostní a vykreslovací poznámky

• Požadavky na anotace používají stejnou bezpečnost relace/tokenu jako požadavky na stránky.
• Relativní ImageAnnotation URL je řešena z hostitele požadavku a musí zůstat dostupná serveru během vykreslování.
• Ověřujte a kontrolujte jakékoli uživatelem dodané 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é volné kresby a exporty ve vysokém rozlišení zvyšují využití paměti; testujte realistické dokumenty a hodnoty přiblížení.

Odstraňování potíží