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

Введение

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

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

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

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

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

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

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

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

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

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

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

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

Настройка Maven

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

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

Настройка Gradle

Или включите её в 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‑данные, что делает их идеальными для автоматической проверки.

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

Как искать страницы со штрих‑кодами в Java?

Signature — основной класс, представляющий документ для обработки. Загрузите ваш документ с помощью new Signature("file.pdf"), BarcodeSearchOptions определяет параметры поиска штрих‑кодов, настройте его для выбора нужных страниц и вызовите signature.search(options). Метод search выполняет операцию поиска с использованием указанных параметров. Движок возвращает список объектов BarcodeSignature, содержащих номера страниц, декодированный текст и геометрические координаты — всё в одном вызове. Такой одношаговый подход устраняет необходимость отдельного извлечения изображений или пользовательской логики декодирования.

Теперь, когда вы понимаете общий процесс, давайте погрузимся в три основные функции, которые вы реализуете.

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

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

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

Якорь определения

Signature представляет документ и предоставляет возможности подписки на события.

Implementation

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 %.

Якорь определения

PagesSetup указывает, какие страницы включаются в операцию поиска.

Implementation

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");

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

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

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

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

Якорь определения

BarcodeSignature представляет обнаруженный штрих‑код и содержит его свойства, такие как номер страницы и декодированный текст.

Implementation

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);

Выбор конкретных страниц значительно сокращает время обработки; PDF из 150 страниц уменьшается с ~4 секунд до <1 секунды, если ограничить поиск двумя страницами.

Проблема 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. конкретным страницам?
О: Сканирование каждой страницы PDF из 50 страниц может занять 3–5 секунд. Ограничение первой + последней страницами обычно завершает поиск менее чем за 1 секунду.

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

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

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

Связанные руководства

• Как добавить штрих‑код в PDF на Java с помощью GroupDocs.Signature
• Как проверить подписи штрих‑кодов в Java с помощью GroupDocs.Signature
• GroupDocs Signature Java подписка на события — отслеживание проверки в реальном времени