Anmärkningar
Lägg till stöd för anmärkningar i visaren
Anmärkningar i Doconut fungerar i två riktningar: användare ritar dem i webbläsarwidgeten och servern sparar dem per sida, eller så bygger din kod dem programatiskt och laddar dem i en öppen session. I båda fallen renderas de på sidorna och kan brännas in i PDF/PNG‑exporter.
Stöd för anmärkningar styrs av licensfunktionen Annotation (tilldelas automatiskt under en aktiv Tillfällig licens).
Aktivera anmärknings‑UI
Anmärkning är en Viewer-modul, inte ett fristående verktygsfält. Den kompletta sidan måste inkludera Viewer-resurserna, Viewer-verktygsfältet, Viewer-monteringen och den initierade objViewer; Annotationsbandet monteras sedan och fästs på samma instans.
Skicka ut anmärkningspaketen tillsammans med visarpaketen — de är licensstyrda, så taggarna visas endast när funktionen är tillgänglig:
@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 // det inbäddade annoteringsbandet
}))Behåll den kompletta Viewer-sammansättningen synlig i markupen:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Visningskontroller, inklusive knappen som öppnar Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Annotationspaketet genererar Ribbon‑DOM:en inuti annBarMount; du behöver inte kopiera dess knappar eller dialog‑markup. Initiera docViewer först, skapa sedan Ribbon endast när servern bekräftar att Anmärkning är licensierad:
<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>Utan funktionen utelämnar ReferenceScripts Ribbon‑skriptet, så server‑sidans if skyddar ett oövervakat doconutAnnotationBar(...)‑anrop från att bryta sidan.
Sparande från Ribbon postar data via middleware (AnnSave), som lagrar den i dokumentsessionen per sida. Laddning (AnnLoad) sker automatiskt när en sida med anmärkningar renderas. De fyra onAnn*‑återanropen håller Ribbon synkroniserad med visarens livscykel.
Öppna och stäng den från vilket host‑ägt Viewer‑verktygsfält som helst:
annBar.open();
annBar.close();Det offentliga Ribbon‑API‑et är:
| Metod | Syfte |
|---|---|
attach(objViewer) | Anslut Ribbon till den initierade visaren; krävs en gång |
open() / close() | Gå in i eller lämna anmärkningsredigering |
reset() | Återställ Ribbon till dess stängda, icke‑redigeringsläge |
isOpen() / annotating() | Läs Ribbon‑status / visarens anmärkningsredigeringsstatus |
reopenEditable() | Ladda om den aktuella sidans anmärkningar som redigerbara objekt |
updateActionState() | Uppdatera tillgänglighet för spara/ta‑bort‑kontroller efter host‑ändringar |
headerSlot() | Hämta den valfria header‑utökningplatsen för host‑ägda kontroller |
onStatus, onToast, onLayout, onEditStart och onEditEnd är valfria host‑återanrop. endpoints‑objektet kan dessutom tillhandahålla exportPdf, exportPng, imageUpload och imageList; kontroller utan en konfigurerad endpoint förblir dolda. För den kombinerade Viewer‑, Search‑ och Annotation‑uppstartssekvensen, se Snabbstart.
Annotationspaketet lägger till webbläsarens författarverktyg, men datan tillhör fortfarande server‑sidans dokumentsession som identifieras av token. Att öppna källan igen skapar en ny session; persistera XML‑ eller kodad anmärknings‑omslag i din applikation om anmärkningar måste överleva bortom sessionens livstid.
Två typer av återuppringning, kopplade på två sätt
Annoteringskoden använder två återuppringningsstilar, och varje misslyckas tyst när den är kopplad på det andra sättet:
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedär alternativ tilldocViewer({...}), precis som varje visningsåteruppringning.Created,Changed,Deleted, ochPropertiesär globala funktioner som hittas efter namn: visnings‑id:t prefixas till händelsen. För visaren i#div_ctlDocär id:tctlDoc, så funktionerna ärctlDoc_Created,ctlDoc_Changed,ctlDoc_Deleted, ochctlDoc_Properties. En felstavad eller omdöpt funktion anropas helt enkelt aldrig.
SaveAnnotations() returnerar inte om den sparade: resultatet kommer via onAnnSaved eller onAnnSaveError. Kod som läser dess returvärde rensar aldrig dess flagga för "osparade ändringar".
Bygg annotationer i C#
Hämta en manager bunden till den öppna sessionen, lägg till annotationer och ladda dem (med using Doconut.Annotations; för typerna och using System.Drawing; för Rectangle/Color):
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// Bundet till den öppna sessionens sidmått
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// En stämpel per sida
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));
// Läs in i sessionen — widgeten hämtar dem via AnnLoad och
// renderaren bränner dem i bild/PDF-exporter.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});Annotationstyper
Alla typer finns i Doconut.Annotations och ärver från BaseAnnotation (sidnummer + avgränsande Rectangle):
| Typ | Anteckningar |
|---|---|
StampAnnotation | Textstämpel med teckenstorlek, kant, färg; stöder Opacity, Rotate |
NoteAnnotation | Klistermärke med text, bakgrundsfärg, teckenstorlek, TitleColor |
RectangleAnnotation | Kant + fyllningsfärger, Title/ShowTitle |
CircleAnnotation | Kant + fyllning, ShowBorder |
EllipseAnnotation | Kant + fyllning, ShowBorder |
TriangleAnnotation | Kantfärg, BackColor, ShowBorder |
LineAnnotation | Raka linjen med bredd och färg |
ArrowAnnotation | Linje med pilspets; inställningsbar Direction (typ ArrowDirection, kompasspunkter, standard E) |
FreehandAnnotation | Fri penseldrag från kodade FreehandData punkter |
ImageAnnotation | Bild från en URL. En relativ URL löses upp mot begärans värd när annotationen läggs till; servern hämtar bilden endast vid bränning — se exportanteckningen nedan |
AnnotationManager‑API:t
| Medlem | Syfte |
|---|---|
Add(BaseAnnotation) | Köa en annotation |
GetAnnotations() / GetAnnotations(int page) | Inspektera vad managern innehåller |
ClearAnnotations() / ClearAnnotations(int page) | Ta bort alla / per sida |
GetAnnotationData() / GetAnnotationData(int page) | Kodad annotation‑data‑sträng — ett Base64‑överföringsomslag (vad widgeten konsumerar) |
GetAnnotationXml() | XML‑formulär |
Viewer speglar laddnings-/läsningsoperationerna mot en session: LoadAnnotationData(token, manager) eller LoadAnnotationData(token, encodedData) (Base64‑överföringsomslaget från GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
Exportera med inbrända annotationer
// PDF av alla sidor med annotationer renderade på dem
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");
});
// Eller en ZIP med PNG-filer per sida
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");
});Exporten använder samma brännare som skärmrendering, så det användarna ser är vad filen innehåller — förutom bildannotationer, som beskrivs nedan.
Bildanteckningar på en intranätvärd exporteras som "Image blocked"
Visaren och exporten hämtar en ImageAnnotations bild från olika platser:
| Yta | Vem laddar ner bilden | På en intranät- eller utvecklingsvärd |
|---|---|---|
| Visaren i webbläsaren | Användarens webbläsare | Bilden visas |
ExportAnnotationsToPdfAsync / …PngZipAsync | Servern | En röd "Image blocked"-platshållare |
När servern hämtar en bild för att bränna in den, avvisar den adresser som pekar tillbaka till privata nätverk: loopback (localhost, 127.0.0.1), 0.0.0.0, link-local (169.254.x.x), de privata intervallen 10.x, 172.16–31.x och 192.168.x, carrier‑grade NAT (100.64.0.0/10) samt IPv6 link‑local och unique‑local adresser. Detta skyddar servern från att användas för att nå interna system via en manipulerad bild‑URL, och det finns ingen omkopplare för att stänga av detta.
En relativ bild‑URL löses mot värden för den aktuella begäran, så på localhost, på en intranät‑server eller på någon webbplats som nås via en privat adress, visas bilden i visaren och exporten innehåller i stället platshållaren. Det är skyddet som fungerar, inte ett renderingsfel. Om exporterna måste innehålla bilden, servera den från en värd med en publik adress och använd en absolut URL. Ett värdnamn som inte kan lösas avvisas på samma sätt; alla andra nedladdningsfel visar URL:en och felmeddelandet i rött där bilden skulle vara.
Arbetsflöde för beständighet
- Öppna dokumentet och hämta dess token.
- Läs in tidigare lagrad XML eller kodad data i den token.
- Låt widgeten läsa och redigera sessionsanteckningarna.
- Hämta XML med
GetAnnotationXML(token)när din applikation bestämmer sig för att spara. - Exportera PDF/PNG när en platt leverans krävs.
- Stäng dokumentsessionen.
Använd inte den ogenomskinliga visartoken som en permanent identifierare för anteckningar. Knyt beständig anteckningsdata till ditt eget dokument- och versionsidentifierare.
Säkerhet och renderingsanteckningar
- Anteckningsförfrågningar använder samma session-/token‑säkerhet som sidförfrågningar.
- Validera och kontrollera alla användargenererade bild‑URL:er för att undvika server‑side request forgery.
- Export använder samma licens‑/anpassade vattenstämpelbeslut som rendering av sidan på skärmen.
- Stora frihands‑payloads och högupplösta export ökar minnesanvändningen; testa realistiska dokument och zoomvärden.
Felsökning
| Symtom | Kontroll |
|---|---|
| Anteckningsbandet saknas | Annotation‑förmåga och de fyra antecknings‑CSS/script‑flaggorna |
| Spara‑återuppringning rapporterar ett fel | Token-/sessionsutgång och middleware BasePath |
ctlDoc_Created (eller en annan händelsefunktion) körs aldrig | Funktionsnamnet: visare‑id + _ + händelse, som en global funktion |
| C#‑anteckningar visas inte | Sidnumrering är en‑baserad och data laddades in i den aktiva token |
| Bildanteckning visas på skärmen men inte i export | Bildens värd har en privat eller loopback‑adress — se ovan |
| Återöppnat dokument har inga anteckningar | Spara XML/data utanför visarsessionen, ladda sedan in den i den nya token |
Var den här sidan hjälpsam?