Дополнительные реквизиты в БСП: получить, добавить и подключить к форме

Дополнительные реквизиты и дополнительные сведения: в чём разница

Оба вида свойств описываются одним планом видов характеристик ДополнительныеРеквизитыИСведения и различаются реквизитом ЭтоДополнительноеСведение (плюс ВидСвойства — Перечисления.ВидыСвойств.ДополнительныеРеквизиты, ДополнительныеСведения, Метки). Практическая разница — в хранении и правах:

• Дополнительный реквизит — часть самого объекта. Значение лежит в табличной части ДополнительныеРеквизиты справочника или документа, пишется вместе с объектом, попадает в его историю изменений и версионирование.
• Дополнительное сведение — данные об объекте, но не сам объект. Значение хранится в независимом регистре сведений ДополнительныеСведения с измерениями Объект и Свойство. Его можно менять без записи объекта и закрывать отдельными правами.

Отсюда следуют ограничения БСП, зашитые в код: УстановитьСвойстваУОбъекта() работает только с дополнительными реквизитами и при попытке передать сведение выбрасывает исключение КатегорияОшибки.ОшибкаКонфигурации. А доступность самих видов проверяют функции ИспользоватьДопРеквизиты() (у метаданных владельца есть табличная часть ДополнительныеРеквизиты) и ИспользоватьДопСведения() (тип владельца входит в параметр общей команды ДополнительныеСведенияКоманднаяПанель).

Где хранятся дополнительные реквизиты и их значения

Полная карта объектов метаданных подсистемы «Свойства» — четыре сущности:

• ПланВидовХарактеристик.ДополнительныеРеквизитыИСведения — описание свойства: имя, заголовок, ТипЗначения, ИдентификаторДляФормул, НаборСвойств.
• Справочник.НаборыДополнительныхРеквизитовИСведений — наборы; их табличные части ДополнительныеРеквизиты и ДополнительныеСведения определяют, какие свойства доступны объекту. Предопределённые элементы именуются по полному имени метаданных с заменой точки на подчёркивание: Справочник_Номенклатура.
• <Объект>.ДополнительныеРеквизиты — табличная часть со значениями (колонки Свойство, Значение, ТекстоваяСтрока) и РегистрСведений.ДополнительныеСведения — значения сведений.
• Справочник.ЗначенияСвойствОбъектов и Справочник.ЗначенияСвойствОбъектовИерархия — списки допустимых значений для свойств со ссылочным типом; владелец элемента — само свойство.

Колонка ТекстоваяСтрока — не декоративная: БСП кладёт туда строковое значение длиннее 1024 символов, а в Значение остаётся усечённая версия. Читая табличную часть напрямую запросом, длинные строки вы получите обрезанными — ЗначенияСвойств() подменяет их содержимым ТекстоваяСтрока автоматически.

Как программно получить дополнительные реквизиты объекта

Основная функция чтения — ЗначенияСвойств(). Принимает ссылку или массив ссылок одного типа, умеет фильтровать по видам свойств и по списку конкретных свойств (ссылками или именами):

// Все дополнительные реквизиты и сведения одного объекта
Значения = УправлениеСвойствами.ЗначенияСвойств(НоменклатураСсылка);

Для Каждого Строка Из Значения Цикл
    Сообщить(Строка.ИмяСвойства + ": " + Строка.Представление);
КонецЦикла;

// Только дополнительные реквизиты и только нужные свойства — по именам
ИменаСвойств = Новый Массив;
ИменаСвойств.Добавить("СрокГодностиДней");
ИменаСвойств.Добавить("СтранаПроисхождения");

Значения = УправлениеСвойствами.ЗначенияСвойств(
    МассивНоменклатуры, Истина, Ложь, ИменаСвойств);

Когда нужно ровно одно значение, используйте ЗначениеСвойства() — обёртку над ЗначенияСвойств(). Если заполнен КодЯзыка, вернётся не значение, а его представление на этом языке:

СрокГодности = УправлениеСвойствами.ЗначениеСвойства(НоменклатураСсылка, "СрокГодностиДней");

// По ссылке на свойство и с представлением на английском
Представление = УправлениеСвойствами.ЗначениеСвойства(НоменклатураСсылка, СвойствоСсылка, "en");

// Список свойств, доступных объекту, и проверка наличия конкретного
МассивСвойств = УправлениеСвойствами.СвойстваОбъекта(НоменклатураСсылка, Истина, Ложь);
Если УправлениеСвойствами.ПроверитьСвойствоУОбъекта(НоменклатураСсылка, СвойствоСсылка) Тогда
    // ...
КонецЕсли;

Важная деталь ЗначенияСвойств(): дополнительные сведения читаются только при праве «Чтение» на регистр ДополнительныеСведения, а вся функция возвращает пустую таблицу, если СвойстваДоступны() = Ложь (нет права чтения справочника наборов). Пустой результат у пользователя с ограниченными правами — это не баг, а RLS.

Как программно добавить дополнительный реквизит

Свойство создаётся функцией ДобавитьСвойство(). Она сама находит набор свойств, проверяет уникальность наименования, имени и идентификатора для формул, создаёт элемент плана видов характеристик и добавляет его в табличную часть набора — всё в одной транзакции.

Параметры = УправлениеСвойствами.ПараметрыДобавленияСвойства();
Параметры.Наименование            = "Срок годности, дней";
Параметры.ТипЗначения             = Новый ОписаниеТипов("Число");
Параметры.Имя                     = "СрокГодностиДней";
Параметры.ИдентификаторДляФормул  = "СрокГодностиДней";
Параметры.Подсказка               = "Количество дней хранения";
Параметры.МногострочноеПолеВвода  = Ложь;

Свойство = УправлениеСвойствами.ДобавитьСвойство(
    Метаданные.Справочники.Номенклатура,
    Параметры,
    Перечисления.ВидыСвойств.ДополнительныеРеквизиты);

Структура ПараметрыДобавленияСвойства() содержит поля: Наименование, ТипЗначения, Имя, Комментарий, ЗаголовокФормыЗначения, ЗаголовокФормыВыбораЗначения, ИдентификаторДляФормул, МногострочноеПолеВвода, Подсказка, Тип (устаревший синоним ТипЗначения) и ЦветСвойства. Обязательны Наименование и ТипЗначения; для вида Перечисления.ВидыСвойств.Метки обязателен ещё и ЦветСвойства — иначе вызов упадёт с перечислением незаполненных параметров.

Если Имя не задано, БСП соберёт его из наименования (слова склеиваются с заглавной буквы, имя, начинающееся с цифры, получает префикс _, а при коллизии — суффикс из GUID). Третий параметр Булево оставлен для совместимости: Истина означает дополнительное сведение, Ложь и Неопределено — дополнительный реквизит.

Владельцем можно передать не только объект метаданных, но и строку («Справочник.Номенклатура» или имя набора «Справочник_Номенклатура»), и готовую ссылку СправочникСсылка.НаборыДополнительныхРеквизитовИСведений. Если набор не найден, вы получите исключение «Переданный объект не подключен к подсистеме Свойства» — значит, объект не зарегистрирован в УправлениеСвойствамиПереопределяемый.

Как добавить значение свойства программно

Для свойств с типом СправочникСсылка.ЗначенияСвойствОбъектов или СправочникСсылка.ЗначенияСвойствОбъектовИерархия список допустимых значений наполняется функцией ДобавитьЗначениеСвойства(). Владельца можно передать ссылкой на свойство или его уникальным именем — тогда БСП найдёт свойство запросом по реквизиту Имя:

ПараметрыСвойства = УправлениеСвойствами.ПараметрыДобавленияСвойства();
ПараметрыСвойства.Наименование = "Признак упаковки";
ПараметрыСвойства.Имя          = "ПризнакУпаковки";
ПараметрыСвойства.ТипЗначения  = Новый ОписаниеТипов("СправочникСсылка.ЗначенияСвойствОбъектов");

Свойство = УправлениеСвойствами.ДобавитьСвойство("Справочник.Номенклатура", ПараметрыСвойства);

ПараметрыЗначения = УправлениеСвойствами.ПараметрыДобавленияЗначенияСвойства();
ПараметрыЗначения.Наименование       = "Хрупкий";
ПараметрыЗначения.ПолноеНаименование = "Хрупкий груз, требует маркировки";

Значение = УправлениеСвойствами.ДобавитьЗначениеСвойства("ПризнакУпаковки", ПараметрыЗначения);

Справочник значений выбирается по фактическому ТипЗначения свойства, а не по параметру Иерархия: если тип — ЗначенияСвойствОбъектовИерархия, элемент создаётся именно там. Флаг ЭтоГруппа в параметрах создаёт группу вместо элемента; Родитель задаёт её место в иерархии. Для свойства с типом, не содержащим значений свойств (число, строка, ссылка на прикладной справочник), функция выбросит исключение — добавлять значения там некуда.

Готовый список значений свойства читается функцией ПолучитьСписокЗначенийСвойств(Свойство) — возвращает массив ссылок.

Записать значения дополнительных реквизитов объекту

Для записи есть две разные функции, и путать их не стоит. ЗаписатьСвойстваУОбъекта() работает с уже записанным объектом: разделяет реквизиты и сведения, блокирует данные, пишет табличную часть и делает МенеджерЗаписи.Записать(Истина) по регистру — всё в транзакции.

ТаблицаСвойств = Новый ТаблицаЗначений;
ТаблицаСвойств.Колонки.Добавить("Свойство");
ТаблицаСвойств.Колонки.Добавить("Значение");

Строка = ТаблицаСвойств.Добавить();
Строка.Свойство = СвойствоСрокГодности;
Строка.Значение = 180;

УправлениеСвойствами.ЗаписатьСвойстваУОбъекта(НоменклатураСсылка, ТаблицаСвойств);

Второй вариант — УстановитьСвойстваУОбъекта(Владелец, Свойства), где Владелец — объект, а не ссылка, а Свойства — Соответствие «ссылка на свойство → значение». Она только заполняет табличную часть в памяти и ничего не записывает, поэтому подходит для нового, ещё не записанного объекта:

НовыйТовар = Справочники.Номенклатура.СоздатьЭлемент();
НовыйТовар.Наименование = "Ваза стеклянная";

Свойства = Новый Соответствие;
Свойства.Вставить(СвойствоСрокГодности, 180);
УправлениеСвойствами.УстановитьСвойстваУОбъекта(НовыйТовар, Свойства);

НовыйТовар.Записать();

Обе функции молча пропускают свойства, которых нет в наборах владельца: перед строкой записи вызывается СвойстваОбъекта(), и «чужие» свойства отфильтровываются. Если значение записалось, но в таблице его нет, — свойство просто не подключено к набору этого объекта.

Как подключить дополнительные реквизиты к форме объекта

Механизм встраивается в форму четырьмя обработчиками. Порядок и сигнатуры — из общего модуля УправлениеСвойствами:

&НаСервере
Процедура ПриСозданииНаСервере(Отказ, СтандартнаяОбработка)
    ДополнительныеПараметры = Новый Структура;
    ДополнительныеПараметры.Вставить("ИмяЭлементаДляРазмещения", "ГруппаДопРеквизиты");
    УправлениеСвойствами.ПриСозданииНаСервере(ЭтотОбъект, ДополнительныеПараметры);
КонецПроцедуры

&НаСервере
Процедура ПриЧтенииНаСервере(ТекущийОбъект)
    УправлениеСвойствами.ПриЧтенииНаСервере(ЭтотОбъект, ТекущийОбъект);
КонецПроцедуры

&НаСервере
Процедура ПередЗаписьюНаСервере(Отказ, ТекущийОбъект, ПараметрыЗаписи)
    УправлениеСвойствами.ПередЗаписьюНаСервере(ЭтотОбъект, ТекущийОбъект);
КонецПроцедуры

&НаСервере
Процедура ОбработкаПроверкиЗаполненияНаСервере(Отказ, ПроверяемыеРеквизиты)
    УправлениеСвойствами.ОбработкаПроверкиЗаполнения(ЭтотОбъект, Отказ, ПроверяемыеРеквизиты);
КонецПроцедуры

ПриСозданииНаСервере() создаёт реквизиты формы и элементы под каждое свойство, ПриЧтенииНаСервере() перезаполняет их при повторном чтении объекта, ПередЗаписьюНаСервере() переносит значения из реквизитов формы в объект, а ОбработкаПроверкиЗаполнения() проверяет свойства с признаком «Заполнять обязательно», включая условную обязательность зависимых реквизитов.

Если состав свойств изменился уже после открытия формы (пользователь отредактировал состав или ваш код вызвал ДобавитьСвойство()), элементы пересоздаются вызовом:

&НаСервере
Процедура ОбновитьСоставРеквизитовНаСервере()
    УправлениеСвойствами.ОбновитьЭлементыДополнительныхРеквизитов(ЭтотОбъект);
КонецПроцедуры

Для формы, которая последовательно показывает свойства разных объектов, в параметрах ставят ПроизвольныйОбъект = Истина. Тогда после ПриСозданииНаСервере() нужно самому вызывать ЗаполнитьДополнительныеРеквизитыВФорме(), а перед сохранением — ПеренестиЗначенияИзРеквизитовФормыВОбъект().

Наборы свойств: как объект получает свои реквизиты

Состав дополнительных реквизитов определяется не объектом, а его набором свойств. Ссылку на предопределённый набор возвращает НаборСвойствПоИмени():

НаборСвойств = УправлениеСвойствами.НаборСвойствПоИмени("Справочник_Пользователи");
Если НаборСвойств = Неопределено Тогда
    // предопределённый набор с таким именем не зарегистрирован
КонецЕсли;

Имя набора — полное имя объекта метаданных с точкой, заменённой на подчёркивание. Наборы регистрируются в УправлениеСвойствамиПереопределяемый.ПриПолученииПредопределенныхНаборовСвойств; если объекта там нет, программное добавление свойства к нему завершится исключением. Когда набор зависит от вида объекта (например, от вида номенклатуры), у владельца есть реквизит набора — по умолчанию НаборСвойств.

Перед обращением к подсистеме полезно проверить доступность: СвойстваДоступны() — есть ли право чтения справочника наборов, ИспользоватьДопРеквизиты(Ссылка) и ИспользоватьДопСведения(Ссылка) — поддерживает ли конкретный объект соответствующий вид свойств.

Частые ошибки при работе с дополнительными реквизитами БСП

• Чтение табличной части запросом вместо ЗначенияСвойств(). Строки длиннее 1024 символов хранятся в колонке ТекстоваяСтрока, и прямой запрос вернёт обрезанное значение.
• Передача массива объектов разных типов в ЗначенияСвойств(). Имя таблицы определяется по первому элементу массива, поэтому остальные типы просто не попадут в результат.
• Попытка записать дополнительное сведение через УстановитьСвойстваУОбъекта(). Функция принимает только дополнительные реквизиты и выбрасывает исключение ОшибкаКонфигурации. Для сведений — ЗаписатьСвойстваУОбъекта().
• Свойство не подключено к набору владельца. Запись молча пропускается: обе процедуры записи фильтруют значения по СвойстваОбъекта(). Проверяйте ПроверитьСвойствоУОбъекта().
• Не заполнены обязательные параметры в ДобавитьСвойство(). Без Наименование и ТипЗначения (или устаревшего Тип) вызов падает; для вида Метки обязателен ещё ЦветСвойства.
• Добавление значения свойству неподходящего типа. ДобавитьЗначениеСвойства() работает только с типами ЗначенияСвойствОбъектов и ЗначенияСвойствОбъектовИерархия.
• Забытый ПередЗаписьюНаСервере() в форме. Пользователь заполняет поля, но значения остаются в реквизитах формы и в объект не переносятся — после записи реквизиты пустые.
• Пустой результат у пользователя с ограниченными правами. Без права чтения справочника наборов ЗначенияСвойств() возвращает пустую таблицу, а сведения отфильтровываются отдельной проверкой права на регистр.

Частые вопросы о дополнительных реквизитах в БСП