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):
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:
<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.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öntem | Amaç |
|---|---|
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,onAnnCloseddocViewer({...})'nin seçenekleridir, tıpkı her görüntüleyici geri çağırması gibi.Created,Changed,DeletedvePropertiesisimle bulunan küresel fonksiyonlardır: olayın önüne görüntüleyici kimliği eklenir.#div_ctlDociçindeki görüntüleyici için kimlikctlDoc'dir, bu yüzden fonksiyonlarctlDoc_Created,ctlDoc_Changed,ctlDoc_DeletedvectlDoc_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):
// 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ür | Notlar |
|---|---|
StampAnnotation | Yazı tipi boyutu, kenarlık, renk içeren metin damgası; Opacity, Rotate destekler |
NoteAnnotation | Metin, arka plan rengi, yazı tipi boyutu ve TitleColor içeren yapışkan not |
RectangleAnnotation | Kenarlık ve dolgu renkleri, Title/ShowTitle |
CircleAnnotation | Kenarlık ve dolgu, ShowBorder |
EllipseAnnotation | Kenarlık ve dolgu, ShowBorder |
TriangleAnnotation | Kenarlık rengi, BackColor, ShowBorder |
LineAnnotation | Genişlik ve renk içeren düz çizgi |
ArrowAnnotation | Ok ucu olan çizgi; ayarlanabilir Direction (ArrowDirection, pusula noktaları, varsayılan E) |
FreehandAnnotation | Kodlanmış FreehandData noktalarından serbest çizgi |
ImageAnnotation | Bir 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
| Üye | Amaç |
|---|---|
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
// 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üzey | Resmi kim indiriyor | İntranet veya geliştirme sunucusunda |
|---|---|---|
| Tarayıcıdaki görüntüleyici | Kullanıcının tarayıcısı | Resim görünür |
ExportAnnotationsToPdfAsync / …PngZipAsync | Sunucu | Kı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ışı
- Belgeyi açın ve token'ını alın.
- Daha önce depolanmış XML'i veya kodlanmış veriyi o token'a yükleyin.
- Widget'ın oturum ek açıklamalarını okumasına ve düzenlemesine izin verin.
- Uygulamanız kalıcı hale getirmeye karar verdiğinde
GetAnnotationXML(token)ile XML'i alın. - Düzleştirilmiş bir teslimat gerektiğinde PDF veya PNG dışa aktarın.
- 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
| Semptom | Kontrol |
|---|---|
| Ek Açıklama Şeridi eksik | Annotation yeteneği ve dört ek açıklama CSS/skript bayrağı |
| Kaydetme bir hata rapor ediyor | Token veya oturum süresi dolmuş, ve widget'ın BasePath |
ctlDoc_Created (veya başka bir olay işlevi) hiç çalışmaz | Fonksiyon adı: görüntüleyici kimliği + _ + olay, global bir işlev olarak |
| C# ek açıklamaları görünmüyor | Sayfa 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österilmez | Resmin ana bilgisayarı özel veya döngüsel bir adrese sahip — yukarıya bakın |
| Yeniden açılan bir belgede ek açıklama yok | XML'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?