Anotace

Přidejte podporu anotací do prohlížeče

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á 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í uživatelského rozhraní anotací

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

Vytvořte balíčky anotací spolu s balíčky prohlížeče — jsou podmíněny licencí, takže značky se objeví pouze když je schopnost dostupná:

html
@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  // vložená páska anotací
}))

Udržujte kompletní kompozici Viewer viditelnou v markupu:

html
<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 Ribbon DOM uvnitř annBarMount; nemusíte kopírovat jeho tlačítka ani markup dialogu. Nejprve inicializujte docViewer, poté vytvořte Ribbon pouze když server potvrdí, že anotace jsou licencovány:

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

Bez této schopnosti ReferenceScripts vynechává skript Ribbon, takže serverová if udržuje nechráněné volání doconutAnnotationBar(...), které by mohlo stránku rozbít.

Ukládání z Ribbon 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 callbacky onAnn* udržují Ribbon synchronizovaný s životním cyklem prohlížeče.

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

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

Veřejné API Ribbon je:

MetodaÚčel
attach(objViewer)Připojte Ribbon k inicializovanému prohlížeči; vyžadováno jednou
open() / close()Zahájit nebo opustit editaci anotací
reset()Vrátit Ribbon do uzavřeného, needitačního stavu
isOpen() / annotating()Přečíst stav Ribbon / stav editace anotací v prohlížeči
reopenEditable()Znovu načíst anotace aktuální stránky jako editovatelné objekty
updateActionState()Obnovit dostupnost ovládacích prvků pro uložení/odstranění po změnách hosta
headerSlot()Získat volitelný slot rozšíření hlavičky pro hostitelské ovládací prvky

onStatus, onToast, onLayout, onEditStart a onEditEnd jsou volitelné hostitelské callbacky. 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 Viewer, 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řetrvávat i po ukončení relace, uložte XML nebo kódovaný obal anotací ve své aplikaci.

Dva typy zpětných volání, zapojené dvěma způsoby

Kód anotací používá dva styly zpětných volání a každý selže tiše, když je zapojen opačným způsobem:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed jsou volby docViewer({...}), jako každé zpětné volání prohlížeče.
  • Created, Changed, Deleted a Properties jsou globální funkce nalezené podle názvu: ID prohlížeče je předponou události. Pro prohlížeč v #div_ctlDoc je ID ctlDoc, takže funkce jsou ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted a ctlDoc_Properties. Špatně napsaná nebo přejmenovaná funkce se prostě nikdy nevolá.

SaveAnnotations() nevrací, zda uložilo: výsledek přichází přes onAnnSaved nebo onAnnSaveError. Kód, který čte jeho návratovou hodnotu, nikdy nevymaže příznak „neuložených změn“.

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

csharp
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čítá přes AnnLoad a
    // renderer je vypálí do exportů obrázků/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):

TypPoznámky
StampAnnotationTextové razítko s velikostí písma, okrajem, barvou; podporuje Opacity, Rotate
NoteAnnotationLepící poznámka s textem, barvou pozadí, velikostí písma, TitleColor
RectangleAnnotationBarvy okraje + výplně, Title/ShowTitle
CircleAnnotationOkraj + výplň, ShowBorder
EllipseAnnotationOkraj + výplň, ShowBorder
TriangleAnnotationBarva okraje, BackColor, ShowBorder
LineAnnotationPřímá čára s šířkou a barvou
ArrowAnnotationČára s šipkou; nastavitelný Direction (typ ArrowDirection, směrové body, výchozí E)
FreehandAnnotationVolná čára z kódovaných FreehandData bodů
ImageAnnotationObrázek z URL. Relativní URL je vyřešena vůči hostiteli požadavku, když je anotace přidána; server načte obrázek až při vypálení — viz poznámka k exportu níže

API AnnotationManageru

ČlenÚčel
Add(BaseAnnotation)Zařadit anotaci do fronty
GetAnnotations() / GetAnnotations(int page)Prozkoumat, co správce obsahuje
ClearAnnotations() / ClearAnnotations(int page)Odstranit vše / podle stránky
GetAnnotationData() / GetAnnotationData(int page)Kódovaný řetězec dat anotace — Base64 obálka (co widget spotřebuje)
GetAnnotationXml()XML forma

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

csharp
// 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 pro každou stránku
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 — s výjimkou obrazových anotací, popsaných níže.

Anotace obrázků na intranetovém hostiteli exportují jako „Image blocked“

Prohlížeč a export získávají obrázek ImageAnnotation z různých míst:

RozhraníKdo stahuje obrázekNa intranetovém nebo vývojovém hostiteli
Prohlížeč v prohlížečiProhlížeč uživateleObrázek se zobrazí
ExportAnnotationsToPdfAsync / …PngZipAsyncServerČervený "Image blocked" zástupný prvek

Když server načte obrázek, aby jej vložil, odmítá adresy, které směřují zpět do soukromých sítí: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), soukromé rozsahy 10.x, 172.16–31.x a 192.168.x, carrier‑grade NAT (100.64.0.0/10) a IPv6 link‑local a unique‑local adresy. Toto chrání server před použitím k dosažení interních systémů pomocí upravené URL obrázku a neexistuje žádný přepínač, který by to vypnul.

Relativní URL obrázku se rozřeší vůči hostiteli aktuálního požadavku, takže na localhost, na intranetovém serveru nebo na jakémkoli webu dosažitelném přes soukromou adresu, se obrázek zobrazí v prohlížeči a export místo toho obsahuje zástupný prvek. To je fungující ochrana, ne selhání vykreslování. Pokud exporty musí obsahovat obrázek, poskytujte jej z hostitele s veřejnou adresou a použijte absolutní URL. Název hostitele, který nelze rozpoznat, je odmítnut stejným způsobem; jakékoli jiné selhání stahování zobrazí URL a chybovou zprávu červeně tam, kde by měl být obrázek.

Pracovní postup trvalého uložení

  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, když je požadována zploštělá výstupní verze.
  6. Uzavřete relaci dokumentu.

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

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

  • Požadavky na anotace používají stejnou bezpečnost relace/tokenu jako požadavky na stránky.
  • Ověřujte a kontrolujte jakoukoli uživatelem poskytnutou URL obrázku, aby se zabránilo 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é náklady 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ů

PříznakKontrola
Chybí páska anotacíAnnotation schopnost a čtyři příznaky CSS/skriptů pro anotace
Uložený zpětný volání hlásí chybuVypršení platnosti tokenu/relace a middleware BasePath
ctlDoc_Created (nebo jiná událostní funkce) se nikdy nespustíNázev funkce: id prohlížeče + _ + událost, jako globální funkce
C# anotace se nezobrazujíČíslování stránek začíná od jedné a data byla načtena do aktivního tokenu
Anotace obrázku se zobrazí na obrazovce, ale ne v exportuHostitel obrázku má soukromou nebo loopback adresu — viz výše
Znovu otevřený dokument nemá anotaceUložte XML/data mimo relaci prohlížeče a poté je načtěte do nového tokenu

Byla tato stránka užitečná?