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öntemle 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 UI'sini Etkinleştir
Açıklama, bağımsız bir araç çubuğu değil, bir Görüntüleyici modülüdür. Tam sayfa, Görüntüleyici kaynaklarını, Görüntüleyici araç çubuğunu, Görüntüleyici montajını ve başlatılmış objViewer'ı içermelidir; ardından Açıklama Şeridi aynı örneğe monte edilir ve eklenir.
Görüntüleyici paketleriyle birlikte açıklama paketlerini yayınlayın — bunlar lisans sınırlamalı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ü açıklama şeridi
}))Tam Görüntüleyici bileşimini işaretlemede görünür tutun:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Görüntüleyici kontrolleri, Annotation'ı açan düğme dahil -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Açıklama paketi, Şerit 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 sunucu Açıklamanın lisanslı olduğunu onayladığında sadece Şeridi oluşturun:
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
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 Şeridin betiğini dışarı bırakır, bu yüzden sunucu tarafı if, sayfayı kırebilecek korumasız bir doconutAnnotationBar(...) çağrısını önler.
Şeritten 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, Şeridi Görüntüleyici yaşam döngüsüyle senkronize tutar.
Herhangi bir host-a ait Görüntüleyici araç çubuğundan açıp kapatabilirsiniz:
annBar.open();
annBar.close();Genel Şerit API'si şudur:
| Yöntem | Amaç |
|---|---|
attach(objViewer) | Şeridi başlatılmış Görüntüleyici'ye bağlayın; bir kez gereklidir |
open() / close() | Açıklama düzenlemeye girin veya çıkın |
reset() | Şeridi kapalı, düzenleme dışı duruma geri döndürün |
isOpen() / annotating() | Şerit durumunu / Görüntüleyici'nin açıklama-düzenleme durumunu okuyun |
reopenEditable() | Mevcut sayfa açıklamalarını düzenlenebilir nesneler olarak yeniden yükleyin |
updateActionState() | Host değişikliklerinden sonra kaydet/sil kontrolünün kullanılabilirliğini yenileyin |
headerSlot() | Host-a ait kontroller için isteğe bağlı başlık uzantı yuvasını alın |
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ş Görüntüleyici, 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 süresinden 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ış
İşaretleme 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,onAnnClosedseçeneklerdocViewer({...})'nin, tıpkı her görüntüleyici geri çağırması gibi.Created,Changed,Deleted, vePropertiesisimle bulunan global fonksiyonlar: 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ış ya da yeniden adlandırılmış bir fonksiyon basitçe hiç çağrılmaz.
SaveAnnotations() kaydedip kaydetmediğ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#'ta işaretlemeler oluşturma
Açık oturuma bağlı bir yöneticiyi alın, işaretlemeler 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ımlara yakar.
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});İşaretleme türleri
Tüm türler Doconut.Annotations içinde bulunur ve BaseAnnotation'den (sayfa numarası + sınırlayıcı Rectangle) miras alır:
| Tür | Notlar |
|---|---|
StampAnnotation | Yazı damgası, yazı tipi boyutu, kenarlık, renk ile; Opacity, Rotate destekler |
NoteAnnotation | Metin, arka plan rengi, yazı tipi boyutu ve TitleColor içeren yapışkan not |
RectangleAnnotation | Kenarlık + dolgu renkleri, Title/ShowTitle |
CircleAnnotation | Kenarlık + dolgu, ShowBorder |
EllipseAnnotation | Kenarlık + dolgu, ShowBorder |
TriangleAnnotation | Kenarlık rengi, BackColor, ShowBorder |
LineAnnotation | Genişlik ve renkli düz çizgi |
ArrowAnnotation | Ok başlığı olan çizgi; ayarlanabilir Direction (ArrowDirection tipi, pusula noktaları, varsayılan E) |
FreehandAnnotation | Kodlanmış FreehandData noktalarından serbest çizim |
ImageAnnotation | Bir URL'den görüntü. Göreceli bir URL, işaretleme 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 işaretlemeyi 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ış işaretleme veri dizesi — bir Base64 ileti 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()'dan gelen Base64 ileti zarfı), LoadAnnotationXML(token, xml), GetAnnotationXML(token).
İşaretlemeler yanmış olarak 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 renderleme ile aynı yakıcıyı kullanır, bu yüzden kullanıcıların gördüğü dosyanın içeriğiyle aynıdır — görüntü işaretlemeleri hariç, aşağıda açıklanmıştı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'ın görüntüsünü farklı yerlerden alır:
| Yüzey | Görüntüyü kim indiriyor | İntranet veya geliştirme sunucusunda |
|---|---|---|
| Tarayıcıdaki görüntüleyici | Kullanıcının tarayıcısı | Görüntü görünür |
ExportAnnotationsToPdfAsync / …PngZipAsync | Sunucu | Kırmızı "Image blocked" yer tutucu |
Sunucu bir görüntüyü 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 adresler. Bu, sunucunun hazırlanmış bir görüntü URL'si üzerinden iç sistemlere ulaşmak için kullanılmasını önler ve bunu kapatacak bir ayar yoktur.
Göreli bir görüntü 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, görüntü 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 görselleştirme hatası değildir. Dışa aktarımların görüntüyü içermesi gerekiyorsa, onu genel bir adrese sahip bir sunucudan sunun ve mutlak bir URL kullanın. Çözülemeyen bir ana bilgisayar adı da aynı şekilde reddedilir; diğer indirme hataları ise URL'yi ve görüntünün olması gereken yerde kırmızı hata mesajını 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/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 görselleştirme notları
- Ek açıklama istekleri, sayfa istekleriyle aynı oturum/token güvenliğini kullanır.
- Kullanıcı tarafından sağlanan herhangi bir görüntü URL'sini doğrulayın ve kontrol edin, sunucu tarafı istek sahteciliğini önlemek için.
- Dışa aktarımlar, ekrandaki sayfa görselleştirmesi ile aynı lisans/özel filigran kararını uygular.
- 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 belgeler 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 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 | İşlev 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 |
| Görüntü ek açıklaması ekranda görünüyor ancak dışa aktarımda yok | Görüntünün ana bilgisayarı özel veya döngüsel bir adrese sahip — yukarıya bakın |
| Yeniden açılan belgede ek açıklama yok | XML/veriyi görüntüleyici oturumunun dışına kalıcı olarak kaydedin, ardından yeni token'a yükleyin |
Bu sayfa yardımcı oldu mu?