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 programmaticamente e le carica in una sessione aperta. In entrambi i casi vengono visualizzate nelle pagine e possono essere incorporate nelle esportazioni PDF/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 del Viewer, non una barra degli strumenti autonoma. La pagina completa deve includere le risorse del Viewer, la barra degli strumenti del Viewer, il montaggio del Viewer e objViewer inizializzato; il Ribbon delle annotazioni viene quindi montato e collegato alla stessa istanza.

Emetti i bundle delle annotazioni insieme ai bundle del viewer — sono limitati dalla licenza, quindi i tag compaiono solo quando la capacità è disponibile:

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  // il nastro di annotazione incorporato
}))

Mantieni la composizione completa del Viewer visibile nel markup:

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

Il bundle delle annotazioni genera il DOM del Ribbon all'interno di annBarMount; non è necessario copiare i suoi pulsanti o il markup della finestra di dialogo. Inizializza prima docViewer, quindi crea il Ribbon solo quando il server conferma che le annotazioni sono licenziate:

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>

Senza la capacità, ReferenceScripts omette lo script del Ribbon, quindi il if lato server mantiene una chiamata doconutAnnotationBar(...) non protetta dal rompere la pagina.

Il salvataggio dal Ribbon invia i dati attraverso il middleware (AnnSave), che li memorizza nella sessione del documento per pagina. Il caricamento (AnnLoad) avviene automaticamente quando una pagina con annotazioni viene renderizzata. I quattro callback onAnn* mantengono il Ribbon sincronizzato con il ciclo di vita del viewer.

Apri e chiudilo da qualsiasi barra degli strumenti del Viewer di proprietà dell'host:

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

L'API pubblica del Ribbon è:

MetodoScopo
attach(objViewer)Collega il Ribbon al viewer inizializzato; richiesto una sola volta
open() / close()Entra o esci dalla modalità di 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 viewer
reopenEditable()Ricarica le annotazioni della pagina corrente come oggetti modificabili
updateActionState()Aggiorna la disponibilità dei controlli salva/elimina dopo le modifiche dell'host
headerSlot()Ottieni lo slot opzionale di estensione dell'intestazione per i controlli di proprietà dell'host

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

Per la sequenza di avvio combinata di Viewer, Search e Annotation, vedi Avvio Rapido.

Il bundle delle annotazioni aggiunge gli strumenti di authoring del browser, ma i dati appartengono ancora alla sessione del documento lato server identificata dal token. Riaprire la sorgente crea una nuova sessione; conserva l'XML o l'involucro di annotazione codificato nella tua applicazione se le annotazioni devono sopravvivere oltre la durata della sessione.

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 scritta in modo 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 legato alla sessione aperta, aggiungi annotazioni e caricale (con using Doconut.Annotations; per i tipi e using System.Drawing; per Rectangle/Color):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Vincolato 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 widget li recupera tramite AnnLoad e il
    // renderer li incorpora nelle esportazioni immagine/PDF.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Tipi di annotazione

Tutti i tipi risiedono in Doconut.Annotations e ereditano da BaseAnnotation (numero di pagina + 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 + riempimento, Title/ShowTitle
CircleAnnotationBordo + riempimento, ShowBorder
EllipseAnnotationBordo + riempimento, ShowBorder
TriangleAnnotationColore del bordo, BackColor, ShowBorder
LineAnnotationLinea retta con larghezza e colore
ArrowAnnotationLinea con punta di freccia; Direction impostabile (tipo ArrowDirection, punti della bussola, predefinito E)
FreehandAnnotationTratto libero da punti codificati FreehandData
ImageAnnotationImmagine da un URL. Un URL relativo è risolto rispetto all'host della richiesta quando l'annotazione è aggiunta; il server recupera l'immagine solo al momento della stampa — vedi la nota di esportazione sotto

L'API di AnnotationManager

MembroScopo
Add(BaseAnnotation)Metti in coda un'annotazione
GetAnnotations() / GetAnnotations(int page)Ispeziona ciò che il manager contiene
ClearAnnotations() / ClearAnnotations(int page)Rimuovi tutti / per pagina
GetAnnotationData() / GetAnnotationData(int page)Stringa di dati di annotazione codificata — un involucro Base64 (ciò che il widget consuma)
GetAnnotationXml()Forma XML

Viewer rispecchia le operazioni di caricamento/lettura rispetto a una sessione: LoadAnnotationData(token, manager) o LoadAnnotationData(token, encodedData) (l'involucro Base64 da GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Esporta con annotazioni incorporate

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

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

Le esportazioni usano lo stesso processo di stampa della resa a schermo, quindi ciò che gli utenti vedono è ciò che il file contiene — tranne per le annotazioni immagine, descritte di seguito.

Annotazioni immagine su un host intranet esportano come "Immagine bloccata"

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 "Immagine bloccata"

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), gli intervalli privati 10.x, 172.16–31.x e 192.168.x, carrier‑grade NAT (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'opzione per disattivarlo.

Un URL immagine relativo si risolve 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 visualizza 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/PNG quando è richiesto un deliverable appiattito.
  6. Chiudi la sessione del documento.

Non utilizzare il token del visualizzatore opaco come identificatore permanente delle annotazioni. Associa i dati delle annotazioni persistenti con i tuoi propri identificatori di documento e di versione.

Note di sicurezza e rendering

  • Le richieste di annotazione usano la stessa sicurezza sessione/token delle richieste di pagina.
  • Convalida e controlla qualsiasi URL immagine fornito dall'utente per evitare falsificazioni di richieste lato server.
  • Le esportazioni applicano la stessa decisione di licenza/acqua personalizzata della resa della pagina sullo schermo.
  • Carichi di disegni a mano libera di grandi dimensioni e esportazioni ad alta risoluzione aumentano l'uso della memoria; testa documenti realistici e valori di zoom.

Risoluzione dei problemi

SintomoVerifica
Il nastro delle annotazioni è mancantecapacità Annotation e i quattro flag CSS/script delle annotazioni
Il callback di salvataggio segnala un erroreScadenza del token/sessione e middleware BasePath
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 compaionoLa numerazione delle pagine è a base uno e i dati sono stati caricati nel token attivo
L'annotazione immagine appare sullo schermo ma non nell'esportazioneL'host dell'immagine ha un indirizzo privato o di loopback — vedi sopra
Il documento riaperto non ha annotazioniPersisti XML/dati al di fuori della sessione del visualizzatore, poi caricali nel nuovo token

Questa pagina è stata utile?