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 obou případech se vykreslují na stránkách a mohou být vloženy do exportů PDF/PNG.
Podpora anotací je podmíněna licenční schopností 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ů. Celá stránka musí zahrnovat zdroje Viewer, lištu nástrojů Viewer, připojení Viewer a inicializovaný objViewer; poté je Ribbon anotací namontován a připojen k téže instanci.
Vytvořte balíčky anotací spolu s balíčky prohlížeče — jsou podmíněny licencí, takže značky se objeví 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áska anotací
}))Udržujte kompletní kompozici Viewer viditelnou 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>Balíček anotací generuje Ribbon DOM uvnitř annBarMount; nemusíte kopírovat jeho tlačítka ani markup dialogu. Nejprve inicializujte docViewer, poté vytvořte Ribbon pouze když server potvrdí, že anotace jsou licencovány:
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
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 Ribbon, takže serverová if udržuje nechráněné volání doconutAnnotationBar(...), které by mohlo stránku rozbít.
Ukládání z Ribbon odesílá data přes middleware (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 callbacky onAnn* udržují Ribbon synchronizovaný s životním cyklem prohlížeče.
Otevřete a zavřete jej z libovolné hostitelské lišty Viewer:
annBar.open();
annBar.close();Veřejné API Ribbon je:
| Metoda | Účel |
|---|---|
attach(objViewer) | Připojte Ribbon k inicializovanému prohlížeči; vyžadováno jednou |
open() / close() | Zahájit nebo opustit editaci anotací |
reset() | Vrátit Ribbon do uzavřeného, needitačního stavu |
isOpen() / annotating() | Přečíst stav Ribbon / stav editace anotací v prohlížeči |
reopenEditable() | Znovu načíst anotace aktuální stránky jako editovatelné objekty |
updateActionState() | Obnovit dostupnost ovládacích prvků pro 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é callbacky. 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 spuštění kombinovaného Viewer, 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; pokud anotace musí přetrvávat i po ukončení relace, uložte XML nebo kódovaný obal anotací ve své aplikaci.
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,DeletedaPropertiesjsou 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 se prostě nikdy nevolá.
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/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čítá 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 s š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 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ý řetězec dat anotace — Base64 obálka (co widget 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 obrazových anotací, popsaných níže.
Anotace obrázků na intranetovém hostiteli exportují jako „Image blocked“
Prohlížeč a export získávají 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. Toto chrání server před použitím k dosažení interních systé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 trvalého 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/PNG, když je požadována zploštělá výstupní verze.
- Uzavřete relaci dokumentu.
Neuží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 poskytnutou 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í.
Řešení problémů
| Příznak | Kontrola |
|---|---|
| Chybí páska anotací | Annotation schopnost a čtyři příznaky CSS/skriptů pro anotace |
| Uložený zpětný volání hlásí chybu | Vypršení platnosti tokenu/relace a middleware BasePath |
ctlDoc_Created (nebo jiná událostní funkce) se nikdy nespustí | Název funkce: id prohlížeče + _ + událost, jako globální funkce |
| C# anotace 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á anotace | Uložte XML/data mimo relaci prohlížeče a poté je načtěte do nového tokenu |
Byla tato stránka užitečná?