Document Compare elementi, bir dokümanın iki farklı versiyonunu karşılaştırmak ve aralarındaki farkları kullanıcıya açık ve görsel bir şekilde sunmak için kullanılan bir UI elementidir. Özellikle doküman inceleme, versiyon kontrolü ve değişiklik takibi gerektiren senaryolarda kullanılır.
Bu element sayesinde kullanıcılar; metin içeriklerindeki değişiklikleri satır/sözcük bazlı olarak görebilir, tablo yapılarında hücre bazlı farkları inceleyebilir ve PDF dokümanlar arasında görsel karşılaştırma yapabilir. Ayrıca Collabora entegrasyonu ile tracked-changes (değişiklik takibi) desteklenerek, yapılan ekleme, silme ve güncellemeler standart ofis araçlarına benzer şekilde işaretlenir.
Document Compare elementi, farklı veri formatlarına uyum sağlayarak tek bir arayüz üzerinden çok yönlü karşılaştırma imkanı sunar. Bu sayede kullanıcılar dokümanlar arasındaki farkları manuel incelemek yerine, sistem tarafından vurgulanan değişiklikler üzerinden hızlı ve doğru analiz yapabilir.
Document Compare elementi yalnızca web uygulamalarda desteklenmektedir.
1. 1. Sık Kullanım Senaryoları
DocumentCompare elementi aşağıdaki senaryolarda yaygın olarak kullanılır:
Aynı dokümanın farklı versiyonları arasındaki değişiklikleri incelemek için kullanılır. Örneğin bir sözleşmenin eski ve yeni versiyonları karşılaştırılarak eklenen, silinen veya güncellenen alanlar hızlıca tespit edilebilir.
Onay ve revizyon süreçlerinde, yapılan değişikliklerin kontrol edilmesi amacıyla tercih edilir. Özellikle içerik editörleri, hukuk ekipleri veya teknik dokümantasyon ekipleri için değişiklik doğrulama sürecini kolaylaştırır.
Metin tabanlı içeriklerde (ör. Word, düz metin) satır veya kelime bazlı farkların analiz edilmesi gereken durumlarda kullanılır.
Tablo içeren dokümanlarda, hücre bazlı değişikliklerin tespit edilmesi gereken senaryolarda kullanılır. Örneğin finansal tablolar veya rapor karşılaştırmaları.
PDF dokümanlar arasında görsel farkların incelenmesi gereken durumlarda tercih edilir. Sayfa bazlı veya overlay (üst üste bindirme) karşılaştırma ile değişiklikler görsel olarak analiz edilebilir.
Collabora tracked-changes desteği ile, kullanıcıların yaptığı değişikliklerin (ekleme, silme, düzenleme) ofis uygulamalarına benzer şekilde izlenmesi gereken senaryolarda kullanılır.
Denetim (audit) ve uyumluluk süreçlerinde, dokümanlar üzerinde zaman içinde yapılan değişikliklerin kayıt altına alınması ve karşılaştırılması için kullanılabilir.
Kullanıcının iki doküman arasında farkları inceleyerek karar vermesi gereken durumlarda kullanılır. Örneğin “hangi versiyonun geçerli olduğu”, “hangi değişikliklerin kabul edileceği” gibi karar süreçlerini destekler.
2. Temel Özellikler
Document Compare elementi, doküman karşılaştırma sürecini kullanıcıya anlaşılır ve görsel olarak takip edilebilir şekilde sunmak için aşağıdaki temel özellikleri sağlar:
Farklı karşılaştırma modlarını destekler. Collabora modu ile tracked-changes görünümü sunulurken; textDiff, cellDiff, slideDiff ve pageDiff modlarında klasik diff (yan yana karşılaştırma) yapısı kullanılır.
Collabora entegrasyonu ile Word benzeri değişiklik takibi yapılabilir. Bu modda doküman, iframe içerisinde açılır ve:
Eklenen metinler yeşil renkte,
Silinen metinler kırmızı ve üstü çizili olarak gösterilir.
Diff modlarında (textDiff, cellDiff, slideDiff, pageDiff) yan yana iki panel görünümü sunar:
Sol panel: Eski versiyon
Sağ panel: Yeni versiyon
Satır bazlı renk kodlama desteği sağlar:
Yeşil arka plan: Eklenen içerik
Kırmızı arka plan: Silinen içerik
Sarı arka plan: Güncellenen/değiştirilen içerik
Gri arka plan: Ayırıcı veya değişiklik olmayan satırlar
Üst bilgi alanında özet değişiklik bilgisi gösterilir. Örneğin:
Senkronize kaydırma (scroll sync) desteği sunar. Kullanıcı bir panelde aşağı/yukarı kaydırma yaptığında diğer panel otomatik olarak aynı konuma gelir. Bu sayede karşılaştırma daha kolay yapılır.
Aynı versiyon kontrolü yapar. Eğer karşılaştırılan iki doküman versiyonu aynı ise kullanıcıya bilgilendirme mesajı gösterilir:
“İki versiyon ID’si aynı — değişiklik yok.”
Desteklenmeyen formatlar için uyarı mekanizması içerir. Karşılaştırma yapılamayan dosya türlerinde kullanıcıya uygun bir uyarı mesajı gösterilir.
Hata durumlarını yönetir. Karşılaştırma sırasında oluşan sistem hataları kullanıcıya kırmızı hata mesajı olarak iletilir.
Yükleme (loading) durumunu görsel olarak belirtir. Karşılaştırma verisi hazırlanırken ekranın ortasında bir spinner gösterilerek kullanıcı bilgilendirilir.
Tema desteği sunar. Element, uygulamanın genel temasına uyum sağlayacak şekilde light veya dark modda kullanılabilir.
2.1. Element Ayarları (Properties)
Document Compare elementini seçtiğinizde, sağ tarafta yer alan Properties paneli üzerinden karşılaştırılacak doküman versiyonlarını, karşılaştırma motorlarını ve görsel davranışları kontrol edebilirsiniz.
Bu elementte kullanılabilen temel özellikler aşağıdaki gibidir:
leftVersionId: Sol panelde gösterilecek eski versiyonun kimliğini (KDocumentVersion.Id - GUID) ifade eder. Bu alan zorunludur ve karşılaştırmanın başlangıç verisini belirler.
Genellikle GetVersions aksiyonundan elde edilir.
isValueProp=true olduğu için SetValueOf ile dinamik olarak güncellenebilir.
Değer değiştiğinde karşılaştırma süreci tetiklenir.
rightVersionId: Sağ panelde gösterilecek yeni versiyonun kimliğini (KDocumentVersion.Id - GUID) ifade eder. Bu alan zorunludur ve karşılaştırmanın hedef verisini belirler.
GetVersions aksiyonundan elde edilir.
isValueProp=true olduğu için SetValueOf ile atanabilir.
leftVersionId ve rightVersionId alanları kısa süre içinde ard arda güncellenirse, sistem 50ms debounce uygular ve karşılaştırma işlemini tek seferde başlatır. Bu sayede gereksiz tekrar istekleri engellenir.
Locale: Elementin arayüz dilini belirler.
Desteklenen değerler:
tr
en
Bu property; üstte gösterilen özet mesajları, bilgi metinleri ve etiketlerin dilini belirler.
textEngine: TXT, CSV, JSON, XML, HTML gibi metin tabanlı dosyalar için karşılaştırma motorunu belirler.
Desteklenen değerler:
auto
Diffplex
2.2. Elemente Eklenebilen Event Aksiyonları
Document Compare elementi, karşılaştırma süreci boyunca oluşan olaylara bağlı olarak aksiyon çalıştırabilen bir yapıya sahiptir. Element seçildiğinde ADD ACTION butonu üzerinden aşağıdaki event’lere aksiyon eklenebilir:
OnLoad: Karşılaştırma işlemi başarıyla tamamlandığında tetiklenir.
Bu event, karşılaştırma sonucu hazır olduğunda yapılması gereken işlemler için kullanılır. Örneğin:
Karşılaştırma özet bilgisini başka bir alanda göstermek
Değişiklik sayısına göre koşullu işlem yapmak
Loglama veya analiz işlemleri başlatmak
Event ile birlikte dönen ComparisonResult verisi kullanılarak detaylı işlem yapılabilir.
OnError: Karşılaştırma sırasında bir hata oluştuğunda tetiklenir.
Bu event, hata yönetimi ve kullanıcıya geri bildirim sağlamak için kullanılır. Örneğin:
Hata mesajını kullanıcıya göstermek
Alternatif bir içerik veya fallback ekranı açmak
Hata loglama işlemi yapmak
2.3. Karşılaştırma Modları
Document Compare elementi, backend tarafından döndürülen karşılaştırma sonucuna göre farklı modlarda çalışır. Kullanılan mod; dosyanın MIME tipi ve seçilen karşılaştırma motoruna bağlı olarak otomatik belirlenir.
Desteklenen karşılaştırma modları aşağıdaki gibidir:
textDiff: Satır bazlı metin karşılaştırması yapılır (DiffPlex). Genellikle metin tabanlı dosyalar için kullanılır.
Kullanıldığı formatlar:
TXT, CSV, JSON, XML, HTML, MD
Kod dosyaları
cellDiff: Hücre bazlı tablo karşılaştırması yapılır. Excel ve benzeri tablo yapıları için uygundur.
Kullanıldığı formatlar:
XLSX, XLS, ODS
slideDiff: Slayt bazlı metin karşılaştırması yapılır. Sunum dosyalarında içerik değişikliklerini analiz etmek için kullanılır.
Kullanıldığı formatlar:
PPTX, PPT, ODP
pageDiff: Sayfa bazlı metin karşılaştırması yapılır. PDF içeriklerinin sayfa düzeyinde analiz edilmesini sağlar.
Kullanıldığı formatlar:
PDF (pdfpage engine)
pdfVisualDiff: PDF dokümanları için piksel bazlı görsel karşılaştırma yapılır. Metin yerine görsel farkların tespit edilmesi gereken durumlarda kullanılır.
Kullanıldığı formatlar:
PDF (pdfvisual engine)
Collabora: Collabora entegrasyonu ile tracked-changes (değişiklik takibi) görünümü sunar. Word benzeri değişiklik izleme deneyimi sağlar.
Kullanıldığı formatlar:
DOCX, DOC, ODT, RTF (Collabora aktifse)
Identical: Karşılaştırılan iki versiyon tamamen aynıdır. Genellikle aynı versionId gönderildiğinde bu mod döner.
Error: Karşılaştırma sırasında bir hata oluşmuştur.
Kullanıldığı durum:
Backend hatası
Geçersiz veri
Engine başarısızlığı
Unsupported: Dosya formatı karşılaştırma için desteklenmiyordur.
Kullanıldığı formatlar:
Görsel dosyalar (örn. PNG, JPG)
3D dosyalar
Arşiv dosyaları (ZIP vb.)
2.4. Otomatik Motor Seçimi
Engine property’leri "auto" olarak ayarlandığında, sistem karşılaştırma motorunu otomatik olarak seçer. Bu seçim MIME tipine göre yapılır.
Çalışma mantığı aşağıdaki gibidir:
Dosyanın MIME tipine göre format ailesi belirlenir (docx, xlsx, pdf, pptx, text).
İlgili engine property kontrol edilir (örneğin DOCX için docxEngine).
Eğer değer "auto" ise aşağıdaki varsayılanlar kullanılır:
DOCX / DOC / ODT: wmlcomparer (gerçek Word Track Changes — varsayılan ve önerilen)
XLSX / XLS / ODS: deep (hücre bazlı detaylı karşılaştırma)
PDF: pdfpage (sayfa bazlı metin karşılaştırması)
PPTX / PPT: diffplex
Metin dosyaları: diffplex
2.5. Kelime Bazlı Inline Diff ve Navigasyon
DocumentCompare elementi, satır bazlı karşılaştırmanın yanında kelime bazlı inline diff desteği de sunar. Bu sayede kullanıcılar yalnızca hangi satırın değiştiğini değil, ilgili satır veya içerik bloğu içinde hangi kelime ya da ifade düzeyinde fark oluştuğunu da görebilir.
Bu özellik özellikle küçük metin değişikliklerinin yoğun olduğu dokümanlarda, farkların daha hassas ve okunabilir şekilde incelenmesini sağlar.
Kelime bazlı inline diff desteği: DocumentCompare, değişiklikleri InlineSegment yapısı ile kelime seviyesinde işaretleyebilir.
Bu yapı sayesinde:
eklenen kelimeler
silinen kelimeler
değiştirilen ifadeler
aynı satır veya paragraf içinde daha net şekilde gösterilir.
Myers LCS algoritması kullanılır: Kelime seviyesindeki farkların tespitinde Myers LCS (Longest Common Subsequence) algoritması kullanılır. Bu algoritma, iki metin arasındaki en anlamlı farkları belirlemeye yardımcı olur ve özellikle metin karşılaştırmalarında yüksek doğruluk sağlar.
DOCX dosyalarında cümle bölümleme desteği vardır: DOCX tabanlı karşılaştırmalarda, daha doğru diff üretmek için sentence splitting uygulanır. Bu sayede uzun metin blokları doğrudan tek parça olarak karşılaştırılmak yerine, cümle düzeyinde bölünerek analiz edilir. Sonuç olarak:
daha okunabilir diff çıktısı oluşur
küçük metin değişiklikleri daha doğru tespit edilir
gereksiz büyük fark blokları azaltılır
Görsel dosyalar için benzerlik yüzdesi gösterilebilir: Görsel karşılaştırma yapılan dosyalarda sistem, iki içerik arasındaki farkı yalnızca işaretlemekle kalmaz, aynı zamanda similarity % bilgisini de gösterebilir. Bu oran, iki görselin ne kadar benzer olduğunu özetlemek için kullanılır.
PDF ve PPTX için format bazlı diff desteği vardır:
PDF dosyalarında sayfa bazlı diff uygulanır.
PPTX dosyalarında slayt bazlı diff uygulanır. Bu yapı sayesinde her dosya tipi kendi yapısına uygun bir karşılaştırma modeli ile işlenir.
Sonraki / Önceki değişiklik navigasyonu desteklenir: Kullanıcı, karşılaştırma ekranında bulunan değişiklikler arasında hızlı geçiş yapabilir. Bu özellik özellikle çok sayıda fark içeren dokümanlarda inceleme sürecini hızlandırır. Desteklenen kısayollar:
Ctrl + N → Sonraki değişikliğe gider
Ctrl + P → Önceki değişikliğe gider
3. Document Compara Elementi Kullanım Senaryosu
Kullanıcı, bir sözleşmenin v2 ve v3 versiyonlarını karşılaştırmak ister. Kullanıcı iki farklı versiyonu seçer, Document Compare elementi bu versiyonları otomatik olarak karşılaştırır ve sonucu ekranda gösterir.
Page Init: Sayfa açıldığında önce ilgili dokümana ait versiyon listesi alınır. Bu liste, eski ve yeni versiyon seçimi yapılacak iki ayrı dropdown elementine bağlanır.
GetVersions(documentId) çalıştırılır → dsVersions
DropDown_EskiVersiyon.options = dsVersions
DropDown_YeniVersiyon.options = dsVersions
Bu yapı sayesinde kullanıcı, aynı dokümana ait mevcut versiyonlar arasından seçim yapabilir.
DropDown_EskiVersiyon.onChange: Kullanıcı eski versiyonu değiştirdiğinde, seçilen değer DocumentCompare elementinin leftVersionId alanına atanır.
DocumentCompare otomatik karşılaştırma süreci: Her iki versiyon ID’si de atandığında, DocumentCompare elementi karşılaştırma işlemini otomatik olarak başlatır.
Sistem, kısa aralıklarla yapılan ardışık değişiklikleri tek işlemde toplamak için 50ms debounce uygular.
Ardından backend’e karşılaştırma isteği gönderilir.
Sonuç türüne göre uygun görüntüleme modu açılır.
Akış şu şekilde ilerler:
POST /documentmanagement/compare çağrılır
Backend karşılaştırma sonucunu üretir
Sonuca göre:
Collabora modu kullanılıyorsa iframe içinde tracked-changes görünümü açılır
Metin diff modu kullanılıyorsa yan yana diff panelleri render edilir
DocumentCompare.onLoad: Karşılaştırma işlemi başarıyla tamamlandığında, sonuç bilgisi kullanılarak ek aksiyonlar çalıştırılabilir.
