Jak dodać kod kreskowy do PDF w Javie

Wprowadzenie

Czy kiedykolwiek zmagałeś się z autentycznością dokumentów w swojej aplikacji Java? Nie jesteś sam. Niezależnie od tego, czy tworzysz system inwentaryzacji, zarządzasz umowami, czy obsługujesz dokumenty łańcucha dostaw, istnieje duże prawdopodobieństwo, że potrzebujesz niezawodnego sposobu na automatyczne podpisywanie i weryfikację plików PDF.

Tradycyjne podpisy cyfrowe są świetne, ale czasami potrzebujesz czegoś bardziej wyspecjalizowanego — np. podpisów w postaci kodów kreskowych, które współpracują bezproblemowo z systemami skanowania i zautomatyzowanymi przepływami pracy. Właśnie tutaj przydają się kody GS1DotCode.

Czego się nauczysz:

  • Jak podpisać dokumenty PDF kodami GS1DotCode w Javie
  • Jak wyodrębnić i zapisać obrazy podpisów kodów kreskowych
  • Kiedy (i dlaczego) używać podpisów kodów kreskowych zamiast tradycyjnych metod
  • Typowe pułapki i jak ich unikać

Po przeczytaniu tego przewodnika będziesz mieć gotowe rozwiązanie, które możesz zintegrować z dowolnym projektem Java.

Szybkie odpowiedzi

  • Jaką bibliotekę dodaje kody kreskowe do PDF‑ów w Javie? GroupDocs.Signature for Java.
  • Jaki format kodu kreskowego jest obsługiwany? GS1DotCode, kompaktowa macierz 2‑D z punktami.
  • Czy potrzebna jest płatna licencja? Bezpłatna wersja próbna wystarcza do testów; produkcja wymaga licencji komercyjnej.
  • Czy mogę wyodrębnić kod kreskowy jako obraz? Tak, przy użyciu API BarcodeSignature.
  • Jakiej wersji Javy wymaga biblioteka? JDK 8 lub wyższy.

Co to jest „how to add barcode”?

How to add barcode odnosi się do procesu programowego osadzania grafiki kodu kreskowego odczytywalnej maszynowo w pliku PDF, tak aby kod stał się częścią strumienia zawartości dokumentu. Obejmuje to generowanie obrazu kodu, pozycjonowanie go na stronie oraz zapis zmodyfikowanego PDF‑a, zapewniając, że kod pozostaje wyszukiwalny i drukowalny.

Dlaczego warto wybrać kody GS1DotCode?

GS1DotCode jest przeznaczony do sytuacji, w których miejsce jest ograniczone. W przeciwieństwie do liniowych kodów kreskowych rozciągających się w poziomie, DotCode tworzy macierz 2‑D z kropek, które mieszczą mnóstwo informacji w małym obszarze. Dzięki temu idealnie sprawdza się w:

  • Małych etykietach produktów, gdzie każdy milimetr się liczy
  • Szybkim drukowaniu na liniach produkcyjnych (format jest do tego zaprojektowany)
  • Śledzeniu łańcucha dostaw, gdy trzeba zakodować złożone struktury danych

Format może pomieścić do 3 116 znaków w kompaktowej przestrzeni i odczytuje się niezawodnie nawet przy wysokich prędkościach lub częściowym uszkodzeniu. Jeśli pracujesz w handlu detalicznym lub logistyce, Twoi partnerzy prawdopodobnie już używają standardów GS1 — więc mówisz tym samym językiem.

Pro tip: Używaj GS1DotCode, gdy potrzebujesz osadzić ponad 20 znaków na etykiecie mniejszej niż 1 cal × 1 cal.

Wymagania wstępne

Zanim zaczniesz kodować, sprawdź, czy Twoje środowisko spełnia poniższe wymagania.

Wymagane biblioteki i zależności

  • GroupDocs.Signature for Java 23.12 lub nowsza (obsługuje 30+ formatów dokumentów)
  • Maven lub Gradle do zarządzania zależnościami

Konfiguracja środowiska

  • JDK 8 lub nowszy, zainstalowany i skonfigurowany w PATH
  • IDE, takie jak IntelliJ IDEA, Eclipse lub NetBeans
  • Przykładowy plik PDF do eksperymentów (dowolny niechroniony PDF będzie odpowiedni)

Wymagania wiedzy

  • Podstawowa składnia Javy (zmienne, metody, obiekty)
  • Znajomość deklaracji zależności w Mavenie lub Gradle
  • Rozumienie operacji I/O w Javie (np. FileInputStream)

Jeśli którekolwiek z tych elementów brakuje, zatrzymaj się i zainstaluj je teraz; dalsze kroki zakładają ich obecność.

Konfiguracja GroupDocs.Signature for Java

Maven

Jeśli używasz Maven, dodaj następującą zależność do pliku pom.xml:

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

Maven pobierze bibliotekę oraz wszystkie wymagane zależności tranzytywne automatycznie.

Gradle

Dla użytkowników Gradle, wstaw tę linię do pliku build.gradle:

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

Gradle rozwiąże pakiet w ten sam, bezobsługowy sposób.

Bezpośrednie pobranie

Jeśli wolisz ręczne zarządzanie, pobierz pliki JAR ze strony wydania: GroupDocs.Signature for Java releases. Umieść JAR‑y na classpathie swojego projektu.

Pro tip: Maven lub Gradle upraszcza przyszłe aktualizacje — wystarczy podnieść numer wersji.

Uzyskanie licencji

GroupDocs oferuje trzy opcje licencjonowania:

  • Bezpłatna wersja próbna – bez karty kredytowej, znak wodny na wyjściu
  • Licencja tymczasowa – 30‑dniowa pełna ocena funkcji
  • Licencja komercyjna – usuwa ograniczenia wersji próbnej i przyznaje prawa do produkcji

Po uzyskaniu pliku licencyjnego umieść go w folderze resources projektu i załaduj przed utworzeniem jakiegokolwiek obiektu Signature.

License.setLicense ładuje plik licencyjny GroupDocs, umożliwiając pełną funkcjonalność bez ograniczeń wersji próbnej.

Uruchom poniższy fragment, aby zweryfikować prawidłowe załadowanie biblioteki:

import com.groupdocs.signature.Signature;

public class InitializeGroupDocs {
    public static void main(String[] args) {
        // Create an instance of Signature
        Signature signature = new Signature("path/to/your/document.pdf");
        
        System.out.println("Initialization successful!");
    }
}

Jeśli zobaczysz komunikat „Initialization successful!”, konfiguracja jest zakończona. W przeciwnym razie sprawdź classpath i ścieżkę do licencji.

Przewodnik implementacji

Omówimy dwie podstawowe funkcje: (1) podpisywanie PDF‑a kodem GS1DotCode oraz (2) wyodrębnianie tego kodu jako pliku obrazu.

Funkcja 1: podpisz dokument kodem GS1DotCode

Jak podpisać PDF kodem GS1DotCode w Javie?

Wczytaj docelowy PDF przy pomocy new Signature("source.pdf"), skonfiguruj obiekt BarcodeSignOptions zawierający dane w formacie GS1 i wywołaj sign(), aby utworzyć nowy PDF z osadzonym kodem. Operacja zapisuje kod bezpośrednio w strumieniu zawartości PDF, zachowując go podczas drukowania i ponownego skanowania.

Proces składa się z trzech zwięzłych kroków: utworzenia instancji Signature, ustawienia BarcodeSignOptions i wywołania sign(). Poniższy kod demonstruje każdy krok.

1. zainicjalizuj obiekt podpisu

Klasa Signature jest punktem wejścia dla wszystkich operacji przetwarzania dokumentów w GroupDocs.Signature.

import com.groupdocs.signature.Signature;

String sourceFilePath = "YOUR_DOCUMENT_DIRECTORY/document.pdf";
final Signature signature = new Signature(sourceFilePath);

Dlaczego to ważne: Obiekt Signature abstrahuje obsługę plików, strumieniując duże PDF‑y efektywnie, bez ładowania całego pliku do pamięci.

2. skonfiguruj opcje kodu kreskowego

BarcodeSignOptions pozwala określić typ kodu, dane do zakodowania, pozycję i wymiary.

import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

BarcodeSignOptions gs1DotCodeOptions = new BarcodeSignOptions("(01)04912345123459(15)970331(30)128(10)ABC123", BarcodeTypes.GS1DotCode);
gs1DotCodeOptions.setLeft(100); // Set barcode position
gs1DotCodeOptions.setTop(100);
gs1DotCodeOptions.setHeight(150);
gs1DotCodeOptions.setWidth(200);

Kluczowe informacje:

  • Zakodowany ciąg musi stosować identyfikatory aplikacji GS1 (AI), np. (01) dla GTIN, (15) dla daty ważności itp.
  • setLeft() i setTop() używają punktów (72 pt = 1 in).
  • Minimalny zalecany rozmiar dla pewnego skanowania to 108 pt × 108 pt (1,5 in × 1,5 in).
3. podpisz dokument

Dodaj skonfigurowane opcje do listy (można łączyć wiele typów podpisów) i wywołaj sign().

import java.util.ArrayList;
import java.util.List;

List<com.groupdocs.signature.options.sign.SignOptions> listOptions = new ArrayList<>();
listOptions.add(gs1DotCodeOptions);
signature.sign("YOUR_OUTPUT_DIRECTORY/signed_document_with_gs1dotcode.pdf", listOptions);

Uwaga o wydajności: Ponowne użycie jednej instancji Signature przy przetwarzaniu wsadowym zmniejsza narzut tworzenia obiektów i zwiększa przepustowość.

Funkcja 2: zapisz zawartość podpisu kodu jako plik

Jak wyodrębnić obraz kodu kreskowego z podpisanego PDF‑a w Javie?

BarcodeSignature reprezentuje obiekt podpisu kodu kreskowego wyodrębniony z podpisanego dokumentu, udostępniając dostęp do danych i obrazu.

Utwórz instancję BarcodeSignature (lub pobierz ją za pomocą search()), odczytaj zakodowany obraz w formacie Base64 przez getContent(), zdekoduj i zapisz bajty do pliku PNG. Otrzymasz samodzielny obraz, który możesz wyświetlić w UI lub wysłać do drukarki etykiet.

1. symulacja tworzenia podpisu kodu kreskowego

W rzeczywistych scenariuszach uzyskujesz BarcodeSignature z wyniku wyszukiwania; tutaj tworzymy go ręcznie w celach demonstracyjnych.

import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import java.io.FileOutputStream;

String base64String = "SampleBase64EncodedData";
BarcodeSignature barcodeSignature = new BarcodeSignature(base64String);
2. zapisz zawartość do pliku

Zdekoduj ciąg Base64 i zapisz otrzymane bajty na dysk, używając bloku try‑with‑resources.

int imageNumber = 1;
String formatExtension = ".png";  // Assume PNG format

try (FileOutputStream outputStream = new FileOutputStream("YOUR_OUTPUT_DIRECTORY/barcode_image" + imageNumber + formatExtension)) {
    byte[] byteArray = barcodeSignature.getContent();
    if (byteArray != null) {
        outputStream.write(byteArray);
    }
}

Pułapka: getContent() może zwrócić null, jeśli podpis został utworzony bez osadzenia obrazu. Zawsze sprawdzaj null przed zapisem.

Typowe problemy i rozwiązania

Problem: kod nie skanuje się

Objawy: Kod wygląda poprawnie w przeglądarce PDF, ale skanery zgłaszają błędy.

Rozwiązania:

  • Zwiększ rozmiar kodu przynajmniej do 108 pt × 108 pt.
  • Upewnij się, że rozdzielczość drukarki wynosi ≥ 300 dpi.
  • Zweryfikuj, czy ciąg danych GS1 spełnia poprawną składnię AI; brak nawiasu powoduje błąd skanera.

Problem: OutOfMemoryError przy dużych PDF‑ach

Objawy: Przetwarzanie dokumentów większych niż 50 MB powoduje awarię pamięci.

Rozwiązania:

  • Uruchom JVM z większym przydziałem pamięci, np. -Xmx2g.
  • Przetwarzaj dokumenty w mniejszych partiach.
  • Jawnie zwalniaj obiekty Signature: signature.dispose() po zakończeniu pracy z każdym plikiem.

Problem: kod jest rozmyty

Objawy: Wygenerowany kod wygląda pikselowo w wyjściowym PDF‑ie.

Rozwiązania:

  • Użyj większych wymiarów; biblioteka renderuje grafikę wektorową, ale skalowanie w dół po generacji wprowadza artefakty.
  • Unikaj konwersji raster‑do‑wektor; pozwól GroupDocs renderować bezpośrednio z definicji wektorowej.

Problem: wyjątki licencyjne

Objawy: Błędy typu „License not found” lub „Trial limitations exceeded”.

Rozwiązania:

  • Umieść plik licencyjny w katalogu root classpath (src/main/resources).
  • Wywołaj License.setLicense("GroupDocs.Signature.lic") przed jakąkolwiek instancją Signature.
  • Dla licencji tymczasowych sprawdź datę wygaśnięcia (30 dni od wydania).

Kiedy stosować to podejście

Dobre przypadki użycia

  • Śledzenie łańcucha dostaw – osadzaj identyfikatory produktów, numery partii i daty ważności bezpośrednio na dokumentach transportowych.
  • Automatyczne drukowanie etykiet – generuj kody na bieżąco dla każdego faktury PDF.
  • Branże regulowane – standardy GS1 są obowiązkowe w wielu sektorach detalicznych i opieki zdrowotnej.

Kiedy rozważyć alternatywy

  • Jeśli potrzebna jest wyłącznie integralność kryptograficzna, lepszy będzie standardowy podpis PKI.
  • Dla prostych adnotacji wizualnych wystarczy podpis tekstowy lub znak graficzny.
  • Gdy rozmiar dokumentu jest krytyczny, unikaj wysokiej rozdzielczości obrazów kodów; zamiast tego użyj kodów QR, które mogą być mniejsze przy podobnej gęstości danych.

Najlepsze praktyki bezpieczeństwa

Walidacja danych

Sanitizuj wszelkie dane podawane przez użytkownika przed zakodowaniem ich w kodzie kreskowym. Nieprawidłowe ciągi GS1 mogą powodować błędy skanowania lub, w najgorszym wypadku, wywołać przepełnienie bufora w starszym oprogramowaniu skanerów.

Kontrola dostępu

Wdroż role‑based access control (RBAC), aby tylko upoważnieni użytkownicy mogli wywoływać API podpisu. Przechowuj plik licencyjny w bezpiecznym miejscu i ogranicz uprawnienia systemu plików.

Logowanie zdarzeń

Loguj każdą operację podpisu, podając identyfikator użytkownika, znacznik czasu, ścieżkę pliku źródłowego oraz dokładny ładunek GS1. Przykładowy fragment logowania:

// Simple logging example (use a proper logging framework in production)
System.out.println("Document signed by: " + userId + " at " + new Date());
System.out.println("Barcode data: " + barcodeData);

Wykrywanie manipulacji

Połącz podpis kodu kreskowego z kryptograficznym podpisem cyfrowym. Kod zapewnia dane odczytywalne maszynowo, a podpis cyfrowy gwarantuje integralność i nieodrzucalność.

Praktyczne zastosowania

1. zarządzanie łańcuchem dostaw

Każda listwa przewozowa otrzymuje kod GS1DotCode zawierający GTIN, partię i miejsce docelowe. Skanery na poszczególnych punktach automatycznie aktualizują system ERP, redukując ręczne wprowadzanie danych o 98 %.

2. kontrola inwentaryzacji

Po przyjęciu towaru, PDF potwierdzający przyjęcie jest podpisany kodem zawierającym numer zamówienia i ilość sztuk. Pracownicy magazynu skanują kod, a baza danych inwentaryzacji aktualizuje się w czasie rzeczywistym.

3. punkt sprzedaży detalicznej

Faktury wydrukowane z kodem pozwalają kasjerom obsługiwać zwroty poprzez skanowanie faktury zamiast ręcznego wprowadzania numeru transakcji, skracając średni czas obsługi o 30 sekund na zwrot.

4. dokumentacja medyczna

Recepty podpisane kodem GS1DotCode zawierają identyfikator pacjenta, kod leku i dawkowanie. Apteki skanują kod, eliminując błędy transkrypcji prowadzące do niepożądanych zdarzeń lekowych.

Rozważania wydajnościowe

Zarządzanie pamięcią

GroupDocs.Signature strumieniuje dane PDF, ale nadal warto zamykać zasoby jak najszybciej:

try (Signature signature = new Signature(sourceFilePath)) {
    // Do your signing operations here
} // Signature automatically disposed here

Użycie try‑with‑resources zapewnia zwolnienie uchwytów plików nawet w przypadku wystąpienia wyjątku.

Wskazówki przy przetwarzaniu wsadowym

  • Ponownie używaj tej samej instancji BarcodeSignOptions, gdy ładunek jest identyczny w wielu dokumentach.
  • Równolegle podpisuj przy pomocy ExecutorService w obciążeniach CPU‑intensywnych; typowy serwer 8‑rdzeniowy może podpisać ≈ 150 PDF‑ów na minutę, gdy każdy plik ma mniej niż 5 MB.
  • Ogranicz wywołania weryfikacji licencji zewnętrznej, aby nie przekroczyć limitów throttlingu.

Optymalizacja formatu pliku

  • Preferuj PDF/A‑1b do archiwizacji; kompresuje strumienie i zmniejsza rozmiar pliku nawet o 40 %.
  • Trzymaj wymiary kodu nie większe niż konieczne; kod 1,5 in × 1,5 in dodaje około 15 KB do PDF‑a o wielkości 2 MB.

Podsumowanie

Masz teraz kompletny, gotowy do produkcji przepływ pracy, który dodaje kody GS1DotCode jako podpisy do plików PDF w Javie, wyodrębnia te kody jako obrazy i integruje proces z szerszymi pipeline’ami zarządzania dokumentami. Pamiętaj, aby:

  1. Walidować ładunki GS1 przed ich kodowaniem.
  2. Dobierać wymiary kodu tak, aby zapewnić niezawodne skanowanie przy jednoczesnym zachowaniu wymagań layoutu.
  3. Łączyć podpisy kodów z podpisami kryptograficznymi dla pełnego pokrycia bezpieczeństwa.

Kolejne kroki: zapoznaj się z innymi typami podpisów oferowanymi przez GroupDocs.Signature — kodami QR, znakami tekstowymi i certyfikatami cyfrowymi, które wszystkie korzystają ze spójnego interfejsu API.

Najczęściej zadawane pytania

P: Co to jest GS1DotCode i czym różni się od kodów QR?
O: GS1DotCode to kompaktowa macierz 2‑D z kropek, która przechowuje do 3 116 znaków w mniejszej przestrzeni niż kody QR, co czyni ją idealną dla małych etykiet i szybkiego druku.

P: Czy mogę używać wersji próbnej w środowisku produkcyjnym?
O: Wersja próbna jest ograniczona do oceny i dodaje znak wodny do plików wyjściowych. Produkcyjne wdrożenia wymagają licencji zakupionej lub tymczasowej (30 dni).

P: Jak umieścić kod na konkretnej stronie?
O: Ustaw setPageNumber(pageIndex) w obiekcie BarcodeSignOptions, a następnie dopasuj setLeft() i setTop() w celu precyzyjnego pozycjonowania.

P: Czy GroupDocs.Signature obsługuje PDF‑y zabezpieczone hasłem?
O: Tak. Podaj hasło przy tworzeniu obiektu Signature: new Signature("file.pdf", "password").

P: Jak zweryfikować, że podpis kodu został dodany prawidłowo?
Signature.search() przeszukuje dokument pod kątem podpisów i zwraca kolekcję pasujących obiektów. Użyj Signature.search() z BarcodeSearchOptions. Zwrócone obiekty BarcodeSignature zawierają zakodowane dane i obraz do weryfikacji.

P: Jaki jest minimalny rozmiar kodu dla pewnego skanowania?
O: Celuj w co najmniej 108 pt × 108 pt (1,5 in × 1,5 in). Większe rozmiary zwiększają czytelność, szczególnie przy drukarkach o niskiej rozdzielczości.

P: Czy mogę jednocześnie podpisywać wiele PDF‑ów?
O: Tak. Utwórz pulę wątków i dla każdego wątku zainicjuj osobny obiekt Signature; biblioteka jest bezpieczna wątkowo, pod warunkiem, że każdy wątek pracuje na własnym dokumencie.

P: Czy istnieje limit liczby kodów, które mogę osadzić w jednym PDF‑ie?
O: Nie ma sztywnego limitu, ale każdy kod dodaje około 15 KB danych. W PDF‑ach powyżej 100 MB rozważ przetwarzanie wsadowe, aby kontrolować zużycie pamięci.

P: Czy biblioteka działa na platformach innych niż Windows?
O: GroupDocs.Signature for Java jest platformowo niezależna i działa na każdym systemie operacyjnym z kompatybilnym JRE, w tym Linux i macOS.

Ostatnia aktualizacja: 2026-08-25
Testowane z: GroupDocs.Signature 23.12 for Java
Autor: GroupDocs

Powiązane samouczki