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 och laddar dem i en öppen session. I båda fallen renderas de på sidorna och kan brännas in i PDF- eller 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. Sidan måste inkludera Viewer-resurserna, Viewer-verktygsfältet, Viewer-monteringen och en initierad objViewer; Annotations‑Ribbon monteras sedan och fästs på samma instans.

Sänd anmärkningsfilerna tillsammans med viewer-filerna. De är licensstyrda, så deras taggar visas endast när funktionen är beviljad. I MVC 5 byggs taggarna i kontrollern (vyer har ingen @inject):

csharp
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   // det inbäddade annoteringsbandet
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Behåll hela Viewer-sammansättningen i markupen:

html
<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>

Annotations‑filerna genererar Ribbon inuti annBarMount; du kopierar inte dess knappar eller dialoger. Initiera docViewer först, skapa sedan Ribbon endast när servern bekräftar att Anmärkning är licensierad:

html
@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>

Utan funktionen utelämnar ReferenceScripts Ribbon‑skriptet, så server‑sidans if skyddar ett oskyddat doconutAnnotationBar(...)‑anrop från att bryta sidan. I Web Forms skriv samma skydd som <% if (IsAnnotationEnabled) { %> … <% } %>.

Sparande från Ribbon postar data till DocImage.axd (AnnSave), som lagrar det i dokumentsessionen per sida. Laddning (AnnLoad) sker automatiskt när en sida med anmärkningar renderas.

Öppna och stäng Ribbon från ditt eget verktygsfält med annBar.open() och annBar.close(). Dess offentliga API:

MetodSyfte
attach(objViewer)Koppla Ribbon till den initierade viewern; krävs en gång
open() / close()Starta eller avsluta redigering av anmärkningar
reset()Återställ Ribbon till dess stängda, icke‑redigerande tillstånd
isOpen() / annotating()Läs Ribbon‑tillståndet / viewerns anmärknings‑redigeringstillstånd
reopenEditable()Ladda om den aktuella sidans anmärkningar som redigerbara objekt
updateActionState()Uppdatera spara‑ och ta‑bort‑kontrollerna efter värdförändringar
headerSlot()Den valfria rubrikplatsen för värdeägda kontroller

onStatus, onToast, onLayout, onEditStart och onEditEnd är valfria värd‑callback‑funktioner. endpoints‑objektet kan också tillhandahålla exportPdf, exportPng, imageUpload och imageList; kontroller utan en konfigurerad endpoint förblir dolda.

Två typer av callback, kopplade på två sätt

Annotationskoden använder två callback‑stilar, och varje misslyckas tyst när den är kopplad på det andra sättet:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed är alternativ till docViewer({...}), precis som varje viewer‑callback.
  • Created, Changed, Deleted, och Properties är globala funktioner som hittas med namn: viewer‑id:t prefixas till händelsen. För viewern i #div_ctlDoc är id:t ctlDoc, så funktionerna är ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted och ctlDoc_Properties. En felstavad eller omdöpt funktion anropas helt enkelt aldrig.

SaveAnnotations() returnerar inte om den sparades: resultatet kommer via onAnnSaved eller onAnnSaveError. Kod som läser dess returvärde rensar aldrig flaggan för "osparade ändringar".

Skapa 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 och Color):

csharp
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // Bundet till den öppna sessionens sidimensioner
    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));

    // Ladda in i sessionen - visaren hämtar dem, och renderaren bränner in dem i
    // image/PDF-export.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

Annotationstyper

Alla typer finns i Doconut.Annotations och ärver från BaseAnnotation (sidnummer plus avgränsande Rectangle):

TypAnteckningar
StampAnnotationTextstämpel med teckenstorlek, kant, färg; stöder Opacity, Rotate
NoteAnnotationKlistrig lapp med text, bakgrundsfärg, teckenstorlek, TitleColor
RectangleAnnotationKant- och fyllnadsfärger, Title/ShowTitle
CircleAnnotationKant och fyllning, ShowBorder
EllipseAnnotationKant och fyllning, ShowBorder
TriangleAnnotationKantfärg, BackColor, ShowBorder
LineAnnotationRaka linjen med bredd och färg
ArrowAnnotationLinje med pilspets; inställbar Direction (ArrowDirection, kompasspunkter, standard E)
FreehandAnnotationFri penseldrag från kodade FreehandData punkter
ImageAnnotationBild från en URL. En relativ URL löses upp mot den aktuella begärans värd när annotationen läggs till — se exportanteckningen nedan

AnnotationManager‑API

MedlemSyfte
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)Kodat annotationsdata — omslaget som widgeten konsumerar
GetAnnotationXml()XML‑formulär

Viewer speglar laddnings‑ och läsoperationerna mot en session: LoadAnnotationData(token, manager) eller LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml), och GetAnnotationXML(token).

Export med inbrända annotationer

csharp
// PDF av alla sidor med annotationer renderade på dem
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");
}

// Eller en ZIP med PNG-filer per sida
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");
}

Export använder samma brännare som skärmrendering, samt samma licens- och anpassade vattenstämpelbeslut.

Bildanteckningar på en intranätvärd exporteras som "Bild blockerad"

Visaren och exporten hämtar en ImageAnnotations bild från olika platser:

YtaVem laddar ner bildenPå en intranät- eller utvecklingsvärd
Visaren i webbläsarenAnvändarens webbläsareBilden visas
ExportAnnotationsToPdfAsync / …PngZipAsyncServernEn röd "Bild blockerad" 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 det.

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 offentlig 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

  1. Öppna dokumentet och hämta dess token.
  2. Ladda tidigare lagrad XML eller kodad data i den token.
  3. Låt widgeten läsa och redigera sessionsanteckningarna.
  4. Hämta XML med GetAnnotationXML(token) när din applikation bestämmer sig för att spara.
  5. Exportera PDF eller PNG när en platt leverans krävs.
  6. Stäng dokumentsessionen.

Använd inte visartoken som en permanent identifierare för anteckningar — den upphör när sessionen avslutas, och en återställning av applikationspoolen avslutar varje session på en enskild server. Spara anteckningsdata mot ditt eget dokument- och versionsidentifierare.

Säkerhets- och renderingsanteckningar

  • Anteckningsförfrågningar använder samma session‑ och token‑säkerhet som sidförfrågningar.
  • Validera och kontrollera alla användargenererade bild‑URL:er.
  • Stora handritade belastningar och högupplösta export ökar minnesanvändningen; testa realistiska dokument och zoomvärden.

Felsökning

SymtomKontroll
Annotationsbandet saknasAnnotation‑kapaciteten och de fyra annotations‑CSS/script‑flaggorna
Sparande rapporterar ett felToken‑ eller sessionens utgång, samt widgetens BasePath
ctlDoc_Created (eller en annan händelsefunktion) körs aldrigFunktionsnamnet: visare‑id + _ + händelse, som en global funktion
C#‑anteckningar visas inteSidnumren är en‑baserade, och data laddades in i den aktiva token
En bildanteckning visas på skärmen men inte i exportenBildens värd har en privat eller loopback‑adress — se ovan
Ett återöppnat dokument har inga anteckningarSpara XML eller data utanför visarsessionen, ladda sedan in dem i den nya token

Var den här sidan hjälpsam?