Açıklamalar

Görüntüleyiciye açıklama desteği ekleyin

Doconut'taki 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öntem 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 sınırlıdır (aktif Geçici lisans altında otomatik olarak verilir).

Açıklama Kullanıcı Arayüzünü 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 — bunlar lisansla sınırlıdır, bu yüzden etiketler yalnızca yetenek mevcut olduğunda görünür:

html
@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  // gömülü annotation şeridi
}))

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

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer kontrolleri, Annotation'ı açan düğmeyi içeren -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Açıklama paketi, Ribbon DOM'unu annBarMount içinde 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 doğruladığında oluşturun:

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

Yetenek olmadan, ReferenceScripts Ribbon betiğini dışarı bırakır, bu yüzden sunucu tarafı if, sayfayı bozmaktan koruyan bir doconutAnnotationBar(...) çağrısını korur.

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

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

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

Genel Ribbon API'si şudur:

MethodPurpose
attach(objViewer)Ribbon'ı başlatılmış viewer'a bağlar; bir kez gereklidir
open() / close()Açıklama düzenlemeye girer veya çıkar
reset()Ribbon'ı kapalı, düzenleme dışı duruma geri döndürür
isOpen() / annotating()Ribbon durumunu / viewer'ın açıklama düzenleme durumunu okur
reopenEditable()Mevcut sayfa açıklamalarını düzenlenebilir nesneler olarak yeniden yükler
updateActionState()Host değişikliklerinden sonra kaydet/mevcut kontrol kullanılabilirliğini yeniler
headerSlot()Host'a ait kontroller için isteğe bağlı başlık uzantı yuvasını alır

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ç noktası olmayan kontroller gizli kalır. Birleştirilmiş Viewer, Search ve Annotation başlangıç sırası için, Hızlı Başlangıç bölümüne bakın.

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 saklayın.

İki tür geri çağırma, iki şekilde bağlanmış

Ek açıklama kodu iki geri çağırma stili kullanır ve her biri diğer şekilde bağlandığında sessizce başarısız olur:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed seçenekler docViewer({...})'nin, tıpkı her izleyici geri çağırması gibi.
  • Created, Changed, Deleted, ve Properties isimle bulunan küresel fonksiyonlar: olayın önüne izleyici kimliği eklenir. #div_ctlDoc içindeki izleyici için kimlik ctlDoc'dir, bu yüzden fonksiyonlar ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted ve ctlDoc_Properties'dir. Yanlış yazılmış ya da yeniden adlandırılmış bir fonksiyon basitçe hiç çağrılmaz.

SaveAnnotations() kaydedilip kaydedilmediğini döndürmez: sonuç onAnnSaved ya da onAnnSaveError aracılığıyla gelir. Dönüş değerini okuyan kod, "kaydedilmemiş değişiklikler" bayrağını asla temizlemez.

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

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

csharp
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ı görüntü/PDF dışa aktarımlarına gömer.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Ek açıklama türleri

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

TürNotlar
StampAnnotationYazı damgası, yazı tipi boyutu, kenarlık, renk; Opacity, Rotate destekler
NoteAnnotationYapışkan not, metin, arka plan rengi, yazı tipi boyutu, TitleColor
RectangleAnnotationKenarlık + doldurma renkleri, Title/ShowTitle
CircleAnnotationKenarlık + doldurma, ShowBorder
EllipseAnnotationKenarlık + doldurma, ShowBorder
TriangleAnnotationKenarlık rengi, BackColor, ShowBorder
LineAnnotationGenişlik ve renkli düz çizgi
ArrowAnnotationOk başlığı olan çizgi; ayarlanabilir Direction (type ArrowDirection, pusula noktaları, varsayılan E)
FreehandAnnotationKodlanmış FreehandData noktalarından serbest çizgi
ImageAnnotationBir URL'den görüntü. Göreceli bir URL, ek açıklama eklendiğinde istek sunucusuna göre çözülür; sunucu görüntüyü yalnızca yakma zamanında alır — aşağıdaki dışa aktarma notuna bakın

AnnotationManager API'si

ÜyeAmaç
Add(BaseAnnotation)Bir ek açıklamayı kuyruğa al
GetAnnotations() / GetAnnotations(int page)Yöneticinin ne tuttuğunu incele
ClearAnnotations() / ClearAnnotations(int page)Hepsini kaldır / sayfa başına
GetAnnotationData() / GetAnnotationData(int page)Kodlanmış ek açıklama veri dizesi — bir Base64 veri zarfı (widget'ın tükettiği)
GetAnnotationXml()XML formu

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

Ek açıklamaların yakıldığı dışa aktarma

csharp
// Ek açıklamalar renderlanmış 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 renderlama ile aynı yakıcıyı kullanır, bu yüzden kullanıcıların gördükleri dosyanın içinde olanla aynıdır — görüntü ek açıklamaları hariç, aşağıda açıklanmıştır.

İntranet sunucusunda görüntü ek açıklamaları "Görüntü engellendi" olarak dışa aktarılıyor

Görüntüleyici ve dışa aktarma, bir ImageAnnotation'ın resmini farklı yerlerden alır:

YüzeyResmi kim indiriyorİntranet veya geliştirme sunucusunda
Tarayıcıdaki görüntüleyiciKullanıcının tarayıcısıResim görünür
ExportAnnotationsToPdfAsync / …PngZipAsyncSunucuKırmızı "Image blocked" yer tutucu

Sunucu bir resmi alıp içine yerleştirmeye çalıştığında, özel ağlara geri dönen adresleri reddeder: loopback (localhost, 127.0.0.1), 0.0.0.0, link-local (169.254.x.x), özel aralıklar 10.x, 172.16–31.x ve 192.168.x, carrier‑grade NAT (100.64.0.0/10) ve IPv6 link‑local ve unique‑local adresleri. Bu, sunucunun oluşturulmuş bir resim URL'si üzerinden iç sistemlere ulaşmak için kullanılmasını önler ve bunu kapatacak bir ayar yoktur.

Bir göreli resim URL'si, mevcut isteğin ana bilgisayarına göre çözülür, bu yüzden localhost üzerinde, bir intranet sunucusunda veya özel bir adres üzerinden erişilen herhangi bir sitede, resim görüntüleyicide gösterilir ve dışa aktarma bunun yerine yer tutucuyu içerir. Bu, bir korumanın çalışmasıdır, render hatası değildir. Dışa aktarmaların resmi içermesi gerekiyorsa, resmi kamuya açık bir adrese sahip bir sunucudan sunun ve mutlak bir URL kullanın. Çözülemeyen bir ana bilgisayar adı aynı şekilde reddedilir; diğer indirme hataları URL'yi ve hatayı kırmızı renkte, resmin olması gereken yerde gösterir.

Kalıcılık iş akışı

  1. Belgeyi açın ve token'ını alın.
  2. Daha önce depolanmış XML veya kodlanmış veriyi o token'a yükleyin.
  3. Widget'ın oturum ek 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 görüntüleyici token'ını kalıcı bir ek açıklama tanımlayıcısı olarak kullanmayın. Kalıcı ek açıklama verilerini kendi belge ve sürüm tanımlayıcılarınızla ilişkilendirin.

Güvenlik ve render notları

  • Ek açıklama istekleri, sayfa istekleriyle aynı oturum/token güvenliğini kullanır.
  • Kullanıcı tarafından sağlanan herhangi bir resim URL'sini doğrulayın ve kontrol edin, sunucu tarafı istek sahteciliğini önlemek için.
  • 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

SemptomKontrol
Ek açıklama şeridi eksikAnnotation yeteneği ve dört ek açıklama CSS/skript bayrağı
Kaydetme geri çağrısı bir hata rapor ediyorToken/oturum süresi dolması ve ara katman BasePath
ctlDoc_Created (veya başka bir olay işlevi) hiç çalışmazFonksiyon adı: görüntüleyici kimliği + _ + olay, global bir işlev olarak
C# ek açıklamaları görünmüyorSayfa numaralandırması bir temelli ve veri aktif token'a yüklendi
Resim ek açıklaması ekranda görünüyor ancak dışa aktarmada yokResmin ana bilgisayarı özel veya loopback bir adrese sahip — yukarıya bakın
Yeniden açılan belgede ek açıklama yokXML/veriyi görüntüleyici oturumu dışına kalıcı olarak kaydedin, ardından yeni token'a yükleyin

Bu sayfa yardımcı oldu mu?