Поиск страниц с определёнными штрих‑кодами в документах с помощью Java

Введение

Когда‑то вам приходилось тратить часы на ручную проверку подписей в сотнях документов? Вы не одиноки. Будь то система управления контрактами, автоматизация обработки счетов или защита медицинских записей — ручной поиск и проверка штрих‑кодов‑подписей утомительны и подвержены ошибкам.

В этом руководстве мы покажем, как программно искать страницы с определёнными штрих‑кодами в ваших документах с помощью Java и GroupDocs.Signature. К концу вы сможете обнаруживать подписи на выбранных страницах, отслеживать процесс поиска в реальном времени и работать с различными форматами штрих‑кодов — всё это с чистым, поддерживаемым кодом.

Что вы узнаете

• Как настроить GroupDocs.Signature в Java‑проекте (≈5 минут)
• Как подписаться на события поиска для отслеживания прогресса в реальном времени
• Как настроить умные параметры поиска для целевых страниц
• Как выполнить поиск и эффективно обработать результаты

Быстрые ответы

• Какая библиотека помогает искать страницы с определёнными штрих‑кодами? GroupDocs.Signature for Java
• Типичное время настройки? Около 5 минут для добавления зависимости Maven/Gradle и лицензии
• Можно ли ограничить поиск только первой и последней страницами? Да — используйте PagesSetup для указания конкретных страниц
• Какие форматы штрих‑кодов поддерживаются? QR Code, Code128, Code39, DataMatrix, EAN/UPC и другие
• Нужна ли платная лицензия для продакшна? Полная лицензия требуется для продакшна; trial‑версия подходит для оценки

Что такое «поиск страниц с определёнными штрих‑кодами»?

Поиск страниц с определёнными штрих‑кодами означает указание движку подписи искать штрих‑коды только на тех страницах, которые вам нужны — например, на первой, последней или любой пользовательской диапазон. Такой целенаправленный подход ускоряет обработку, уменьшает потребление памяти и позволяет создавать отзывчивый UI.

Почему использовать GroupDocs.Signature для этой задачи?

GroupDocs.Signature предоставляет высокоуровневый API, который скрывает детали низкоуровневого декодирования штрих‑кодов, рендеринга страниц и работы с форматами документов. Он работает с PDF, DOCX, XLSX и многими другими форматами «из коробки», позволяя сосредоточиться на бизнес‑логике, а не на парсинге файлов.

Предварительные требования

• JDK 8+ установлен
• Maven или Gradle для управления зависимостями
• Базовое знакомство с классами, методами и обработкой исключений в Java
• Доступ к лицензии GroupDocs.Signature (trial или полная)

Настройка GroupDocs.Signature для Java

Maven Setup

Добавьте зависимость в ваш pom.xml:

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

Gradle Setup

Или включите её в build.gradle:

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

Предпочитаете ручные загрузки? Последнюю версию можно скачать напрямую со страницы загрузки GroupDocs.

Получение лицензии

• Free Trial — стартуйте сразу, без обязательств
• Temporary License — полный набор функций для оценки
• Full License — готова к продакшну, без ограничений

Проверьте установку быстрым фрагментом инициализации:

import com.groupdocs.signature.Signature;

public class SignatureSetup {
    public static void main(String[] args) {
        // Initialize the Signature instance with the document path
        Signature signature = new Signature("YOUR_DOCUMENT_PATH");
        
        System.out.println("GroupDocs.Signature for Java initialized successfully.");
    }
}

Pro tip: Замените "YOUR_DOCUMENT_PATH" реальным файлом PDF, DOCX или XLSX. Если в консоли появится сообщение об успехе, вы готовы к работе.

Понимание типов штрих‑кодов‑подписей

Штрих‑коды встраивают машинно‑читаемые данные в документ. В отличие от рукописных подписей, они могут хранить идентификаторы, метки времени, URL‑адреса или JSON‑полезные нагрузки, что делает их идеальными для автоматической верификации.

Штрих‑коды часто используют, когда требуется быстрый машинный ввод, структурированные данные или подпись с защитой от подделки.

Как искать страницы с определёнными штрих‑кодами

Разобьём реализацию на три сфокусированных функции.

Функция 1: Подписка на события поиска документа

Почему это важно

При обработке больших пакетов обратная связь в реальном времени (например, индикаторы прогресса) улучшает UX и помогает быстро обнаружить зависания.

Реализация

Signature signature = new Signature("YOUR_DOCUMENT_PATH");

signature.SearchStarted.add(new ProcessStartEventHandler() {
    public void invoke(Signature sender, ProcessStartEventArgs args) {
        System.out.println("Search process started at " + args.getStarted()
            + " with " + args.getTotalSignatures() + " total signatures to be put in document");
    }
});

signature.SearchProgress.add(new ProcessProgressEventHandler() {
    public void invoke(Signature sender, ProcessProgressEventArgs args) {
        System.out.println("Search progress. Processed " + args.getProcessedSignatures()
            + " signatures. Time spent " + args.getTicks() + " mlsec");
    }
});

signature.SearchCompleted.add(new ProcessCompleteEventHandler() {
    public void invoke(Signature sender, ProcessCompleteEventArgs args) {
        System.out.println("Search process completed at " + args.getCompleted()
            + " with " + args.getTotalSignatures() + " total signatures. Process took "
            + args.getTicks() + " mlsec");
    }
});

Эти три обработчика дают вам время начала, живой прогресс и итоговую статистику — идеально для логирования или обновления UI.

Функция 2: Настройка параметров поиска штрих‑кода для конкретных страниц

Почему важен гранулированный контроль

Сканировать каждую страницу 200‑страничного контракта тратит процессорные ресурсы зря. Поиск только первой и последней страниц может сократить время выполнения на 80 %.

Реализация

import com.groupdocs.signature.domain.enums.TextMatchType;
import com.groupdocs.signature.options.search.BarcodeSearchOptions;

BarcodeSearchOptions options = new BarcodeSearchOptions();

options.setAllPages(false); // Opt‑in selective page searching
options.setPageNumber(1);   // Starting page (optional)

import com.groupdocs.signature.options.PagesSetup;

PagesSetup pagesSetup = new PagesSetup();
pagesSetup.setFirstPage(true);   // Include first page
pagesSetup.setLastPage(true);    // Include last page
pagesSetup.setOddPages(false);   // Skip odd pages
pagesSetup.setEvenPages(false);  // Skip even pages
options.setPagesSetup(pagesSetup);

options.setMatchType(TextMatchType.Contains);
options.setText("12345");

• Match types позволяют точно настроить поиск текста (Contains, Exact, StartsWith, EndsWith).
• Настройте setAllPages и PagesSetup, чтобы искать штрих‑коды только на выбранных страницах.

Функция 3: Выполнение поиска и обработка результатов

Почему этот шаг важен

Найти штрих‑коды — это только половина задачи; необходимо обработать полученные данные (валидация, хранение, запуск рабочих процессов).

Реализация

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

try {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    System.out.println("Source document contains following signatures.");
    
    for (BarcodeSignature barcodeSignature : signatures) {
        System.out.println("Barcode signature found at page " + barcodeSignature.getPageNumber()
            + " with type " + barcodeSignature.getEncodeType() + " and text " + barcodeSignature.getText());
    }
} catch (Exception e) {
    throw new RuntimeException(e.getMessage(), e);
}

Теперь у вас есть список объектов BarcodeSignature, каждый из которых предоставляет:

• getPageNumber() — номер страницы, где находится штрих‑код
• getEncodeType() — QR, Code128 и т.д.
• getText() — декодированная полезная нагрузка
• Позицию (getLeft(), getTop()) и размер (getWidth(), getHeight())

Пример: Обрабатывать только QR‑коды на последней странице

for (BarcodeSignature barcodeSignature : signatures) {
    if (barcodeSignature.getPageNumber() == lastPageNumber 
        && barcodeSignature.getEncodeType().equals("QRCode")) {
        // Process only QR codes from the final page
        processApprovalCode(barcodeSignature.getText());
    }
}

Реальные сценарии применения

Частые проблемы и решения

Проблема 1 — Нет результатов, хотя штрих‑коды видны

// Ensure you are not limiting pages too aggressively
options.setAllPages(true);

Если штрих‑код встроен как растровое изображение, рассмотрите использование GroupDocs.Image для обнаружения на основе изображений.

Проблема 2 — Низкая производительность на больших файлах

PagesSetup pagesSetup = new PagesSetup();
pagesSetup.setLastPage(true);  // Most signatures are on the last page
pagesSetup.setFirstPage(true);
options.setPagesSetup(pagesSetup);

Поиск только целевых страниц значительно сокращает время обработки.

Проблема 3 — TextMatchType не находит ожидаемые штрих‑коды

String searchText = "12345".trim().toLowerCase();
options.setText(searchText);
options.setMatchType(TextMatchType.StartsWith); // Try a more permissive mode

Проблема 4 — Утечки памяти в длительных циклах

try (Signature signature = new Signature("document.pdf")) {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    // Process signatures
}

Блок try‑with‑resources автоматически освобождает экземпляр Signature.

Лучшие практики для продакшна

Надёжная обработка ошибок

try {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
} catch (com.groupdocs.signature.exception.GroupDocsSignatureException e) {
    logger.error("GroupDocs error: " + e.getMessage());
} catch (Exception e) {
    logger.error("Unexpected error: " + e.getMessage(), e);
}

Кеширование результатов для неизменных документов

Map<String, List<BarcodeSignature>> cache = new ConcurrentHashMap<>();

public List<BarcodeSignature> getCachedSignatures(String docId) {
    return cache.computeIfAbsent(docId, id -> performSearch(id));
}

Использование событий прогресса для UI‑обратной связи

signature.SearchProgress.add(new ProcessProgressEventHandler() {
    public void invoke(Signature sender, ProcessProgressEventArgs args) {
        int percent = (args.getProcessedSignatures() * 100) / args.getTotalSignatures();
        updateProgressBar(percent);
    }
});

Валидация полезных нагрузок штрих‑кода

for (BarcodeSignature barcodeSignature : signatures) {
    String text = barcodeSignature.getText();
    if (!text.matches("APPR-\\d{4}-\\d{3}")) {
        logger.warn("Invalid format: " + text);
        continue;
    }
    if (!validateChecksum(text)) {
        logger.error("Checksum failed for: " + text);
        flagForManualReview(document);
    }
}

Оптимизация выбора страниц в зависимости от типа документа

PagesSetup contractsSetup = new PagesSetup();
contractsSetup.setLastPage(true); // Contracts usually signed on last page
options.setPagesSetup(contractsSetup);

Фильтрация по типу штрих‑кода после поиска (если нужны только QR‑коды)

for (BarcodeSignature sig : signatures) {
    if ("QRCode".equals(sig.getEncodeType())) {
        // Process QR code
    }
}

Извлечение размеров изображения штрих‑кода (при необходимости для рендеринга)

for (BarcodeSignature sig : signatures) {
    int width = sig.getWidth();
    int height = sig.getHeight();
    // Use dimensions for overlay or thumbnail generation
}

Часто задаваемые вопросы

В: Можно ли искать несколько форматов штрих‑кодов в одном вызове?
О: Да. BarcodeSearchOptions по умолчанию ищет все поддерживаемые форматы. При необходимости отфильтруйте результаты по getEncodeType().

В: Как обрабатывать документы, содержащие как штрих‑коды, так и подписи‑изображения?
О: Выполняйте отдельные поиски — используйте BarcodeSignature.class для штрих‑кодов и ImageSignature.class для изображений, затем объединяйте результаты по необходимости.

В: Какой прирост производительности при поиске всех страниц vs. только выбранных?
О: Сканирование всех страниц 50‑страничного PDF занимает 3–5 секунд. Ограничение первой + последней страницей обычно укладывается в 1 секунду.

В: Работает ли это со сканированными PDF (растровыми изображениями)?
О: Только если штрих‑код добавлен как цифровой объект подписи. Для чисто растровых штрих‑кодов понадобится распознаватель на основе изображений (например, GroupDocs.Barcode).

В: Как проверить, что штрих‑код‑подпись не был подделан?
О: Встроьте хеш или цифровую подпись в полезную нагрузку штрих‑кода, затем пересчитайте хеш исходных данных и сравните. Для этого нужен оригинальный закрывающий ключ или сертификат.

Последнее обновление: 2026-01-29
Тестировано с: GroupDocs.Signature 23.12 for Java
Автор: GroupDocs