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):
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:
<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.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,onAnnClosedjsou volbydocViewer({...}), jako každé zpětné volání prohlížeče.Created,Changed,Deleted, aPropertiesjsou globální funkce nalezené podle názvu: ID prohlížeče je předponou události. Pro prohlížeč v#div_ctlDocje IDctlDoc, takže funkce jsouctlDoc_Created,ctlDoc_Changed,ctlDoc_DeletedactlDoc_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):
// 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):
| Typ | Poznámky |
|---|---|
StampAnnotation | Textové razítko s velikostí písma, okrajem, barvou; podporuje Opacity, Rotate |
NoteAnnotation | Lepící poznámka s textem, barvou pozadí, velikostí písma, TitleColor |
RectangleAnnotation | Barvy okraje a výplně, Title/ShowTitle |
CircleAnnotation | Okraj a výplň, ShowBorder |
EllipseAnnotation | Okraj a výplň, ShowBorder |
TriangleAnnotation | Barva okraje, BackColor, ShowBorder |
LineAnnotation | Přímá čára s šířkou a barvou |
ArrowAnnotation | Čára se šipkou; nastavitelný Direction (ArrowDirection, směrové body, výchozí E) |
FreehandAnnotation | Volný tah z kódovaných FreehandData bodů |
ImageAnnotation | Obrá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
// 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:
| Povrch | Kdo stahuje obrázek | Na intranetovém nebo vývojovém hostiteli |
|---|---|---|
| Prohlížeč v prohlížeči | Prohlížeč uživatele | Obrázek se zobrazí |
ExportAnnotationsToPdfAsync / …PngZipAsync | Server | Č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í
- Otevřete dokument a získejte jeho token.
- Načtěte dříve uložené XML nebo kódovaná data do tohoto tokenu.
- Nechte widget načíst a upravit anotace relace.
- Získejte XML pomocí
GetAnnotationXML(token), když se vaše aplikace rozhodne data uložit. - Exportujte PDF nebo PNG, když je vyžadován plochý výstup.
- 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říznak | Kontrola |
|---|---|
| Panel anotací chybí | Schopnost Annotation a čtyři příznaky CSS/skriptu pro anotace |
| Ukládání hlásí chybu | Token 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 exportu | Hostitel obrázku má soukromou nebo loopback adresu — viz výše |
| Znovu otevřený dokument nemá žádné anotace | Ulož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á?