Açıklamalar

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

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

Açıklama UI'sini Etkinleştir

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.

Açıklama paketlerini Viewer paketleriyle birlikte yayınlayın — lisans kısıtlamalıdırlar, 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">
    <!-- Görüntüleyici kontrolleri, Açıklamayı açan düğme dahil -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

annBarMount içinde Ribbon DOM'unu Annotation paketi oluşturur; düğmelerini veya iletişim kutusu işaretlemesini kopyalamanıza gerek yoktur. Önce docViewer'ı başlatın, ardından Ribbon'ı yalnızca sunucu Açıklamanın lisanslı olduğunu onayladığında 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>

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

Herhangi bir host tarafından sahip olunan Viewer araç çubuğundan açıp kapatın:

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

Public Ribbon API'si şudur:

onStatus, onToast, onLayout, onEditStart ve onEditEnd isteğe bağlı host geri çağırmalarıdır. endpoints nesnesi ayrıca exportPdf, exportPng, imageUpload ve imageList sağlayabilir; yapılandırılmış bir uç nokta olmayan kontroller gizli kalır. Birleştirilmiş Viewer, Arama ve Açıklama başlangıç sırası için, bkz. Hızlı Başlangıç.

Açıklama paketi tarayıcı oluşturma 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 kalıcı tutun.

C#'da açıklamaları oluşturma

Açık oturuma bağlı bir yöneticiyi alın, açıklamaları ekleyin ve onları 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) =>
{
    // Açık oturumun sayfa boyutlarına bağlı
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Sayfa başına bir damga
    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));

    // Oturuma yükle — widget bunları AnnLoad aracılığıyla alır ve
    // renderer bunları image/PDF dışa aktarımlarına yakar.
    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) kalıtım 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 veri zarfı), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Açıklamaları yanmış şekilde dışa aktar

// Ek açıklamaları üzerine renderlanan tüm sayfaların PDF'si
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");
});

// Veya sayfa başına PNG'lerin bir ZIP'i
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 aktarmalar, ekrandaki render ile aynı yanma işlemcisini kullanır, böylece kullanıcıların gördüğü dosyanın içeriğiyle aynıdır.

Kalıcılaştırma iş akışı

1. Belgeyi açın ve token'ını alın.
2. Daha önce depolanmış 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ılaştırmaya 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 görüntüleyici token'ını kalıcı bir açıklama tanımlayıcısı olarak kullanmayın. Kalıcılaştırılmış açıklama verilerini kendi belge ve sürüm tanımlayıcılarınızla ilişkilendirin.

Güvenlik ve render notları

• Anotasyon istekleri, sayfa istekleriyle aynı oturum/token güvenliğini kullanır.
• Göreceli ImageAnnotation URL'si istek ana bilgisayarından çözülür ve yanma zamanında sunucu tarafından erişilebilir olmalıdır.
• Sunucu tarafı istek sahteciliğini önlemek için kullanıcı tarafından sağlanan tüm görüntü URL'lerini doğrulayın ve kontrol edin.
• Dışa aktarmalar, 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 aktarmalar bellek kullanımını artırır; gerçekçi belgeler ve yakınlaştırma değerleriyle test edin.

Sorun Giderme