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

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

Vydávejte balíčky anotací spolu s balíčky vieweru — 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ás anotací
}))

Udržujte kompletní kompozici Vieweru viditelnou v markup:

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 DOM Ribbonu 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: '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>

Bez této schopnosti ReferenceScripts vynechává skript Ribbonu, takže serverová if udržuje nechráněné volání doconutAnnotationBar(...) před poškozením stránky.

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

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

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

Veřejné API Ribbonu je:

MetodaÚčel
attach(objViewer)Připojte Ribbon k inicializovanému vieweru; vyžadováno jednou
open() / close()Vstoupit do nebo opustit režim úpravy anotací
reset()Vrátit Ribbon do uzavřeného, needitačního stavu
isOpen() / annotating()Přečíst stav Ribbonu / stav úpravy anotací vieweru
reopenEditable()Znovu načíst anotace aktuální stránky jako editovatelné objekty
updateActionState()Obnovit dostupnost ovládacích prvků uložit/smazat 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é 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ří 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.

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 prostě není nikdy volána.

SaveAnnotations() nevrací, zda byl uložen: 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 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):

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čte přes AnnLoad a the
    // renderer je vkládá 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 a 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 při přidání anotace; server načte obrázek až při vypálení — viz poznámka o 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 konzumuje)
GetAnnotationXml()XML forma

Viewer odráží 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 vrytý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 po stránce
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 načítají 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" placeholder

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. Tím se chrání server před tím, aby byl použit k dosažení interních systémů prostřednictvím vytvořené URL obrázku, a neexistuje žádný přepínač, který by to vypnul.

Relativní URL obrázku se rozpozná 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 fungování ochrany, 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 perzistence

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

Neužívejte neprůhledný token prohlížeče 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.
  • Ověřujte a kontrolujte jakékoli uživatelem dodané URL obrázku, aby se zabránilo podvržení požadavku na serveru.
  • Exporty používají stejné rozhodnutí o licenci/vlastní vodoznaku jako vykreslování stránky na obrazovce.
  • Velké volné payloady 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ás anotacíschopnost Annotation a čtyři příznaky CSS/script pro anotace
Uložit zpětné volání hlásí chybuVypršení 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
Anotace C# 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á žádné anotaceUložte XML/data mimo relaci prohlížeče, poté je načtěte do nového tokenu

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