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):
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:
<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.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:
| Metodo | Scopo |
|---|---|
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,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 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):
// 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):
| 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 e riempimento, Title/ShowTitle |
CircleAnnotation | Bordo e riempimento, ShowBorder |
EllipseAnnotation | Bordo e riempimento, ShowBorder |
TriangleAnnotation | Colore del bordo, BackColor, ShowBorder |
LineAnnotation | Linea retta con spessore e colore |
ArrowAnnotation | Linea con punta di freccia; Direction impostabile (ArrowDirection, punti cardinali, default E) |
FreehandAnnotation | Tratto libero da punti codificati FreehandData |
ImageAnnotation | Immagine 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
| Membro | Scopo |
|---|---|
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
// 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:
| 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 "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
- 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 o PNG quando è richiesto un deliverable appiattito.
- 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
| Sintomo | Controllo |
|---|---|
| La barra degli strumenti di annotazione è mancante | La capacità Annotation e le quattro flag CSS/script di annotazione |
| Il salvataggio segnala un errore | Scadenza del token o della sessione, e il BasePath del widget |
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 | I numeri di pagina partono da 1, e i dati sono stati caricati nel token attivo |
| Un'annotazione immagine appare sullo schermo ma non nell'esportazione | L'host dell'immagine ha un indirizzo privato o di loopback — vedi sopra |
| Un documento riaperto non ha annotazioni | Persisti XML o dati al di fuori della sessione del visualizzatore, poi caricali nel nuovo token |
Questa pagina è stata utile?