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.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:
<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:
<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:
annBar.open();
annBar.close();Genel Ribbon API'si şudur:
| Method | Purpose |
|---|---|
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,onAnnClosedseçeneklerdocViewer({...})'nin, tıpkı her izleyici geri çağırması gibi.Created,Changed,Deleted, vePropertiesisimle bulunan küresel fonksiyonlar: olayın önüne izleyici kimliği eklenir.#div_ctlDociçindeki izleyici için kimlikctlDoc'dir, bu yüzden fonksiyonlarctlDoc_Created,ctlDoc_Changed,ctlDoc_DeletedvectlDoc_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):
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ür | Notlar |
|---|---|
StampAnnotation | Yazı damgası, yazı tipi boyutu, kenarlık, renk; Opacity, Rotate destekler |
NoteAnnotation | Yapışkan not, metin, arka plan rengi, yazı tipi boyutu, TitleColor |
RectangleAnnotation | Kenarlık + doldurma renkleri, Title/ShowTitle |
CircleAnnotation | Kenarlık + doldurma, ShowBorder |
EllipseAnnotation | Kenarlık + doldurma, ShowBorder |
TriangleAnnotation | Kenarlık rengi, BackColor, ShowBorder |
LineAnnotation | Genişlik ve renkli düz çizgi |
ArrowAnnotation | Ok başlığı olan çizgi; ayarlanabilir Direction (type ArrowDirection, pusula noktaları, varsayılan E) |
FreehandAnnotation | Kodlanmış FreehandData noktalarından serbest çizgi |
ImageAnnotation | Bir 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
| Üye | Amaç |
|---|---|
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
// 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ü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 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ışı
- Belgeyi açın ve token'ını alın.
- Daha önce depolanmış XML 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/PNG dışa aktarın.
- 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
| Semptom | Kontrol |
|---|---|
| Ek açıklama şeridi eksik | Annotation yeteneği ve dört ek açıklama CSS/skript bayrağı |
| Kaydetme geri çağrısı bir hata rapor ediyor | Token/oturum süresi dolması ve ara katman 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 numaralandırması bir temelli ve veri aktif token'a yüklendi |
| Resim ek açıklaması ekranda görünüyor ancak dışa aktarmada yok | Resmin ana bilgisayarı özel veya loopback bir adrese sahip — yukarıya bakın |
| Yeniden açılan belgede ek açıklama yok | XML/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?