Штрих-код
Примечание
Доступность функции зависит от состава и условий поставки, включая подключённые компоненты трансформации и конвертеры.
Citeck позволяет формировать PDF-документ со встроенным штрих-кодом — это упрощает идентификацию и отслеживание документов в рамках бизнес-процессов. Функционал реализован в микросервисе ecos-transformations: изображение генерируется через ZXing, а компонент трансформации barcode накладывает его на PDF через iText.
На основе атрибута записи генерируется изображение штрих-кода, которое можно:
Отобразить в карточке;
Открыть для печати;
Наложить на PDF-документ.
Процесс формирования PDF-документа со штрих-кодом
Исходный контент загружается пользователем или генерируется из шаблона.
Если исходник не PDF, выполняется конвертация в PDF. Для DOC/DOCX необходим доступный конвертер офисных форматов, например OnlyOffice.
Компонент
barcodeполучает данные штрих-кода из указанной сущности или сущности входного контента и добавляет его в PDF. Без сущности-источника компонент завершится ошибкой.Результат скачивается или сохраняется согласно настройке цели трансформации (
output). Запись в контент документа или дочерней сущности настраивается отдельно.
По умолчанию штрих-код размещается внизу по центру на всех страницах. Пример:
Настройка штрих-кода
Настройка осуществляется через аспект, который добавляется к требуемому типу:
Аспект: Имеет штрих-код (barcode)
В настройках аспекта для типа есть три поля:
format— формат штрих-кода, по умолчаниюCODE_128.attribute— атрибут с кодируемым содержимым, по умолчанию_docNum.textAttribute— атрибут подписи под изображением. Если он не задан, подпись берётся из атрибута кодируемого содержимого.
Аспект задаёт способ получения данных. Автоматическое создание и сохранение PDF требует отдельного действия или настройки процесса.
Добавление штрих-кода в PDF-документ
Для добавления штрих-кода в PDF можно воспользоваться возможностями трансформации содержимого.
Пример настройки UI-действия transform для наложения штрих-кода на существующий PDF:
---
id: download-with-barcode
name: Скачать со штрих-кодом
type: transform
config:
transformations:
- type: barcode
Если содержимое документа нужно предварительно конвертировать в PDF (например, из doc/docx), добавьте трансформер convert перед barcode:
---
id: download-with-barcode-converted
name: Скачать PDF со штрих-кодом
type: transform
config:
transformations:
- type: convert
config:
toMimeType: application/pdf
- type: barcode
Эти примеры описывают UI-действия; подготовка источника и цели зависит от клиентского компонента. Полная серверная конфигурация включает input, transformations и output — см. трансформации содержимого.
Все параметры компонента barcode имеют значения по умолчанию. Для изменения положения и выбора страниц можно добавить config к шагу трансформации:
- type: barcode
config:
layout: BOTTOM_CENTER
pages: FIRST
altText: true
layout поддерживает TOP_LEFT, TOP_CENTER, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER и BOTTOM_RIGHT. Для pages доступны ALL (по умолчанию), FIRST и LAST. Также можно задать entityRef, barcodeAttribute, размеры, отступы, масштаб и цвета; подробнее см. конфигурацию трансформаций.
В настроенной карточке действие может отображаться, например, как Скачать PDF (со штрих-кодом). Его наличие и название зависят от конфигурации действий:
Подробнее о трансформациях — в трансформации содержимого.
REST API
Для загрузки штрих-кода в виде изображения можно воспользоваться следующим API:
GET /gateway/transformations/api/barcode/image?content=123
Путь внутри микросервиса — /api/barcode/image; префикс /gateway/transformations определяется маршрутизацией платформы.
Доступны два режима:
Без
entityRefиспользуютсяcontentиbarcodeFormat.При переданном
entityRefсодержимое и формат берутся из записи и конфигурации её аспекта.attributeможет переопределить атрибут содержимого;contentиbarcodeFormatв этом режиме не используются.
Для прямой генерации по content полностью опускайте entityRef, а не передавайте пустое значение. Значения query-параметров URL-кодируйте.
Параметры:
Параметр |
Тип |
Описание |
|---|---|---|
barcodeFormat |
String? |
Формат штрих-кода при генерации по |
imageFormat |
String? |
Формат изображения. Текущая реализация поддерживает только |
width |
Int? |
Ширина матрицы штрих-кода в пикселях. По умолчанию |
height |
Int? |
Высота матрицы штрих-кода в пикселях. По умолчанию |
margin |
Int? |
Отступ кодировщика. По умолчанию |
altText |
Boolean? |
Рендерить текстовое содержимое штрих-кода. По умолчанию — Да |
content |
String? |
Кодируемое содержимое. Используется только при отсутствии |
entityRef |
String? |
Ссылка на сущность для получения данных. При наличии имеет приоритет над |
attribute |
String? |
Атрибут кодируемого содержимого в режиме |
download |
Boolean? |
При |
Boolean? |
При |
|
outputType |
String? |
При выключенном
print точное значение json возвращает JSON с полем data (base64 изображения).При другом или отсутствующем значении возвращается изображение.
outputType=pdf сам по себе не включает PDF; для него требуется print=true. |
Значения barcodeFormat и imageFormat приводятся к верхнему регистру, но неизвестный формат вызывает ошибку. Значение outputType=json проверяется с учётом регистра.
Для двумерных штрих-кодов при нулевых ширине и высоте используется матрица 60 × 60. Если задана только одна сторона, вторая принимается равной ей. Текстовая подпись может увеличить размер итогового PNG.
При сочетании download с print или JSON учитывайте, что текущий контроллер формирует имя вложения до выбора формата ответа и дописывает расширение по формату изображения. Соответствующее PDF/JSON-расширение имени не гарантируется.
Пример получения изображения по записи:
GET /gateway/transformations/api/barcode/image?entityRef=emodel/anysrc@123&attribute=_docNum
Хотя HTTP-параметры необязательны в сигнатуре, для генерации нужны корректные данные. Допустимая длина и алфавит содержимого зависят от выбранного формата.
Поддерживаемые форматы штрих-кода:
AZTEC
CODABAR
CODE_39
CODE_93
CODE_128
DATA_MATRIX
EAN_8
EAN_13
ITF
PDF_417
QR_CODE
UPC_A
UPC_E