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 uchovává po stránkách, nebo je váš kód vytvoří a načte do otevřené relace. V obou případech se zobrazují na stránkách a mohou být vloženy do exportů PDF nebo PNG.

Cesta k podpoře anotací je omezena schopností licence 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ů. 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 soubory anotací spolu se soubory vieweru. Jsou omezeny licencí, takže jejich značky se zobrazí pouze při udělení schopnosti. V MVC 5 vytvořte značky v kontroleru (pohledy nemají @inject):

csharp
public class ViewerController : Controller
{
    public ActionResult Index()
    {
        var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
        ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
        {
            IncludeViewerCss     = true,
            IncludeAnnotationCss = true    // jquery-ui.min.css + annotationBar.css
        });
        ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
        {
            IncludeJQuery            = true,
            IncludeViewerScripts     = true,
            IncludeAnnotationScripts = true,  // jquery-ui, raphael.js, annotation.js
            IncludeAnnotationBar     = true   // vložený pás anotací
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Uchovejte kompletní kompozici Vieweru 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>

Soubor anotací generuje Ribbon uvnitř annBarMount; nekopírujete jeho tlačítka ani dialogy. Nejprve inicializujte docViewer, pak vytvořte Ribbon pouze tehdy, když server potvrdí, že anotace jsou licencovány:

html
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
    var annBar = null;
    var currentToken = '';

    var objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        ResPath:  'doconut-res/images',
        onAnnLoaded:    function () { if (annBar) annBar.handleAnnLoaded(); },
        onAnnSaved:     function () { if (annBar) annBar.handleAnnSaved(); },
        onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
        onAnnClosed:    function () { if (annBar) annBar.handleAnnClosed(); },
        onError:        function (message) { console.error('Viewer error:', message); }
    });

    @if ((bool)ViewBag.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: function () { return { token: currentToken }; },
        onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

Bez této schopnosti ReferenceScripts vynechá skript Ribbonu, takže serverová if udržuje nechráněné volání doconutAnnotationBar(...), které by mohlo stránku rozbít. Ve Web Forms napište stejnou ochranu jako <% if (IsAnnotationEnabled) { %> … <% } %>.

Ukládání z Ribbonu odesílá data na DocImage.axd (AnnSave), který je ukládá do relace dokumentu po stránkách. Načítání (AnnLoad) probíhá automaticky, když se vykreslí stránka s anotacemi.

Otevřete a zavřete Ribbon ze své vlastní lišty nástrojů pomocí annBar.open() a annBar.close(). Jeho veřejné API:

MetodaÚčel
attach(objViewer)Připojí Ribbon k inicializovanému vieweru; vyžadováno jednou
open() / close()Zahájit nebo opustit editaci anotací
reset()Vrátí Ribbon do uzavřeného, needitačního stavu
isOpen() / annotating()Přečíst stav Ribbonu / stav editace anotací ve vieweru
reopenEditable()Znovu načíst anotace aktuální stránky jako editovatelné objekty
updateActionState()Obnovit ovládací prvky pro uložení a smazání po změnách hosta
headerSlot()Volitelný slot hlavičky pro ovládací prvky vlastněné hostem

onStatus, onToast, onLayout, onEditStart a onEditEnd jsou volitelné zpětné volání hosta. Objekt endpoints může také poskytovat exportPdf, exportPng, imageUpload a imageList; ovládací prvky bez nakonfigurovaného koncového bodu zůstávají skryté.

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

csharp
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<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 - prohlížeč je načte a renderér je vloží do
    // image/PDF exporty.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

Typy anotací

Všechny typy jsou v Doconut.Annotations a dědí z BaseAnnotation (číslo stránky plus 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 a výplň, ShowBorder
EllipseAnnotationOkraj a výplň, ShowBorder
TriangleAnnotationBarva okraje, BackColor, ShowBorder
LineAnnotationPřímá čára s šířkou a barvou
ArrowAnnotationČára se šipkou; nastavitelný Direction (ArrowDirection, směrové body, výchozí E)
FreehandAnnotationVolný tah z kódovaných FreehandData bodů
ImageAnnotationObrázek z URL. Relativní URL je rozřešena vůči hostiteli aktuálního požadavku, když je anotace přidána — 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á data anotace — obálka, kterou widget spotřebuje
GetAnnotationXml()XML forma

Viewer zrcadlí operace načtení a čtení vůči relaci: LoadAnnotationData(token, manager) nebo LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml) a GetAnnotationXML(token).

Export s vloženými anotacemi

csharp
// PDF všech stránek s vykreslenými anotacemi
public async Task<ActionResult> ExportPdf(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", "export.pdf");
}

// Nebo ZIP s PNG soubory po stránce
public async Task<ActionResult> ExportPngZip(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(zip, "application/zip", "annotations-png.zip");
}

Exporty používají stejný vypalovač jako vykreslování na obrazovce a stejnou licenci a rozhodnutí o vlastním vodoznaku.

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:

PovrchKdo 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ů prostřednictvím vytvořené 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 pro trvalé 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 nebo PNG, když je vyžadován plochý výstup.
  6. Uzavřete relaci dokumentu.

Neužívejte token prohlížeče jako trvalý identifikátor anotace — zaniká s relací a recyklace aplikačního poolu ukončí každou relaci na jediném serveru. Ukládejte data anotací pod své vlastní identifikátory dokumentu a verze.

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

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

PříznakKontrola
Panel anotací chybíSchopnost Annotation a čtyři příznaky CSS/skriptu pro anotace
Ukládání hlásí chybuToken nebo expirace relace a BasePath widgetu
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íČísla stránek jsou číslována od jedné a data byla načtena do aktivního tokenu
Anotace obrázku se zobrazuje 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 nebo data mimo relaci prohlížeče a poté je načtěte do nového tokenu

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