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ı oluşturur ve açık bir oturuma yükler. Hangi yöntemle olursa olsun, sayfalarda görüntülenir ve PDF veya PNG dışa aktarımlarına yerleştirilebilir.

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. Sayfa Viewer kaynaklarını, Viewer araç çubuğunu, Viewer bağlamasını ve başlatılmış bir objViewer içermelidir; ardından Açıklama Şeridi aynı örneğe monte edilir ve eklenir.

Açıklama dosyalarını viewer dosyalarıyla birlikte yayınlayın. Bunlar lisans kısıtlamalıdır, bu yüzden etiketleri yalnızca yetenek verildiğinde görünür. MVC 5'te, etiketleri denetleyicide oluşturun (görünümlerde @inject yoktur):

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   // gömülü açıklama şeridi
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

Tam Viewer bileşimini işaretlemede (markup) tutun:

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

Açıklama dosyaları, annBarMount içinde Şeridi (Ribbon) oluşturur; düğmelerini veya iletişim kutularını kopyalamazsınız. Önce docViewer'yi başlatın, ardından Şeridi yalnızca sunucu Açıklamanın lisanslı olduğunu onayladığında oluşturun:

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>

Yetenek olmadan, ReferenceScripts Şeridin betiğini dışarı bırakır, böylece sunucu tarafı if, sayfayı bozabilecek korumasız bir doconutAnnotationBar(...) çağrısını önler. Web Forms'ta, aynı korumayı <% if (IsAnnotationEnabled) { %> … <% } %> olarak yazın.

Şeritten kaydetme, verileri DocImage.axd (AnnSave) adresine gönderir, bu da sayfa başına belge oturumunda saklar. Yükleme (AnnLoad) ise açıklamaları içeren bir sayfa render edildiğinde otomatik olarak gerçekleşir.

Kendi araç çubuğunuzdan annBar.open() ve annBar.close() ile Şeridi açıp kapatın. Genel API'si:

YöntemAmaç
attach(objViewer)Şeridi başlatılmış görüntüleyiciye bağlar; bir kez gereklidir
open() / close()Açıklama düzenlemeye girer veya çıkar
reset()Şeridi kapalı, düzenleme olmayan duruma geri döndürür
isOpen() / annotating()Şerit durumunu / görüntüleyicinin açıklama-düzenleme durumunu okur
reopenEditable()Mevcut sayfanın açıklamalarını düzenlenebilir nesneler olarak yeniden yükler
updateActionState()Ana bilgisayar değişikliklerinden sonra kaydet ve sil kontrollerini yeniler
headerSlot()Ana bilgisayarın kontrol öğeleri için isteğe bağlı başlık yuvası

onStatus, onToast, onLayout, onEditStart ve onEditEnd isteğe bağlı ana bilgisayar 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.

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

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

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

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

C#'ta açıklamaları oluşturun

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

csharp
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<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 - görüntüleyici onları alır ve işleyici onları içine yakar
    // image/PDF dışa aktarımları.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

Açıklama türleri

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

TürNotlar
StampAnnotationYazı tipi boyutu, kenarlık, renk içeren metin damgası; Opacity, Rotate destekler
NoteAnnotationMetin, arka plan rengi, yazı tipi boyutu ve TitleColor içeren yapışkan not
RectangleAnnotationKenarlık ve dolgu renkleri, Title/ShowTitle
CircleAnnotationKenarlık ve dolgu, ShowBorder
EllipseAnnotationKenarlık ve dolgu, ShowBorder
TriangleAnnotationKenarlık rengi, BackColor, ShowBorder
LineAnnotationGenişlik ve renk içeren düz çizgi
ArrowAnnotationOk ucu olan çizgi; ayarlanabilir Direction (ArrowDirection, pusula noktaları, varsayılan E)
FreehandAnnotationKodlanmış FreehandData noktalarından serbest çizgi
ImageAnnotationBir URL'den görüntü. Göreceli bir URL, açıklama eklendiğinde mevcut isteğin sunucusuna göre çözülür — aşağıdaki dışa aktarma notuna bakın

AnnotationManager API'si

ÜyeAmaç
Add(BaseAnnotation)Bir 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ış açıklama verileri — widget'ın tükettiği zarf
GetAnnotationXml()XML formu

Viewer bir oturuma karşı yükleme ve okuma işlemlerini yansıtır: LoadAnnotationData(token, manager) veya LoadAnnotationData(token, encodedData), LoadAnnotationXML(token, xml) ve GetAnnotationXML(token).

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

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

// Veya sayfa başına PNG'lerin bir ZIP'i
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");
}

Dışa aktarmalar, ekrandaki renderlama ile aynı yakıcıyı, aynı lisansı ve özel filigran kararını kullanır.

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

Görüntüleyici ve dışa aktarım, bir ImageAnnotation'nin 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 yerleştirmek için alırken, özel ağlara geri dönen adresleri reddeder: döngüsel (localhost, 127.0.0.1), 0.0.0.0, bağlantı yerel (169.254.x.x), özel aralıklar 10.x, 172.16–31.x ve 192.168.x, taşıyıcı sınıfı NAT (100.64.0.0/10) ve IPv6 bağlantı yerel ve benzersiz yerel adresleri. Bu, sunucunun hazırlanmış bir resim URL'si üzerinden iç sistemlere ulaşmak için kullanılmasını önler ve bunu kapatacak bir anahtar yoktur.

Göreceli bir resim URL'si, geçerli isteğin ana bilgisayarına göre çözülür, bu yüzden localhost üzerinde, bir intranet sunucusunda veya özel bir adrese ulaşan herhangi bir site üzerinde, resim görüntüleyicide gösterilir ve dışa aktarım yerine yer tutucuyu içerir. Bu, korumanın çalıştığı anlamına gelir, bir render hatası değildir. Dışa aktarımların resmi içermesi gerekiyorsa, resmi kamuya açık bir adrese sahip bir sunucudan sunun ve mutlak bir URL kullanın. Çözülmesi mümkün olmayan 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'i 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 veya PNG dışa aktarın.
  6. Belge oturumunu kapatın.

Görüntüleyici token'ını kalıcı bir ek açıklama tanımlayıcısı olarak kullanmayın — oturumla birlikte sona erer ve uygulama havuzunun yeniden başlatılması tek bir sunucudaki tüm oturumları sonlandırır. Ek açıklama verilerini kendi belge ve sürüm tanımlayıcılarınızla saklayın.

Güvenlik ve render notları

  • Ek açıklama istekleri, sayfa istekleriyle aynı oturum ve token güvenliğini kullanır.
  • Kullanıcı tarafından sağlanan tüm resim URL'lerini doğrulayın ve kontrol edin.
  • 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 belgeleri ve yakınlaştırma değerlerini test edin.

Sorun Giderme

SemptomKontrol
Ek Açıklama Şeridi eksikAnnotation yeteneği ve dört ek açıklama CSS/skript bayrağı
Kaydetme bir hata rapor ediyorToken veya oturum süresi dolmuş, ve widget'ın 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 numaraları birden başlar ve veri aktif token'a yüklendi
Bir resim ek açıklaması ekranda gösterilir ancak dışa aktarımda gösterilmezResmin ana bilgisayarı özel veya döngüsel bir adrese sahip — yukarıya bakın
Yeniden açılan bir belgede ek açıklama yokXML'i veya veriyi görüntüleyici oturumunun dışına kalıcı hale getirin, ardından yeni token'a yükleyin

Bu sayfa yardımcı oldu mu?