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.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:
<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:
<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:
annBar.open();
annBar.close();L'API pubblica del Ribbon è:
| Metodo | Scopo |
|---|---|
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,onAnnClosedsono opzioni didocViewer({...}), come ogni callback del visualizzatore.Created,Changed,Deleted, ePropertiessono funzioni globali trovate per nome: l'ID del visualizzatore è prefisso all'evento. Per il visualizzatore in#div_ctlDocl'ID èctlDoc, quindi le funzioni sonoctlDoc_Created,ctlDoc_Changed,ctlDoc_DeletedectlDoc_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):
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):
| Tipo | Note |
|---|---|
StampAnnotation | Timbro di testo con dimensione del carattere, bordo, colore; supporta Opacity, Rotate |
NoteAnnotation | Nota adesiva con testo, colore di sfondo, dimensione del carattere, TitleColor |
RectangleAnnotation | Colori di bordo + riempimento, Title/ShowTitle |
CircleAnnotation | Bordo + riempimento, ShowBorder |
EllipseAnnotation | Bordo + riempimento, ShowBorder |
TriangleAnnotation | Colore del bordo, BackColor, ShowBorder |
LineAnnotation | Linea retta con larghezza e colore |
ArrowAnnotation | Linea con punta di freccia; Direction impostabile (tipo ArrowDirection, punti della bussola, predefinito E) |
FreehandAnnotation | Tratto libero da punti codificati FreehandData |
ImageAnnotation | Immagine 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
| Membro | Scopo |
|---|---|
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
// 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:
| Superficie | Chi scarica l'immagine | Su un host intranet o di sviluppo |
|---|---|---|
| Il visualizzatore nel browser | Il browser dell'utente | L'immagine appare |
ExportAnnotationsToPdfAsync / …PngZipAsync | Il server | Un 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
- Apri il documento e ottieni il suo token.
- Carica XML o dati codificati precedentemente memorizzati in quel token.
- Consenti al widget di leggere e modificare le annotazioni della sessione.
- Recupera XML con
GetAnnotationXML(token)quando la tua applicazione decide di persistere. - Esporta PDF/PNG quando è richiesto un deliverable appiattito.
- 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
| Sintomo | Verifica |
|---|---|
| Il nastro delle annotazioni è mancante | capacità Annotation e i quattro flag CSS/script delle annotazioni |
| Il callback di salvataggio segnala un errore | Scadenza del token/sessione e middleware BasePath |
ctlDoc_Created (o un'altra funzione evento) non viene mai eseguita | Il nome della funzione: id del visualizzatore + _ + evento, come funzione globale |
| Le annotazioni C# non compaiono | La numerazione delle pagine è a base uno e i dati sono stati caricati nel token attivo |
| L'annotazione immagine appare sullo schermo ma non nell'esportazione | L'host dell'immagine ha un indirizzo privato o di loopback — vedi sopra |
| Il documento riaperto non ha annotazioni | Persisti XML/dati al di fuori della sessione del visualizzatore, poi caricali nel nuovo token |
Questa pagina è stata utile?