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 ukládá per stránku, nebo váš kód je vytváří programově a načítá do otevřené relace. V každém případě se vykreslují na stránkách a mohou být vloženy do exportů PDF/PNG.
Podpora anotací je řízena schopností licence Annotation (udělenou automaticky při aktivní dočasné licenci).
Povolení uživatelského rozhraní anotací
Anotace je modul Viewer, nikoli samostatná lišta nástrojů. Celá 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 balíčky anotací spolu s balíčky vieweru — jsou řízeny licencí, takže značky se zobrazí pouze když je schopnost dostupná:
@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 // vložený pás anotací
}))Udržujte kompletní kompozici Vieweru viditelnou v značkování:
<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>Balíček anotací generuje DOM Ribbonu uvnitř annBarMount; nemusíte kopírovat jeho tlačítka ani značkování dialogu. Nejprve inicializujte docViewer, pak vytvořte Ribbon pouze když server potvrdí, že anotace jsou licencovány:
<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>Bez této schopnosti ReferenceScripts vynechává skript Ribbonu, takže serverová if udržuje nechráněné volání doconutAnnotationBar(...) před poškozením stránky.
Ukládání z Ribbonu odesílá data přes prostřední vrstvu (AnnSave), která je ukládá do relace dokumentu per stránku. Načítání (AnnLoad) probíhá automaticky, když se vykreslí stránka s anotacemi. Čtyři zpětné volání onAnn* udržují Ribbon synchronizovaný s životním cyklem vieweru.
Otevřete a zavřete jej z libovolné hostitelské lišty Vieweru:
annBar.open();
annBar.close();Veřejné API Ribbonu je:
| Metoda | Účel |
|---|---|
attach(objViewer) | Připojte Ribbon k inicializovanému vieweru; vyžadováno jednou |
open() / close() | Zahájit nebo opustit úpravu anotací |
reset() | Vrátit Ribbon do uzavřeného, needitačního stavu |
isOpen() / annotating() | Přečíst stav Ribbonu / stav úpravy anotací vieweru |
reopenEditable() | Znovu načíst anotace aktuální stránky jako editovatelné objekty |
updateActionState() | Obnovit dostupnost ovládacích prvků uložení/odstranění po změnách hosta |
headerSlot() | Získat volitelný slot rozšíření hlavičky pro hostitelské ovládací prvky |
onStatus, onToast, onLayout, onEditStart a onEditEnd jsou volitelné hostitelské zpětné volání. Objekt endpoints může navíc poskytovat exportPdf, exportPng, imageUpload a imageList; ovládací prvky bez nakonfigurovaného koncového bodu zůstávají skryté.
Pro sekvenci spouštění kombinovaného Vieweru, Search a Annotation viz Rychlý start.
Balíček anotací přidává nástroje pro tvorbu v prohlížeči, ale data stále patří serverové relaci dokumentu identifikované tokenem. Opětovné otevření zdroje vytvoří novou relaci; v aplikaci uchovejte XML nebo kódovaný obal anotací, pokud anotace musí přežít po dobu životnosti relace.
Dva druhy 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 volby prodocViewer({...}), 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 byl uložen: 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 vázaného na otevřenou relaci, přidejte anotace a načtěte je (s using Doconut.Annotations; pro typy a using System.Drawing; pro Rectangle/Color):
app.MapPost("/api/annotations/load-sample", (string token, Viewer 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 — widget je načte přes AnnLoad a
// renderer je vypálí do exportů obrázků/PDF.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});Typy anotací
Všechny typy jsou v Doconut.Annotations a dědí z BaseAnnotation (číslo stránky + 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 + výplně, Title/ShowTitle |
CircleAnnotation | Okraj + výplň, ShowBorder |
EllipseAnnotation | Okraj + výplň, ShowBorder |
TriangleAnnotation | Barva okraje, BackColor, ShowBorder |
LineAnnotation | Přímá čára s šířkou a barvou |
ArrowAnnotation | Čára se šipkou; nastavitelný Direction (typ ArrowDirection, směrové body, výchozí E) |
FreehandAnnotation | Volná čára z kódovaných FreehandData bodů |
ImageAnnotation | Obrázek z URL. Relativní URL je vyřešena vůči hostiteli požadavku, když je anotace přidána; server načte obrázek až při vypálení — viz poznámka o 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ý řetězec dat anotace — Base64 obálka (co widgetu spotřebuje) |
GetAnnotationXml() | XML forma |
Viewer zrcadlí operace načítání/čtení vůči relaci: LoadAnnotationData(token, manager) nebo LoadAnnotationData(token, encodedData) (Base64 obálka z GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
Export s vloženými anotacemi
// PDF všech stránek s anotacemi vykreslenými na nich
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");
});
// Nebo ZIP s PNG soubory pro každou stránku
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");
});Exporty používají stejný vypalovač jako vykreslování na obrazovce, takže to, co uživatelé vidí, je to, co soubor obsahuje — s výjimkou obrázkových anotací, popsaných níže.
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:
| Rozhraní | 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. To chrání server před využitím k přístupu k interním systémům pomocí upravené 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 trvalosti
- 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/PNG, když je požadován zploštělý výstup.
- Uzavřete relaci dokumentu.
Nepoužívejte neprůhledný token prohlížeče jako trvalý identifikátor anotace. Spojte uložená data anotací s vašimi vlastními identifikátory dokumentu a verzí.
Poznámky k zabezpečení a vykreslování
- Požadavky na anotace používají stejnou bezpečnost relace/tokenu jako požadavky na stránky.
- Ověřujte a kontrolujte jakoukoli uživatelem dodanou URL obrázku, aby se zabránilo podvržení požadavku na straně serveru.
- Exporty používají stejné rozhodnutí o licenci/vlastní vodoznaku jako vykreslování stránky na obrazovce.
- Velké volné náklady a exporty ve vysokém rozlišení zvyšují využití paměti; testujte realistické dokumenty a hodnoty přiblížení.
Odstraňování potíží
| Příznak | Kontrola |
|---|---|
| Chybí pás anotací | schopnost Annotation a čtyři příznaky CSS/skriptů anotací |
| Uložený zpětný volání hlásí chybu | Vypršení tokenu/relace a middleware BasePath |
ctlDoc_Created (nebo jiná funkce události) se nikdy nespustí | Název funkce: ID prohlížeče + _ + událost, jako globální funkce |
| Anotace C# se nezobrazují | Číslování stránek začíná od jedné a data byla načtena do aktivního tokenu |
| Anotace obrázku se zobrazí 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/data mimo relaci prohlížeče, poté je načtěte do nového tokenu |
Byla tato stránka užitečná?