Jak odczytać kod QR z PDF przy użyciu Javy

Wprowadzenie

Czy kiedykolwiek musiałeś wyodrębnić informacje o kodach kreskowych ze setek faktur PDF, etykiet wysyłkowych lub dokumentów inwentaryzacyjnych? Ręczne przeglądanie stron jest żmudne i podatne na błędy. Niezależnie od tego, czy budujesz zautomatyzowany system przetwarzania dokumentów, czy weryfikujesz autentyczność produktów, efektywne znajdowanie kodów kreskowych w PDF‑ach może być wyzwaniem.

W tym przewodniku dowiesz się, jak odczytywać kod QR z dokumentów PDF efektywnie przy użyciu API GroupDocs.Signature. To potężne API zamienia godziny ręcznej pracy w kilka linijek kodu. Możesz skanować całe dokumenty, lokalizować określone typy kodów kreskowych (takie jak QR czy Code128) i automatycznie wyodrębniać ich dane.

Czego się nauczysz:

Konfiguracji GroupDocs.Signature dla Javy w kilka minut
Wyszukiwania podpisów kodów kreskowych w dokumentach PDF
Konfigurowania opcji wyszukiwania dla precyzyjnych, ukierunkowanych wyników
Obsługi różnych typów kodów kreskowych (QR, EAN, Code128 itp.)
Rozwiązywania typowych problemów i optymalizacji wydajności

Zanurzmy się!

Szybkie odpowiedzi

Czy GroupDocs.Signature potrafi odczytywać kody QR z PDF‑ów? Tak, wykrywa QR, Data Matrix, PDF417 oraz wiele kodów 1D.
Czy potrzebna jest licencja do użytku produkcyjnego? Wymagana jest licencja komercyjna; dostępna jest darmowa wersja próbna do oceny.
Jakiej wersji Javy wymaga? Java 8+ (zalecane Java 11+).
Jak ograniczyć wyszukiwanie do konkretnych stron? Użyj BarcodeSearchOptions.setAllPages(false) i ustaw setPageNumber().
Czy API jest wątkowo‑bezpieczne przy przetwarzaniu wsadowym? Tak, pod warunkiem tworzenia osobnej instancji Signature dla każdego wątku.

Dlaczego wyszukiwać kody kreskowe w PDF‑ach?

Zanim przejdziemy do technicznych szczegółów, oto dlaczego ma to znaczenie w rzeczywistych zastosowaniach:

Typowe scenariusze biznesowe

Przetwarzanie faktur – Automatyczne wyodrębnianie numerów zamówień lub kodów śledzenia z faktur dostawców.
Zarządzanie zapasami – Skanowanie katalogów produktów i wyciąganie kodów SKU do aktualizacji bazy danych.
Transport i logistyka – Weryfikacja kodów śledzenia paczek w listach przewozowych.
Uwierzytelnianie dokumentów – Walidacja podpisanych dokumentów poprzez sprawdzenie wbudowanych kodów bezpieczeństwa.
Rekordy medyczne – Wyodrębnianie identyfikatorów pacjentów lub kodów recept z dokumentacji medycznej.

API GroupDocs.Signature zajmuje się ciężką pracą – nie musisz martwić się o przetwarzanie obrazów, algorytmy dekodowania kodów kreskowych ani złożoność renderowania PDF. Wszystko jest wbudowane.

Wymagania wstępne

Zanim rozpoczniesz ten samouczek, upewnij się, że masz przygotowane następujące elementy:

Wymagane biblioteki i zależności

Musisz dodać bibliotekę GroupDocs.Signature do swojego projektu Java. Oto jak to zrobić przy użyciu Maven lub Gradle:

Maven:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

Gradle:

implementation 'com.groupdocs:groupdocs-signature:23.12'

Uwaga: Zawsze sprawdzaj najnowszą wersję na stronie GroupDocs.Signature dla Javy – wydania. Korzystanie z najnowszej wersji zapewnia poprawki błędów i nowe funkcje.

Konfiguracja środowiska

JDK 8 lub wyższy – GroupDocs.Signature wymaga co najmniej Java 8 (zalecane Java 11+ dla lepszej wydajności).
IDE – Każdy edytor tekstu się sprawdzi, ale IntelliJ IDEA lub Eclipse ułatwią życie dzięki autouzupełnianiu i debugowaniu.
Dokument PDF – Przygotuj testowy PDF z kodami kreskowymi (faktury, etykiety wysyłkowe lub katalogi produktów działają świetnie).

Wymagania wiedzy

Powinieneś być zaznajomiony z:

Podstawową składnią Javy i koncepcjami obiektowymi
Obsługą wyjątków przy użyciu bloków try‑catch
Pracą z zewnętrznymi bibliotekami w IDE

Jeśli dopiero zaczynasz przygodę z bibliotekami firm trzecich, nie martw się – przeprowadzimy Cię krok po kroku.

Konfiguracja GroupDocs.Signature dla Javy

Rozpoczęcie pracy z GroupDocs.Signature zajmuje tylko kilka minut. Oto kompletny proces konfiguracji:

Krok 1: Dodaj zależność

Użyj Maven lub Gradle, aby dołączyć bibliotekę (zobacz kod powyżej). Po dodaniu zależności odśwież projekt, aby pobrać pliki JAR.

Krok 2: Uzyskanie licencji

GroupDocs oferuje kilka opcji licencjonowania:

Darmowa wersja próbna – Idealna do testów. Pobierz z GroupDocs releases.
Licencja tymczasowa – Uzyskaj 30‑dniowy pełny dostęp poprzez Stronę licencji tymczasowej.
Licencja komercyjna – Do użytku produkcyjnego zakup licencję na GroupDocs Purchase.

Pro tip: Zacznij od wersji próbnej, aby zbudować proof‑of‑concept, a potem przejdź na licencję komercyjną, jeśli API spełni Twoje oczekiwania.

Krok 3: Podstawowa inicjalizacja

Poniżej przykład tworzenia obiektu Signature do pracy z Twoim PDF‑em:

import com.groupdocs.signature.Signature;

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with your PDF path
Signature signature = new Signature(filePath);

Klasa Signature jest Twoim głównym punktem wejścia. Ładuje PDF do pamięci i udostępnia metody do wyszukiwania, weryfikacji i wyodrębniania danych podpisu (w tym kodów kreskowych).

Ważne: Upewnij się, że ścieżka do pliku jest prawidłowa i PDF istnieje. Typowy błąd początkujących? Używanie odwrotnych ukośników w Windows bez ich escapowania (C:\\Documents\\file.pdf zamiast C:\Documents\file.pdf).

Przewodnik implementacji

Teraz najciekawsza część – napiszmy kod, który wyszukuje kody kreskowe w Twoim PDF‑ie.

Wyszukiwanie podpisów kodów kreskowych w dokumencie

Ten rozdział pokazuje, jak zeskanować PDF i zlokalizować wszystkie podpisy kodów kreskowych. Podzielimy go na przystępne kroki z wyjaśnieniami.

Krok 1: Inicjalizacja obiektu Signature

Załaduj dokument PDF:

import com.groupdocs.signature.Signature;

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with actual file path
Signature signature = new Signature(filePath);

Co się dzieje
Klasa Signature otwiera Twój PDF i przygotowuje go do przetwarzania. To jak otwarcie pliku w edytorze tekstu – dokument zostaje załadowany do pamięci, abyś mógł na nim pracować.

Uwaga z życia wzięta
Jeśli przetwarzasz PDF‑y przesyłane przez użytkowników, zawsze waliduj ścieżkę i sprawdzaj, czy plik istnieje przed utworzeniem obiektu Signature. Zapobiega to niejasnym błędom później.

Krok 2: Utwórz BarcodeSearchOptions

Skonfiguruj, jak chcesz wyszukiwać kody kreskowe:

import com.groupdocs.signature.options.search.BarcodeSearchOptions;

// Configure options for searching barcodes
BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setAllPages(true); // Search every page in the document

Kluczowe opcje konfiguracji

setAllPages(true): Skanuje wszystkie strony. Ustaw false, jeśli chcesz sprawdzić tylko wybrane strony (konfigurujesz je za pomocą setPageNumber()).
Dlaczego to ważne: Jeśli przetwarzasz faktury, na których kody kreskowe zawsze znajdują się na stronie 1, przeszukiwanie wszystkich stron marnuje zasoby. W przypadku wielostronicowych list przewozowych potrzebujesz setAllPages(true).

Pro tip: Możesz także filtrować po typie kodu kreskowego (więcej w sekcji Obsługiwane typy kodów kreskowych poniżej). Przyspiesza to wyszukiwanie, gdy wiesz, jaki format Cię interesuje.

Krok 3: Wykonaj wyszukiwanie i obsłuż wyniki

Teraz uruchom wyszukiwanie i przetwórz wyniki:

import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import java.util.List;

try {
    // Execute the barcode search
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    
    // Check if any barcodes were found
    if (signatures.isEmpty()) {
        System.out.println("No barcode signatures found in the document.");
    } else {
        System.out.println("Found " + signatures.size() + " barcode signature(s):\n");
        
        // Loop through each barcode and display details
        for (BarcodeSignature barcodeSignature : signatures) {
            System.out.println("----------------------------------------");
            System.out.println("Barcode Type: " + barcodeSignature.getEncodeType().getTypeName());
            System.out.println("Barcode Text: " + barcodeSignature.getText());
            System.out.println("Page Number: " + barcodeSignature.getPageNumber());
            System.out.println("Position: X=" + barcodeSignature.getLeft() + 
                             ", Y=" + barcodeSignature.getTop());
            System.out.println("Size: Width=" + barcodeSignature.getWidth() + 
                             ", Height=" + barcodeSignature.getHeight());
            System.out.println("----------------------------------------\n");
        }
    }
} catch (Exception e) {
    System.err.println("Error searching for barcodes: " + e.getMessage());
    e.printStackTrace();
} finally {
    // Always dispose of the signature object to free resources
    if (signature != null) {
        signature.dispose();
    }
}

Co robi ten kod

Wykonanie wyszukiwania – signature.search() skanuje PDF i zwraca listę obiektów BarcodeSignature.
Sprawdzenie pustej listy – Zapobiega wyjątkom typu null‑pointer, gdy nie znaleziono kodów.
Wyodrębnianie danych – Dla każdego kodu pobieramy:
- Typ – Format kodu (QR Code, Code128, EAN13 itp.)
- Tekst – Zdekodowane dane (numer zamówienia, kod śledzenia, SKU itp.)
- Lokalizacja – Numer strony oraz współrzędne X/Y
- Wymiary – Szerokość i wysokość (przydatne przy walidacji)
Obsługa błędów – try‑catch zapobiega awariom w przypadku problemów (uszkodzony PDF, brak pliku itp.).
Czyszczenie zasobów – Blok finally zapewnia prawidłowe zwolnienie obiektu Signature, co zwalnia pamięć.

Zastosowanie w praktyce
Załóżmy, że przetwarzasz etykiety wysyłkowe. Wyodrębniasz wartość getText() (numer śledzenia) i zapisujesz ją w bazie danych. Numer strony informuje, która etykieta odpowiada któremu zamówieniu, jeśli przetwarzasz dokumenty wsadowe.

Filtrowanie po typie kodu kreskowego

Możesz przyspieszyć wyszukiwanie, określając typ kodu, którego szukasz:

import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setEncodeType(BarcodeTypes.QR); // Only search for QR codes
options.setAllPages(true);

Kiedy filtrować
Jeśli wiesz, że Twoje faktury zawierają wyłącznie kody Code128, filtrowanie po typie skróci czas przetwarzania o 30‑50 % w dużych dokumentach.

Obsługiwane typy kodów kreskowych

GroupDocs.Signature potrafi wykrywać szeroką gamę formatów kodów kreskowych. Oto, co możesz wyszukiwać:

Kody 1D (liniowe)

Code128 – Powszechny w wysyłce i opakowaniach
Code39 – Stosowany w przemyśle motoryzacyjnym i obronnym
EAN13/EAN8 – Kody produktów detalicznych (widziane na każdym produkcie)
UPC‑A/UPC‑E – Standard detaliczny w Ameryce Północnej
Interleaved2of5 – Magazyny i dystrybucja

Kody 2D (matrycowe)

QR Code – Najpopularniejszy – używany do URL‑ów, haseł Wi‑Fi, płatności
Data Matrix – Kompaktowy format dla małych przedmiotów (komponenty elektroniczne)
PDF417 – Dokumenty rządowe, karty pokładowe, prawo jazdy
Aztec Code – Bilety transportowe

Filtrowanie po typie (przykład podany wyżej) pomaga skupić się na dokładnie tym formacie, którego potrzebujesz.

Praktyczne przypadki użycia

Oto, jak programiści wykorzystują wyszukiwanie kodów kreskowych w produkcji:

1. Automatyczne przetwarzanie faktur

Scenariusz – Dział księgowości otrzymuje codziennie ponad 500 faktur od dostawców w formacie PDF.
Rozwiązanie – Skanowanie każdej faktury pod kątem kodów Code39 zawierających numery faktur, automatyczne dopasowywanie ich do zamówień w systemie ERP. Eliminacja ręcznego wprowadzania danych i redukcja błędów.

// Pseudo-code workflow
for (PDF invoice : invoiceBatch) {
    List<BarcodeSignature> barcodes = searchBarcodes(invoice);
    String invoiceNumber = barcodes.get(0).getText();
    updateERPSystem(invoiceNumber, invoice);
}

2. Aktualizacje inwentarza w magazynie

Scenariusz – Magazyn otrzymuje przesyłki z listami pakowania w PDF, na których znajdują się kody SKU w formacie EAN13.
Rozwiązanie – Wyodrębnianie wszystkich kodów z listów, automatyczna aktualizacja stanów magazynowych i flagowanie niezgodności do weryfikacji.

3. Uwierzytelnianie dokumentów

Scenariusz – Dokumenty prawne zawierają kody QR z podpisami kryptograficznymi w celu weryfikacji autentyczności.
Rozwiązanie – Wyszukiwanie kodów QR w podpisanych umowach, dekodowanie danych podpisu i weryfikacja względem zaufanego urzędu certyfikacji. Zapewnia, że dokumenty nie zostały zmodyfikowane.

4. Zarządzanie rekordami medycznymi

Scenariusz – Pliki pacjentów w szpitalach zawierają raporty laboratoryjne w PDF z kodami Code128 identyfikującymi próbki.
Rozwiązanie – Automatyczne wyodrębnianie identyfikatorów próbek i łączenie wyników badań z rekordami pacjenta w systemie HIS.

Typowe problemy i rozwiązania

Oto problemy, które mogą się pojawić, oraz sposoby ich naprawy:

Problem 1: „Nie znaleziono kodów” (choć wiesz, że istnieją)

Możliwe przyczyny

Jakość obrazu kodu jest zbyt niska (rozmyta, pikselowana)
PDF jest oparty na obrazie, a kod jest zbyt mały
Szukasz niewłaściwego typu kodu

Rozwiązania

Sprawdź rozdzielczość obrazu – Kody kreskowe potrzebują co najmniej 200 DPI, aby były niezawodnie wykrywane. Przy skanowaniu używaj 300 DPI lub wyżej.
Usuń filtrowanie po typie – Najpierw przeszukaj wszystkie typy kodów (nie ustawiaj setEncodeType()), a potem zawęź zakres, gdy już wiesz, co jest w dokumencie.
Zweryfikuj jakość kodu – Otwórz PDF w Adobe Acrobat i przybliż. Jeśli kod wygląda na rozmyty, API również będzie miał problem.

Problem 2: `OutOfMemoryError` przy dużych PDF‑ach

Przyczyna – Ładowanie 500‑stronicowego PDF‑a z obrazami wysokiej rozdzielczości zużywa dużo pamięci.

Rozwiązanie

Przetwarzaj strony partiami – Zamiast setAllPages(true), przetwarzaj po 50 stron:

for (int startPage = 1; startPage <= totalPages; startPage += 50) {
    BarcodeSearchOptions options = new BarcodeSearchOptions();
    options.setPageNumber(startPage);
    options.setPagesSetup(new PagesSetup());
    options.getPagesSetup().setLastPage(Math.min(startPage + 49, totalPages));
    
    List<BarcodeSignature> batchResults = signature.search(BarcodeSignature.class, options);
    // Process results...
}

Zwiększ rozmiar sterty JVM – Dodaj -Xmx4g do polecenia Java, aby przydzielić 4 GB pamięci (dostosuj w zależności od potrzeb).

Problem 3: Wolna wydajność przy dokumentach wielostronicowych

Przyczyna – Sekwencyjne przeszukiwanie wszystkich stron zajmuje czas, zwłaszcza przy skomplikowanych kodach jak PDF417.

Rozwiązania

Przetwarzanie równoległe – Jeśli kody zawsze znajdują się na określonych stronach (np. strona 1 faktur), przeszukuj tylko te strony.
Buforowanie wyników – Jeśli ten sam dokument jest przetwarzany wielokrotnie, zapamiętuj wyniki, aby nie skanować go ponownie.
Używaj dysków SSD – Szybkość I/O ma znaczenie przy ładowaniu dużych PDF‑ów. SSD‑y skracają czas ładowania o 60‑70 % w porównaniu z HDD.

Problem 4: Fałszywe trafienia (wykrywanie losowych wzorów jako kodów)

Przyczyna – Tabele, siatki lub linie mogą być błędnie rozpoznane jako kody kreskowe.

Rozwiązanie – Waliduj wyniki, sprawdzając długość i format zdekodowanego tekstu:

for (BarcodeSignature barcode : signatures) {
    String text = barcode.getText();
    
    // Example: Invoice numbers are always 10 digits
    if (text.matches("\\d{10}")) {
        // Valid invoice number
        processBarcode(barcode);
    } else {
        System.out.println("Skipping invalid barcode: " + text);
    }
}

Wskazówki wydajnościowe dla dużych dokumentów

Przetwarzasz tysiące PDF‑ów? Oto jak zoptymalizować proces:

1. Strategia przetwarzania wsadowego

Zamiast przetwarzać pliki pojedynczo, użyj puli wątków, aby obsłużyć wiele PDF‑ów jednocześnie:

ExecutorService executor = Executors.newFixedThreadPool(4); // 4 parallel threads

for (String pdfPath : pdfFiles) {
    executor.submit(() -> {
        try (Signature sig = new Signature(pdfPath)) {
            List<BarcodeSignature> results = sig.search(BarcodeSignature.class, options);
            // Process results...
        } catch (Exception e) {
            e.printStackTrace();
        }
    });
}

executor.shutdown();
executor.awaitTermination(1, TimeUnit.HOURS);

Zysk wydajnościowy – Przetworzenie 1 000 plików spada z ~2 godzin do ~30 minut na czterordzeniowej maszynie.

2. Ogranicz zakres wyszukiwania

Jeśli logika biznesowa na to pozwala, ogranicz obszar przeszukiwania:

// Only search the top‑right corner where barcodes are typically placed
options.setRectangle(new Rectangle(400, 50, 150, 150)); // X, Y, Width, Height

Zysk wydajnościowy – 40‑60 % szybsze na dokumentach, w których pozycja kodu jest stała.

3. Monitoruj zużycie pamięci

W długotrwałych procesach wsadowych obserwuj zużycie sterty i w razie potrzeby wymuszaj garbage collection:

Runtime runtime = Runtime.getRuntime();
long usedMemory = runtime.totalMemory() - runtime.freeMemory();

if (usedMemory > (runtime.maxMemory() * 0.8)) {
    System.gc(); // Suggest garbage collection
}

Najlepsze praktyki

Stosuj się do tych wytycznych, aby kod był gotowy do produkcji:

1. Zawsze zwalniaj obiekty Signature

Użyj try‑with‑resources (Java 7+), aby automatycznie zamykać zasoby:

try (Signature signature = new Signature(filePath)) {
    // Your search code here...
} // Automatically disposed

2. Waliduj pliki wejściowe

Przed przetworzeniem sprawdź, czy plik istnieje i jest prawidłowym PDF‑em:

File pdfFile = new File(filePath);
if (!pdfFile.exists() || !pdfFile.canRead()) {
    throw new FileNotFoundException("PDF not found or not readable: " + filePath);
}

// Optional: Verify it's actually a PDF (check magic bytes)

3. Loguj wyniki wykrywania kodów

Do debugowania i audytu zapisuj, co zostało znalezione:

Logger logger = Logger.getLogger(BarcodeSearcher.class.getName());

for (BarcodeSignature barcode : signatures) {
    logger.info(String.format("Detected %s barcode '%s' on page %d at (%.2f, %.2f)",
        barcode.getEncodeType().getTypeName(),
        barcode.getText(),
        barcode.getPageNumber(),
        barcode.getLeft(),
        barcode.getTop()));
}

4. Obsługuj różne formaty kodów

Różne branże używają różnych standardów. Projektuj kod elastycznie:

switch (barcode.getEncodeType().getTypeName()) {
    case "QR":
        // QR codes might contain URLs or JSON data
        processQRCode(barcode.getText());
        break;
    case "Code128":
        // Code128 typically contains alphanumeric order/tracking numbers
        processTrackingNumber(barcode.getText());
        break;
    default:
        logger.warning("Unexpected barcode type: " + barcode.getEncodeType());
}

5. Testuj na rzeczywistych dokumentach

Nie ograniczaj się do idealnych przykładów. Użyj prawdziwych dokumentów z produkcji:

Zeskanowane faktury z plamami kawy
Faxowane listy przewozowe z szumem
Niskiej rozdzielczości zdjęcia z telefonu zamienione na PDF

To ujawni przypadki brzegowe, których nie znajdziesz w demonstracjach.

Najczęściej zadawane pytania

P: Czy mogę odczytywać kod QR z PDF‑ów bez licencji?
O: Darmowa wersja próbna pozwala na odczyt kodu QR z PDF‑ów w celach ewaluacyjnych, ale do wdrożeń produkcyjnych wymagana jest licencja komercyjna.

P: Czy API obsługuje PDF‑y zabezpieczone hasłem?
O: Tak. Hasło można przekazać przy tworzeniu obiektu Signature: new Signature(filePath, "password").

P: Jak poprawić wykrywanie przy niskiej rozdzielczości skanów?
O: Zwiększ DPI źródłowego skanu (minimum 200 DPI) i rozważ filtrowanie po typie kodu, aby ograniczyć liczbę fałszywych trafień.

P: Czy wyszukiwanie jest wątkowo‑bezpieczne przy przetwarzaniu równoległym?
O: Każdy wątek powinien używać własnej instancji Signature. API jest wątkowo‑bezpieczne przy takiej praktyce.

P: Z jaką wersją GroupDocs.Signature testowano ten samouczek?
O: Kod został zweryfikowany z GroupDocs.Signature 23.12.

Podsumowanie

Właśnie nauczyłeś się, jak odczytywać kod QR z dokumentów PDF przy użyciu Javy i API GroupDocs.Signature. Oto, co omówiliśmy:

✅ Konfiguracja – Dodanie GroupDocs.Signature do projektu i opcje licencjonowania
✅ Implementacja – Pełny kod do wyszukiwania, wyodrębniania i przetwarzania danych kodów kreskowych
✅ Typy kodów – Przegląd obsługiwanych formatów (1D i 2D)
✅ Przypadki użycia – Przetwarzanie faktur, zarządzanie zapasami, uwierzytelnianie dokumentów, rekordy medyczne
✅ Rozwiązywanie problemów – Jak radzić sobie z błędami pamięci i fałszywymi trafieniami
✅ Wydajność – Optymalizacja przetwarzania dużych ilości dokumentów

API GroupDocs.Signature zajmuje się złożonością parsowania PDF i wykrywania kodów kreskowych, pozwalając Ci skupić się na logice biznesowej. Niezależnie od tego, czy automatyzujesz przetwarzanie faktur, weryfikujesz etykiety wysyłkowe, czy wyciągasz dane inwentaryzacyjne, masz teraz solidne rozwiązanie.

Ostatnia aktualizacja: 2026-03-01
Testowane z: GroupDocs.Signature 23.12
Autor: GroupDocs