Annotazioni

Aggiungi il supporto alle annotazioni al visualizzatore

Le annotazioni in Doconut funzionano in due direzioni: gli utenti le disegnano nel widget del browser e il server le conserva per pagina, oppure il tuo codice le crea e le carica in una sessione aperta. In entrambi i casi vengono renderizzate nelle pagine e possono essere incorporate in esportazioni PDF o PNG.

Il supporto alle annotazioni è limitato dalla capacità di licenza Annotation (concessa automaticamente con una licenza Temporanea attiva).

Abilita l'interfaccia delle annotazioni

L'annotazione è un modulo Viewer, non una barra degli strumenti autonoma. La pagina deve includere le risorse Viewer, la barra degli strumenti Viewer, il mount Viewer e un objViewer inizializzato; il Ribbon delle Annotazioni viene quindi montato e collegato alla stessa istanza.

Emetti i file delle annotazioni insieme ai file del viewer. Sono soggetti a licenza, quindi i loro tag compaiono solo quando la capacità è concessa. In MVC 5, costruisci i tag nel controller (le viste non hanno @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   // il nastro di annotazione incorporato
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Mantieni la composizione completa del Viewer nel markup:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Controlli del Viewer, inclusi il pulsante che apre Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

I file delle Annotazioni generano il Ribbon all'interno di annBarMount; non devi copiare i suoi pulsanti o dialoghi. Inizializza prima docViewer, quindi crea il Ribbon solo quando il server conferma che le Annotazioni sono licenziate:

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>

Senza la capacità, ReferenceScripts omette lo script del Ribbon, così il if lato server mantiene una chiamata doconutAnnotationBar(...) non protetta dal rompere la pagina. In Web Forms, scrivi la stessa protezione come <% if (IsAnnotationEnabled) { %> … <% } %>.

Il salvataggio dal Ribbon invia i dati a DocImage.axd (AnnSave), che li memorizza nella sessione del documento per pagina. Il caricamento (AnnLoad) avviene automaticamente quando una pagina con annotazioni viene renderizzata.

Apri e chiudi il Ribbon dalla tua barra degli strumenti con annBar.open() e annBar.close(). La sua API pubblica:

MetodoScopo
attach(objViewer)Collega il Ribbon al visualizzatore inizializzato; richiesto una volta
open() / close()Entra o esci dalla modifica delle annotazioni
reset()Riporta il Ribbon al suo stato chiuso, non in modifica
isOpen() / annotating()Leggi lo stato del Ribbon / lo stato di modifica delle annotazioni del visualizzatore
reopenEditable()Ricarica le annotazioni della pagina corrente come oggetti modificabili
updateActionState()Aggiorna i controlli di salvataggio ed eliminazione dopo le modifiche dell'host
headerSlot()Lo slot opzionale dell'intestazione per i controlli di proprietà dell'host

onStatus, onToast, onLayout, onEditStart e onEditEnd sono callback opzionali dell'host. L'oggetto endpoints può anche fornire exportPdf, exportPng, imageUpload e imageList; i controlli senza un endpoint configurato rimangono nascosti.

Due tipi di callback, collegati in due modi

Il codice di annotazione utilizza due stili di callback, e ciascuno fallisce silenziosamente quando è collegato nell'altro modo:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed sono opzioni di docViewer({...}), come ogni callback del visualizzatore.
  • Created, Changed, Deleted, e Properties sono funzioni globali trovate per nome: l'ID del visualizzatore è prefisso all'evento. Per il visualizzatore in #div_ctlDoc l'ID è ctlDoc, quindi le funzioni sono ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted e ctlDoc_Properties. Una funzione con nome errato o rinominata semplicemente non viene mai chiamata.

SaveAnnotations() non restituisce se ha salvato: il risultato arriva tramite onAnnSaved o onAnnSaveError. Il codice che legge il valore di ritorno non cancella mai il flag delle "modifiche non salvate".

Crea annotazioni in C#

Ottieni un manager associato alla sessione aperta, aggiungi annotazioni e caricale (con using Doconut.Annotations; per i tipi e using System.Drawing; per Rectangle e Color):

csharp
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // Legato alle dimensioni della pagina della sessione aperta
    var manager   = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Un timbro per pagina
    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));

    // Carica nella sessione - il visualizzatore li recupera e il renderer li incorpora
    // esportazioni image/PDF.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

Tipi di annotazione

Tutti i tipi risiedono in Doconut.Annotations e ereditano da BaseAnnotation (numero di pagina più il Rectangle di delimitazione):

TipoNote
StampAnnotationTimbro di testo con dimensione del carattere, bordo, colore; supporta Opacity, Rotate
NoteAnnotationNota adesiva con testo, colore di sfondo, dimensione del carattere, TitleColor
RectangleAnnotationColori di bordo e riempimento, Title/ShowTitle
CircleAnnotationBordo e riempimento, ShowBorder
EllipseAnnotationBordo e riempimento, ShowBorder
TriangleAnnotationColore del bordo, BackColor, ShowBorder
LineAnnotationLinea retta con spessore e colore
ArrowAnnotationLinea con punta di freccia; Direction impostabile (ArrowDirection, punti cardinali, default E)
FreehandAnnotationTratto libero da punti codificati FreehandData
ImageAnnotationImmagine da un URL. Un URL relativo viene risolto rispetto all'host della richiesta corrente quando l'annotazione viene aggiunta — vedi la nota di esportazione sotto

L'API di AnnotationManager

MembroScopo
Add(BaseAnnotation)Accoda un'annotazione
GetAnnotations() / GetAnnotations(int page)Ispeziona cosa contiene il manager
ClearAnnotations() / ClearAnnotations(int page)Rimuovi tutti / per pagina
GetAnnotationData() / GetAnnotationData(int page)Dati di annotazione codificati — la busta che il widget consuma
GetAnnotationXml()Forma XML

Viewer rispecchia le operazioni di caricamento e lettura rispetto a una sessione: LoadAnnotationData(token, manager) o LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml), e GetAnnotationXML(token).

Esporta con annotazioni incorporate

csharp
// PDF di tutte le pagine con le annotazioni renderizzate su di esse
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");
}

// Oppure un ZIP di PNG per pagina
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");
}

Le esportazioni usano lo stesso bruciatore del rendering su schermo, e la stessa licenza e decisione di filigrana personalizzata.

Annotazioni immagine su un host intranet esportate come "Image blocked"

Il visualizzatore e l'esportazione recuperano l'immagine di un ImageAnnotation da luoghi diversi:

SuperficieChi scarica l'immagineSu un host intranet o di sviluppo
Il visualizzatore nel browserIl browser dell'utenteL'immagine appare
ExportAnnotationsToPdfAsync / …PngZipAsyncIl serverUn segnaposto rosso "Image blocked"

Quando il server recupera un'immagine per incorporarla, rifiuta gli indirizzi che puntano nuovamente a reti private: loopback (localhost, 127.0.0.1), 0.0.0.0, link-local (169.254.x.x), le gamme private 10.x, 172.16–31.x e 192.168.x, NAT di tipo carrier‑grade (100.64.0.0/10) e gli indirizzi IPv6 link‑local e unique‑local. Questo protegge il server dall'essere usato per raggiungere sistemi interni tramite un URL immagine manipolato, e non esiste un interruttore per disattivarlo.

Un URL immagine relativo viene risolto rispetto all'host della richiesta corrente, quindi su localhost, su un server intranet, o su qualsiasi sito raggiunto tramite un indirizzo privato, l'immagine viene mostrata nel visualizzatore e l'esportazione contiene invece il segnaposto. Questo è il meccanismo di protezione in azione, non un errore di rendering. Se le esportazioni devono contenere l'immagine, servila da un host con indirizzo pubblico e usa un URL assoluto. Un nome host che non può essere risolto viene rifiutato allo stesso modo; qualsiasi altro errore di download mostra l'URL e il messaggio di errore in rosso dove sarebbe l'immagine.

Flusso di lavoro di persistenza

  1. Apri il documento e ottieni il suo token.
  2. Carica XML o dati codificati precedentemente memorizzati in quel token.
  3. Consenti al widget di leggere e modificare le annotazioni della sessione.
  4. Recupera XML con GetAnnotationXML(token) quando la tua applicazione decide di persistere.
  5. Esporta PDF o PNG quando è richiesto un deliverable appiattito.
  6. Chiudi la sessione del documento.

Non utilizzare il token del visualizzatore come identificatore permanente delle annotazioni — scade con la sessione, e un riciclo del pool di applicazioni termina ogni sessione su un singolo server. Conserva i dati delle annotazioni associandoli ai tuoi identificatori di documento e versione.

Note su sicurezza e rendering

  • Le richieste di annotazione utilizzano la stessa sicurezza di sessione e token delle richieste di pagina.
  • Convalida e controlla qualsiasi URL immagine fornito dall'utente.
  • Carichi di disegni liberi di grandi dimensioni e esportazioni ad alta risoluzione aumentano l'uso di memoria; testa documenti realistici e valori di zoom.

Risoluzione dei problemi

SintomoControllo
La barra degli strumenti di annotazione è mancanteLa capacità Annotation e le quattro flag CSS/script di annotazione
Il salvataggio segnala un erroreScadenza del token o della sessione, e il BasePath del widget
ctlDoc_Created (o un'altra funzione evento) non viene mai eseguitaIl nome della funzione: id del visualizzatore + _ + evento, come funzione globale
Le annotazioni C# non compaionoI numeri di pagina partono da 1, e i dati sono stati caricati nel token attivo
Un'annotazione immagine appare sullo schermo ma non nell'esportazioneL'host dell'immagine ha un indirizzo privato o di loopback — vedi sopra
Un documento riaperto non ha annotazioniPersisti XML o dati al di fuori della sessione del visualizzatore, poi caricali nel nuovo token

Questa pagina è stata utile?