# Штрихкоды

Штрихкоды используются для идентификации объектов системы. Каждый сформированный штрихкод хранится в таблице `BS_BarCode` и связан с объектом через поле `gidRef`.

Для большинства сценариев достаточно использовать один из уже зарегистрированных стандартных типов штрихкодов, например `CODE128`, `EAN-13` или `CODE39`. Собственный тип требуется только в том случае, если стандартных типов недостаточно.

Для автоматического формирования штрихкодов необходимо выбрать тип штрихкода, создать настройку `Bs_BarCodeObjectType` с маской формирования и подключить ее к требуемому классу. После этого для новых объектов штрихкоды формируются автоматически, а для ранее созданных объектов можно использовать операцию **Генерация ШК**.

## Общая схема работы

Настройка выполняется в следующем порядке:

1. Выберите существующий тип штрихкода. Если стандартных типов недостаточно, разработчик может зарегистрировать собственный тип.
2. Создайте тип объекта для штрихкода `Bs_BarCodeObjectType` и задайте маску формирования.
3. Настройте использование `Bs_BarCodeObjectType` для требуемого класса.
4. При необходимости сформируйте штрихкоды для ранее созданных объектов операцией **Генерация ШК**.

В механизме используются два связанных, но разных понятия:

- **тип штрихкода** — тип объекта класса `Bs_BarCode`, который определяет используемую последовательность и длину формируемого значения;
- **тип объекта для штрихкода** — запись `Bs_BarCodeObjectType`, которая связывает тип штрихкода с маской формирования.

Настройка класса определяет, для каких объектов применяется выбранный `Bs_BarCodeObjectType`.

При создании нового объекта система:

1. Определяет настройку формирования для класса и, если используется настройка в разрезе типа объекта, для его типа.
2. Получает следующее значение последовательности.
3. Применяет заданную маску.
4. Создает запись `BS_BarCode`.
5. Сохраняет связь с объектом в `gidRef`.

## Настройка в интерфейсе

### Настройка типа объекта для штрихкода

`Bs_BarCodeObjectType` связывает тип штрихкода с маской формирования.

В выборке `Bs_BarCodeObjectType` (**Тип объекта для ШК**) создайте новую запись и укажите:

- тип штрихкода;
- маску формирования.

Для типового сценария выберите один из уже зарегистрированных стандартных типов штрихкода. Создавать собственный тип для этого не требуется.

Счетчик в маске обозначается как `[counter]`. До и после счетчика можно указать произвольный текст.

Например:

- длина штрихкода — `10`;
- следующее значение последовательности — `12`;
- маска — `001-[counter]`.

Будет сформирован штрихкод:

<!-- Начало кода -->
```text
001-000012
```
<!-- Конец кода -->

Одна запись `Bs_BarCodeObjectType` используется для объектов, к которым применяется одинаковое правило формирования. Создавать отдельную запись для каждого сформированного штрихкода не требуется.

Если требуется другое сочетание типа штрихкода и маски, создайте отдельный `Bs_BarCodeObjectType`.

### Настройка формирования для класса

После создания типа объекта для штрихкода настройте, для объектов какого класса он должен использоваться.

Для настройки:

1. В приложении **Настройка системы** откройте `Сущности > Классы`.
2. Откройте карточку класса, для объектов которого требуется формировать штрихкоды.
3. Перейдите на вкладку **Настройка штрихкодов**.
4. Выполните операцию **Создать настройку формирования штрихкодов**. Откроется список **Настройка штрихкодов**.
5. Создайте запись.
6. В поле **Тип объекта для штрихкода** укажите ранее созданный `Bs_BarCodeObjectType`.
7. Если для разных типов объектов класса должны применяться разные правила формирования, установите признак **Настройка в разрезе типа объекта** и укажите типы объектов, для которых применяется текущая настройка.
8. Установите признак **Формировать штрихкоды для объектов класса**.
9. В карточке класса в группе операций **Дополнительно** выполните операцию **Сбросить Shared Cache по классу**.
10. Выполните операцию **Сбросить Shared Cache по классу** также для класса `Btk_Class`.

![](/img/Img28\(barcodegeneration\).jpg)

После настройки при создании новых объектов класса штрихкоды формируются автоматически в соответствии с заданными правилами.

Если используется **Настройка в разрезе типа объекта**, правило формирования определяется с учетом типа создаваемого объекта.

<!-- Начало кода -->
```{attention}
Если признак **Формировать штрихкоды для объектов класса** не установлен, при создании нового объекта штрихкод не формируется, даже если для класса настроены правила формирования.

Если признак **Формировать штрихкоды для объектов класса** установлен, но настройки формирования отсутствуют, при создании объекта возникает ошибка **У класса отсутствуют настройки формирования**.
```
<!-- Конец кода -->

### Генерация штрихкодов для существующих объектов

Операция **Генерация ШК** используется для формирования штрихкодов для ранее созданных объектов.

Путь: `Настройка системы > Сущности > Классы > карточка класса > Настройка штрихкодов`.

Операция использует настройки формирования, заданные для выбранного класса, и формирует штрихкод конкретного настроенного типа для объектов, у которых отсутствует штрихкод этого типа.

Наличие у объекта штрихкода другого типа не препятствует формированию дополнительного штрихкода.

Если используется **Настройка в разрезе типа объекта**, при формировании учитывается правило, заданное для соответствующего типа объекта.

При выполнении операции автоматически устанавливается признак **Формировать штрихкоды для объектов класса**.

<!-- Начало кода -->
```{attention}
Если для класса отсутствуют настройки формирования, при выполнении операции **Генерация ШК** возникает ошибка **У класса отсутствуют настройки формирования**.
```
<!-- Конец кода -->

### Просмотр штрихкодов объекта

Просмотреть зарегистрированные для объекта штрихкоды можно с помощью операции **Информация об объекте**.

![](/img/Img30\(objectinformation\).jpg)

Если для объекта зарегистрирован один штрихкод, его значение отображается в поле **Штрихкод**.

![](/img/Img31\(informationoutput\).jpg)

Если для одного объекта сформировано несколько штрихкодов, например разных типов, в поле **Штрихкод** отображается значение **Список…**.

Для просмотра всех штрихкодов нажмите кнопку в поле **Штрихкод**.

## Настройка для разработчика

### Создание собственного типа штрихкода

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

Тип штрихкода регистрируется как тип объекта класса `Bs_BarCode`. Для него задаются последовательность, используемая для счетчика, и длина формируемого значения.

Последовательность задается в `odm.xml` внутри тега `<seqs>`, расположенного в `<dbData>`.

Пример:

<!-- Начало кода -->
```xml
<seq name="bs_barcode_seq$ean13" version="1">
    create sequence if not exists bs_barcode_seq$ean13;
</seq>
```
<!-- Конец кода -->

Для типа задаются объектные характеристики:

- `nLength` — длина формируемого штрихкода;
- `SeqName` — системное имя последовательности, используемой для счетчика.

Пример регистрации в коде:

<!-- Начало кода -->
```scala
idv = Btk_ObjectTypeApi().register(
  spCode = "CODE128A",
  spCaption = "Code 128 A",
  spShortCaption = "Code 128 A",
  idpRefClass = idClass
)

rop = Btk_ObjectTypeApi().load(idv)

jObjAttrs = Btk_ObjectTypeApi().parseObjAttrs(rop).asJObject
jObjAttrs.set("nLength", 13.nn)
jObjAttrs.set("SeqName", "bs_barcode_seq$code128a".ns)
```
<!-- Конец кода -->

Параметры:

- `spCode` — код типа объекта;
- `spCaption` — наименование;
- `spShortCaption` — короткое наименование;
- `idpRefClass` — класс типа объекта.

### Регистрация типа объекта для штрихкода в коде

Тип объекта для штрихкода можно зарегистрировать программно методом `Bs_BarCodeObjectTypeApi().register()`.

Пример:

<!-- Начало кода -->
```scala
Bs_BarCodeObjectTypeApi().register(
  sSystemName = "Mnf_ShiftTask",
  sCaption = "ШК для сменного задания",
  sDescription = None.ns,
  idBarCodeType = Bs_BarCodeApi().findByMnemoCodeBarCodeType("CODE128"),
  spMask = "[counter]"
)
```
<!-- Конец кода -->

Параметры:

- `sSystemName` — системное имя;
- `sCaption` — наименование;
- `sDescription` — описание;
- `idBarCodeType` — используемый тип штрихкода;
- `spMask` — маска формирования.

### Настройка в ODM

В метаданных класса свойство `barCodeObjectTypeName` тега `Class` используется для указания системного имени `Bs_BarCodeObjectType`.

### Регистрация настройки класса в коде

Настройку формирования для класса можно зарегистрировать программно методом `Bs_ClassBarcodeSettingApi().registerSetting()`.

Пример:

<!-- Начало кода -->
```scala
Bs_ClassBarcodeSettingApi().registerSetting(
  spClass = "Rpltst_Test1",
  bpCreateBarcode = 1.nn,
  spBarCodeObjectType = "Bs_Goods",
  bpSettingByObjectType = 1.nn,
  sapObjectType = List("Wf_Doc", "test3")
)
```
<!-- Конец кода -->

Параметры:

- `spClass` — системное имя класса;
- `bpCreateBarcode` — значение признака **Формировать штрихкоды для объектов класса**;
- `spBarCodeObjectType` — системное имя типа объекта для штрихкода из `Bs_BarCodeObjectType`;
- `bpSettingByObjectType` — значение признака **Настройка в разрезе типа объекта**;
- `sapObjectType` — список системных имен типов объектов, для которых применяется настройка.

Прием считанных значений от сканеров описан на странице [Работа со сканерами](030_работа_со_сканерами.md).