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

Introduction

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. Przeglądanie 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 pozwala uruchomić porównanie PDF w całości z poziomu kodu i wybrać dokładnie, jak ma być przedstawiony wynik. Wersja 26.4 wprowadziła dedykowaną klasę PdfCompareOptions z trzema trybami wyświetlania wyniku:

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ą umieszczone 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 naprzemienne 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 czytniku PDF w trybie Two Page View daje naturalne porównanie lewa/prawa.

W tym artykule przeprowadzimy 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 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 side‑by‑side, 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.

Prerequisites

Zanim zaczniesz:

• .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 zamówić tymczasową licencję do testów.
• Dwa pliki PDF do porównania — nazwijmy je source.pdf i target.pdf. Przykładowa zawartość:

Mode 1: Inline Comparison (Default)

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 drugiej stronie.

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 domyślną wartością 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ść z dokumentu źródłowego jest podświetlona jednym kolorem (domyślnie czerwonym).
• Wstawiona treść z dokumentu docelowego jest podświetlona innym kolorem (domyślnie zielonym).
• Obie grupy zmian współistnieją na tych samych stronach, więc wynik jest zwarty, ale może wyglądać na „zagracony”, gdy dokumenty różnią się znacznie. Przy dużych edycjach tekstu usunięte i wstawione fragmenty mogą fizycznie nachodzić na siebie — np. zastąpiony akapit renderuje się na wierzchu oryginału, tworząc nieczytelny bałagan. W takich przypadkach lepszy będzie tryb SideBySide lub Interleaved.

Mode 2: Side‑by‑Side Comparison

Kiedy używać: dokumenty różnią się znacznie i umieszczanie usunięć oraz wstawek na tej samej stronie utrudniałoby odczyt. Side‑by‑Side trzyma treść źródłową i docelową ściśle oddzielnie, 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 to w zasadzie szerokie płótno podzielone 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.

Mode 3: Interleaved Comparison

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 (pokazany w Two‑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 trzeba odróżnić komentarze różnych autorów.

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.

Limiting Comparison to a Page Range

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 — zachowanie identyczne jak w poprzednich wersjach.

Exploring PdfCompareOptions

PdfCompareOptions jest podklasą specyficzną dla PDF klasy CompareOptions, 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.

Pełny przykład konfiguracji:

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.

Getting Changes Programmatically

Niezależnie od trybu wyświetlania, możesz pobrać ustrukturyzowaną listę wszystkich wykrytych różnic za pomocą Comparer.GetChanges(). Przydaje się to do budowania własnych raportów, wprowadzania wyników do systemu recenzji lub zbierania statystyk o zakresie edycji.

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

    comparer.Compare("result.pdf");

    var changes = comparer.GetChanges(); // returns ChangeInfo[]
    Console.WriteLine($"Total changes detected: {changes.Length}");
}

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

Working with Password‑Protected PDFs

PDF‑y zabezpieczone hasłem są w pełni obsługiwane. Przekaż hasło poprzez LoadOptions przy tworzeniu 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);
}

Get a Free Trial

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

Frequently Asked Questions

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

Q: Który tryb wyświetlania powinienem używać domyślnie?
A: Zacznij od Inline — generuje 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 czytniku PDF w trybie „Two Page View”.

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

Q: Co się stanie, jeśli nie ustawiam licencji?
A: 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 czasie testów.

Q: Czy mogę porównać tylko obrazy wewnątrz PDF i zignorować zmiany tekstu?
A: 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.

Conclusion

GroupDocs.Comparison for .NET 26.4 daje precyzyjną, kodową kontrolę nad tym, jak prezentowane są wyniki porównania PDF. Tryb Inline pokrywa najczęstszy przypadek — pojedynczy, udostępnialny PDF z zaznaczonymi zmianami. SideBySide utrzymuje mocno zmienioną treść czystą i czytelną. Interleaved naturalnie współgra z trybem Two‑Page View w dowolnym czytniku PDF, umożliwiając pełnowymiarowy przegląd stron. Dodatkowo filtrowanie zakresu stron pozwala skupić się dokładnie na interesujących 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ć preferowany widok.

Additional Resources

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