Açıklamalar

Doconut'ta açıklamalar iki yönde çalışır: kullanıcılar bunları tarayıcı widget'ında çizer ve sunucu sayfa başına saklar, ya da kodunuz bunları programlı olarak oluşturur ve açık bir oturuma yükler. Hangi yöntemle olursa olsun, sayfalarda görüntülenir ve PDF/PNG dışa aktarımlarına gömülebilir.

Açıklama desteği, Annotation lisans yeteneğiyle kısıtlanmıştır (aktif bir Geçici lisans altında otomatik olarak verilir).

Açıklama UI'sini Etkinleştirme

Açıklama, bağımsız bir araç çubuğu değil, bir Viewer modülüdür. Tam sayfa Viewer kaynaklarını, Viewer araç çubuğunu, Viewer montajını ve başlatılmış objViewer'ı içermelidir; ardından Açıklama Şeridi aynı örneğe monte edilir ve eklenir.

Annotation paketlerini Viewer paketleriyle birlikte yayınlayın — bunlar lisans kısıtlamalıdır, bu yüzden etiketler yalnızca yetenek mevcut olduğunda görünür:

@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  // the embedded annotation ribbon
}))

Tam Viewer bileşenini işaretlemede görünür tutun:

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer controls, including the button that opens Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Annotation paketi, annBarMount içinde Şerit DOM'unu oluşturur; düğmelerini veya iletişim kutusu işaretlemesini kopyalamanıza gerek yoktur. Önce docViewer'ı başlatın, ardından sunucu Açıklamanın lisanslı olduğunu onayladığında Şeridi oluşturun:

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

Şeritten kaydetme, verileri ara katman (AnnSave) aracılığıyla gönderir ve bu, belge oturumunda sayfa başına saklar. Yükleme (AnnLoad) ise açıklamaları içeren bir sayfa render edildiğinde otomatik olarak gerçekleşir. Dört onAnn* geri çağrısı, Şeridin Viewer yaşam döngüsüyle senkronize kalmasını sağlar.

Herhangi bir host'a ait Viewer araç çubuğundan açıp kapatabilirsiniz:

annBar.open();
annBar.close();

Genel Şerit API'si şudur:

onStatus, onToast, onLayout, onEditStart ve onEditEnd isteğe bağlı host geri çağrılarıdır. endpoints nesnesi ayrıca exportPdf, exportPng, imageUpload ve imageList sağlayabilir; yapılandırılmış bir uç noktası olmayan kontroller gizli kalır. Birleştirilmiş Viewer, Arama ve Açıklama başlangıç sırası için, Quick Start bölümüne bakın.

Annotation paketi tarayıcı düzenleme araçlarını ekler, ancak veriler hâlâ token ile tanımlanan sunucu tarafı belge oturumuna aittir. Kaynağı yeniden açmak yeni bir oturum oluşturur; açıklamaların oturum ömründen sonra da kalması gerekiyorsa XML'i veya kodlanmış açıklama zarfını uygulamanızda saklayın.

C#'ta Açıklamalar Oluşturma

Açık oturuma bağlı bir yönetici alın, açıklamaları ekleyin ve yükleyin (using Doconut.Annotations; tipler için ve using System.Drawing; Rectangle/Color için):

app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Bound to the open session's page dimensions
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // One stamp per page
    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));

    // Load into the session — the widget fetches them via AnnLoad and the
    // renderer burns them into image/PDF exports.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Açıklama Türleri

Tüm türler Doconut.Annotations içinde bulunur ve BaseAnnotation'dan (sayfa numarası + sınırlayıcı Rectangle) miras alır:

AnnotationManager API'si

Viewer, bir oturuma karşı yükleme/okuma işlemlerini yansıtır: LoadAnnotationData(token, manager) veya LoadAnnotationData(token, encodedData) (GetAnnotationData()'dan gelen Base64 kablo zarfı), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Açıklamaların Yanmış Olduğu Dışa Aktarım

// PDF of all pages with annotations rendered onto them
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");
});

// Or a ZIP of per-page PNGs
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");
});

Dışa aktarımlar, ekrandaki render gibi aynı yanma mekanizmasını kullanır, bu yüzden kullanıcıların gördüğü dosyanın içeriğidir.

Kalıcılık İş Akışı

1. Belgeyi açın ve token'ını alın.
2. Daha önce saklanmış XML'i veya kodlanmış veriyi o token'a yükleyin.
3. Widget'ın oturum açıklamalarını okumasına ve düzenlemesine izin verin.
4. Uygulamanız kalıcı hale getirmeye karar verdiğinde GetAnnotationXML(token) ile XML'i alın.
5. Düzleştirilmiş bir teslimat gerektiğinde PDF/PNG dışa aktarın.
6. Belge oturumunu kapatın.

Opak viewer token'ını kalıcı bir açıklama tanımlayıcısı olarak kullanmayın. Saklanan açıklama verilerini kendi belge ve sürüm tanımlayıcılarınızla ilişkilendirin.

Güvenlik ve Render Notları

• Açıklama istekleri, sayfa istekleriyle aynı oturum/token güvenliğini kullanır.
• Göreli bir ImageAnnotation URL'si istek host'undan çözülür ve yanma sırasında sunucu tarafından erişilebilir olmalıdır.
• Kullanıcı tarafından sağlanan herhangi bir görüntü URL'sini doğrulayın ve kontrol edin, sunucu tarafı istek sahteciliğini önlemek için.
• Dışa aktarımlar, ekrandaki sayfa render'ı gibi aynı lisans/özel filigran kararını uygular.
• Büyük serbest el yükleri ve yüksek çözünürlüklü dışa aktarımlar bellek kullanımını artırır; gerçekçi belgeler ve yakınlaştırma değerleriyle test edin.

Sorun Giderme