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 každém případě se vykreslují na stránkách a mohou být vloženy do exportů PDF/PNG.

Podpora anotací je řízena schopností licence Annotation (udě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, připojení 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
@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 značkování:

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 značkování dialogu. Nejprve inicializujte docViewer, pak 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 prostřední vrstvu (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()Zahájit nebo opustit úpravu 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ž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é 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; v aplikaci uchovejte XML nebo kódovaný obal anotací, pokud anotace musí přežít po dobu životnosti relace.

Dva druhy 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 pro 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
    // 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 se š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 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 widgetu 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 obrázkový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" 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. To chrání server před využitím k přístupu k interním systémů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 trvalosti

  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án zploštělý výstup.
  6. Uzavřete relaci dokumentu.

Nepouží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 dodanou 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í.

Odstraňování potíží

PříznakKontrola
Chybí pás anotacíschopnost Annotation a čtyři příznaky CSS/skriptů anotací
Uložený zpětný volání hlásí chybuVypršení tokenu/relace a middleware BasePath
ctlDoc_Created (nebo jiná funkce události) 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á?