Porównaj dokumenty PDF w C#: Inline, Side‑by‑Side i Interleaved

Wprowadzenie

PDF jest de‑facto standardem dla umów, specyfikacji, raportów i dokumentów regulacyjnych — a przy wielu wersjach w obiegu, szybkie ustalenie, co dokładnie zmieniło się pomiędzy dwoma plikami, staje się żmudne. Przewijanie dokumentów obok siebie i ręczne oznaczanie różnic nie skaluje się, a nawet dedykowane narzędzia, takie jak funkcja Compare w Adobe Acrobat, wymagają ręcznej interwencji przy każdej parze plików.

GroupDocs.Comparison for .NET umożliwia porównywanie PDF‑ów w pełni z poziomu kodu i precyzyjny wybór sposobu prezentacji wyniku. Wersja 26.4 wprowadziła dedykowaną klasę PdfCompareOptions z trzema trybami wyświetlania:

1. Inline (domyślnie) — pojedynczy scalony PDF, w którym usunięcia i wstawienia są podświetlone różnymi kolorami na tych samych stronach. To klasyczne zachowanie i najłatwiejszy wynik do udostępnienia jako samodzielny plik.
2. Side‑by‑Side — każda strona wyniku pokazuje stronę źródłową i docelową obok siebie, bez nakładania się treści. Idealny, gdy dokumenty różnią się znacznie i mieszanie treści na jednej stronie byłoby mylące.
3. Interleaved — wynik zawiera naprzemiennie strony: nieparzyste pochodzą ze źródła (usunięcia podświetlone), parzyste z docelowego (wstawienia podświetlone). Zmiany są reprezentowane jako natywne adnotacje PDF — wbudowany typ obiektu PDF, który niesie metadane takie jak typ zmiany i nazwa autora. Większość przeglądarek PDF (Adobe Acrobat Reader, Foxit itp.) pozwala otworzyć panel adnotacji i zaakceptować lub usunąć poszczególne adnotacje, co tworzy lekki przepływ recenzji bez dodatkowego oprogramowania. Otworzenie tego pliku w przeglądarce PDF w trybie Two Page View daje naturalne porównanie lewa/prawa.

W tym artykule przejdziemy przez wszystkie trzy tryby z działającymi przykładami w C#, przyjrzymy się PdfCompareOptions i jego właściwościom oraz krótko omówimy, jak to samo zadanie wykonać ręcznie w Adobe Acrobat.

Porównywanie plików PDF w Adobe Acrobat

Zanim przejdziemy do podejścia programistycznego, warto poznać, co oferuje Adobe Acrobat Pro „out of the box”. Wbudowane narzędzie Compare Files (dostępne w Tools → Compare Files) generuje raport obok siebie, podświetlający zmiany tekstu, różnice w obrazach i zmiany formatowania.

Aby uruchomić porównanie w Acrobat Pro:

1. Otwórz Acrobat Pro i wybierz Tools → Compare Files.
2. Wybierz Older File (źródło) i Newer File (cel).
3. Kliknij Compare. Acrobat generuje interaktywny raport porównania z podsumowaniem i znacznikami zmian w treści.

Działa to dobrze przy okazjonalnych ręcznych przeglądach. Jednak narzędzie porównania w Acrobat ma istotne ograniczenia, gdy porównanie musi być częścią zautomatyzowanego potoku.

Gdy porównanie musi odbywać się na serwerze, w potoku CI/CD lub jako część własnego przepływu recenzji, biblioteka kodowa jest właściwym rozwiązaniem.

Wymagania wstępne

Zanim rozpoczniesz:

• .NET 6.0 lub nowszy.
• GroupDocs.Comparison for .NET 26.4 lub nowszy — zainstaluj przez NuGet:

dotnet add package GroupDocs.Comparison

• Plik licencji (GroupDocs.Comparison.lic). Bez niego biblioteka działa w trybie ewaluacyjnym z znakami wodnymi i limitami liczby stron. Możesz poprosić o tymczasową licencję do testów.
• Dwa pliki PDF do porównania — nazwijmy je source.pdf i target.pdf. Przykładowa zawartość:

Tryb 1: Porównanie Inline (Domyślne)

Kiedy używać: potrzebujesz jednego, samodzielnego pliku PDF, który każdy może otworzyć i od razu zobaczyć, co się zmieniło — bez specjalnego czytnika czy układu dwustronicowego. Typowy scenariusz to udostępnienie wersji kontraktu z zaznaczonymi zmianami kontrahentowi.

using GroupDocs.Comparison;
using GroupDocs.Comparison.Options;

using (var comparer = new Comparer("source.pdf"))
{
    comparer.Add("target.pdf");

    var options = new PdfCompareOptions
    {
        DisplayMode = PdfCompareOptions.ComparisonDisplayMode.Inline
    };

    comparer.Compare("result_inline.pdf", options);
}

Uwaga: Inline jest wartością domyślną DisplayMode, więc blok options jest opcjonalny. Wywołanie comparer.Compare("result_inline.pdf") daje ten sam wynik.

Wynikowy dokument w trybie Inline:

Co się dzieje w tle:

• Usunięta treść ze źródłowego dokumentu jest podświetlona jednym kolorem (domyślnie czerwonym).
• Wstawiona treść z dokumentu docelowego jest podświetlona innym kolorem (domyślnie zielonym).
• Oba zestawy zmian współistnieją na tych samych stronach, więc wynik jest zwarty, ale może wyglądać na zatłoczony, gdy dokumenty różnią się znacznie. Przy dużych edycjach tekstu usunięta i wstawiona treść może fizycznie nachodzić na siebie — np. zamieniony akapit renderuje się na wierzchu oryginału, tworząc nieczytelny bałagan. W takich przypadkach lepszy będzie tryb SideBySide lub Interleaved.

Tryb 2: Porównanie Side‑by‑Side

Kiedy używać: dokumenty różnią się znacznie i umieszczanie usunięć i wstawek na tej samej stronie utrudniałoby odczyt. Side‑by‑Side utrzymuje treść źródłową i docelową ściśle oddzieloną, co ułatwia szybkie przeglądanie każdej strony.

using GroupDocs.Comparison;
using GroupDocs.Comparison.Options;

using (var comparer = new Comparer("source.pdf"))
{
    comparer.Add("target.pdf");

    var options = new PdfCompareOptions
    {
        DisplayMode = PdfCompareOptions.ComparisonDisplayMode.SideBySide
    };

    comparer.Compare("result_side_by_side.pdf", options);
}

Wynikowy dokument w trybie Side‑by‑Side:

Co się dzieje w tle:

• Każda strona wyniku jest w zasadzie szerokim płótnem podzielonym na dwie połowy.
• Lewa połowa pokazuje odpowiadającą stronę źródłową z podświetlonymi usunięciami.
• Prawa połowa pokazuje stronę docelową z podświetlonymi wstawieniami.
• Treść z dwóch dokumentów nigdy się nie nakłada, więc nawet mocno edytowane strony pozostają czytelne.

Tryb 3: Porównanie Interleaved

Kiedy używać: chcesz przeglądać zmiany strona po stronie w standardowym czytniku PDF używając trybu Two Page View (lub „Facing Pages”). Każda strona źródłowa znajduje się po lewej, a odpowiadająca jej strona docelowa po prawej — układ fizyczny odzwierciedla to, co Side‑by‑Side renderuje na jednym płótnie, ale każda strona zachowuje pełny rozmiar.

using GroupDocs.Comparison;
using GroupDocs.Comparison.Options;

using (var comparer = new Comparer("source.pdf"))
{
    comparer.Add("target.pdf");

    var options = new PdfCompareOptions
    {
        DisplayMode = PdfCompareOptions.ComparisonDisplayMode.Interleaved,
        AnnotationAuthorName = "GroupDocs"
    };

    comparer.Compare("result_interleaved.pdf", options);
}

Wynikowy dokument w trybie Interleaved (wyświetlony w Twojej Page View):

Co się dzieje w tle:

• Dokument wynikowy zawiera 2 × N stron dla pary N‑stronowego źródła i celu.
• Strony nieparzyste (1, 3, 5 …) to strony źródłowe z podświetlonymi usunięciami.
• Strony parzyste (2, 4, 6 …) to strony docelowe z podświetlonymi wstawieniami.
• AnnotationAuthorName umieszcza nazwę autora w adnotacjach PDF tworzonych podczas porównania — przydatne, gdy wynik trafia do przepływu recenzji, w którym komentarze kilku autorów muszą być rozróżnialne.

Wskazówka: otwórz wynik w Adobe Acrobat Reader lub dowolnym czytniku obsługującym View → Page Display → Two Page View, aby automatycznie uzyskać zamierzony układ lewa/prawa.

Ograniczanie porównania do zakresu stron

Wszystkie trzy tryby obsługują filtrowanie zakresu stron za pomocą właściwości PagesSetup. Jest to przydatne, gdy zmieniony został tylko konkretny rozdział lub sekcja dużego dokumentu i chcesz pominąć resztę.

using GroupDocs.Comparison;
using GroupDocs.Comparison.Options;

using (var comparer = new Comparer("source.pdf"))
{
    comparer.Add("target.pdf");

    var options = new PdfCompareOptions
    {
        DisplayMode = PdfCompareOptions.ComparisonDisplayMode.SideBySide,
        PagesSetup = new PagesSetup
        {
            StartPage = 3,
            EndPage = 10
        }
    };

    comparer.Compare("result_pages_3_to_10.pdf", options);
}

Gdy PagesSetup jest null (lub nie ustawiony), porównywane są wszystkie strony — tak jak w poprzednich wersjach.

Badanie PdfCompareOptions

PdfCompareOptions jest podklasą specyficzną dla PDF klasy CompareOptions, działającą analogicznie do WordCompareOptions wprowadzonej w wersji 26.2. Grupuje wszystkie ustawienia dotyczące wyłącznie PDF w jednym miejscu, aby nie zastosować przypadkowo opcji specyficznych dla Worda lub arkuszy kalkulacyjnych do zadania PDF.

Przykład w pełni skonfigurowany:

var options = new PdfCompareOptions
{
    DisplayMode = PdfCompareOptions.ComparisonDisplayMode.Interleaved,
    CompareImagesPdf = true,
    AnnotationAuthorName = "Review Bot",
    PagesSetup = new PagesSetup { StartPage = 1, EndPage = 5 }
};

Dziedziczone właściwości bazowe CompareOptions — InsertedItemStyle, DeletedItemStyle, ChangedItemStyle — są również dostępne, umożliwiając nadpisanie domyślnych kolorów podświetlenia w razie potrzeby.

Pobieranie zmian programowo

Niezależnie od wybranego trybu wyświetlania, możesz uzyskać ustrukturyzowaną listę wszystkich wykrytych różnic za pomocą Comparer.GetChanges(). To przydatne przy budowie własnych raportów, wprowadzaniu wyników do systemu recenzji lub zbieraniu statystyk o zakresie edycji.

using (var comparer = new Comparer("source.pdf"))
{
    comparer.Add("target.pdf");

    comparer.Compare("result.pdf");

    var changes = comparer.GetChanges(); // zwraca ChangeInfo[]
    Console.WriteLine($"Łączna liczba wykrytych zmian: {changes.Length}");
}

Zobacz oficjalną dokumentację API po szczegóły: Comparer.GetChanges.

Praca z zabezpieczonymi hasłem plikami PDF

Pliki PDF chronione hasłem są w pełni obsługiwane. Przekaż hasło poprzez LoadOptions przy tworzeniu obiektu Comparer:

using GroupDocs.Comparison;
using GroupDocs.Comparison.Options;

using (var comparer = new Comparer("source_protected.pdf",
    new LoadOptions { Password = "secret" }))
{
    comparer.Add("target_protected.pdf", new LoadOptions { Password = "secret" });

    var options = new PdfCompareOptions
    {
        DisplayMode = PdfCompareOptions.ComparisonDisplayMode.SideBySide
    };

    comparer.Compare("result_protected.pdf", options);
}

Uzyskaj darmową wersję próbną

Możesz pobrać GroupDocs.Comparison for .NET ze strony oficjalnych wydań. Aby przetestować bez ograniczeń, poproś o tymczasową licencję — karta kredytowa nie jest wymagana.

Najczęściej zadawane pytania

P: Czy potrzebuję zainstalowanego Adobe Acrobat lub innego oprogramowania PDF na serwerze?
O: Nie. GroupDocs.Comparison to samodzielna biblioteka .NET, która odczytuje i zapisuje pliki PDF bez żadnych zewnętrznych zależności.

P: Który tryb wyświetlania powinienem używać domyślnie?
O: Zacznij od Inline — daje najbardziej zwarty wynik i najłatwiej go udostępnić. Przejdź na SideBySide, gdy intensywne edycje utrudniają odczyt w trybie inline, lub użyj Interleaved, gdy recenzenci otworzą wynik w trybie „Two Page View”.

P: Czy mogę porównywać dokumenty w formatach innych niż PDF?
O: Tak — biblioteka obsługuje dokumenty Word, arkusze Excel, prezentacje PowerPoint, pliki tekstowe i wiele innych. Pełna lista znajduje się w dokumentacji.

P: Co się stanie, jeśli nie ustawiam licencji?
O: Biblioteka działa w trybie ewaluacyjnym. Dokumenty wyjściowe będą zawierały znak wodny i przetworzone zostaną tylko pierwsze kilka stron. Tymczasowa licencja usuwa te ograniczenia w trakcie testów.

P: Czy mogę porównać tylko obrazy wewnątrz PDF i pominąć zmiany tekstu?
O: Ustaw CompareImagesPdf = true w PdfCompareOptions, aby włączyć porównanie obrazów. Aby skupić się wyłącznie na obrazach, możesz połączyć to z właściwością ImagesInheritanceMode; szczegóły znajdziesz w dokumentacji API.

Inne platformy

GroupDocs.Comparison jest dostępny jako natywna biblioteka dla kilku środowisk — opisany wyżej przepływ Inline / Side‑by‑Side / Interleaved jest dostępny we wszystkich z nich:

• GroupDocs.Comparison for Java
• GroupDocs.Comparison for Python via .NET
• GroupDocs.Comparison for Node.js via Java
• GroupDocs.Comparison Cloud API — językowo‑agnostyczne API REST

Powierzchnia API jest celowo utrzymana spójna między platformami, więc koncepcje Comparer / PdfCompareOptions / DisplayMode przekładają się bezpośrednio — zmienia się jedynie składnia.

Zakończenie

GroupDocs.Comparison for .NET 26.4 daje precyzyjną, kodową kontrolę nad tym, jak prezentowane są wyniki porównania PDF. Tryb Inline obejmuje najczęstszy scenariusz — pojedynczy, udostępnialny PDF z zaznaczonymi zmianami. SideBySide utrzymuje mocno zmienioną treść przejrzystą i czytelną. Interleaved naturalnie współgra z trybem Two Page View dowolnego czytnika PDF, umożliwiając pełnowymiarowy przegląd stron. Dodatkowo filtrowanie zakresu stron pozwala skupić się wyłącznie na istotnych fragmentach, a PdfCompareOptions konsoliduje wszystkie ustawienia specyficzne dla PDF w jednej, łatwej do odkrycia klasie.

Wybierz tryb pasujący do Twojego przepływu pracy lub wygeneruj wszystkie trzy i pozwól każdemu odbiorcy wybrać preferowaną wizualizację.

Dodatkowe zasoby

• GroupDocs.Comparison Documentation
• API Reference
• Get a Temporary License
• Sample Projects on GitHub
• GroupDocs.Comparison Blog Category
• Community Forum