Как в 1С обратиться к дополнительному реквизиту документа

Дополнительные реквизиты в 1С — это механизм БСП (библиотеки стандартных подсистем), который позволяет добавлять к документам и справочникам произвольные поля без изменения конфигурации. Хранятся они в табличной части объекта с именем ДополнительныеРеквизиты, а не в реквизитах шапки, поэтому обратиться к ним через точку, как к обычному реквизиту, нельзя — это самая частая причина ошибок у начинающих разработчиков.

Чтобы получить значение дополнительного реквизита, нужно найти в табличной части строку, где колонка Свойство ссылается на нужное свойство из плана видов характеристик «Дополнительные реквизиты и сведения», и прочитать колонку Значение. Свойство ищется по имени, заголовку или предопределённому имени — надёжнее всего по имени предопределённого элемента, потому что заголовок пользователь может переименовать.

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

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

В типовых конфигурациях на БСП у документов, к которым подключён механизм дополнительных реквизитов, есть стандартная табличная часть ДополнительныеРеквизиты с двумя ключевыми колонками: Свойство (ссылка на ПланВидовХарактеристик.ДополнительныеРеквизитыИСведения) и Значение (хранит данные типа, заданного в свойстве). Каждая строка — это одна пара «свойство → значение».

Сами настройки свойств — имя, тип значения, обязательность, наборы — задаются в режиме Предприятия через «Администрирование → Общие настройки → Дополнительные реквизиты и сведения». Прежде чем обращаться к реквизиту программно, убедитесь, что он создан и включён в набор свойств соответствующего вида документов, иначе табличная часть останется пустой.

Как найти свойство по имени перед обращением

Первый шаг любого обращения — получить ссылку на свойство. Самый устойчивый способ — поиск по имени предопределённого элемента, если свойство задано разработчиком, или по заголовку, если оно создано пользователем. Поиск по заголовку хрупок: пользователь может переименовать реквизит, и код перестанет находить строку.

// Поиск свойства по заголовку
Свойство = ПланыВидовХарактеристик.ДополнительныеРеквизитыИСведения
.НайтиПоНаименованию("Номер договора поставщика", Истина);

Если Свойство.Пустая() Тогда
ВызватьИсключение "Свойство не найдено";
КонецЕсли;

Если свойство предопределённое, используйте ПланыВидовХарактеристик.ДополнительныеРеквизитыИСведения.ИмяСвойства — так код не зависит от переименований. В некоторых конфигурациях имя хранится в реквизите Имя свойства (используется для УРИБ и обменов), тогда поиск делают запросом по этому реквизиту.

Чтение значения дополнительного реквизита

Когда ссылка на свойство получена, чтение сводится к поиску строки в табличной части. Для объекта документа это выглядит так:

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

Если Строки.Количество() > 0 Тогда
ЗначениеРеквизита = Строки[0].Значение;
Иначе
ЗначениеРеквизита = Неопределено; // реквизит не заполнен
КонецЕсли;

Если у вас только ссылка на документ, а не объект, выгрузить табличную часть можно запросом — так быстрее и не требует получения объекта целиком:

Запрос = Новый Запрос(
"ВЫБРАТЬ
|	ДопРеквизиты.Значение КАК Значение
|ИЗ
|	Документ.РеализацияТоваровУслуг.ДополнительныеРеквизиты КАК ДопРеквизиты
|ГДЕ
|	ДопРеквизиты.Ссылка = &Ссылка
|	И ДопРеквизиты.Свойство = &Свойство");

В конфигурациях на актуальных версиях БСП доступны готовые функции модуля УправлениеСвойствами (в старых версиях — УправлениеСвойствамиПереопределяемый и служебные процедуры), которые инкапсулируют этот поиск. Использовать их предпочтительнее, так как они учитывают особенности хранения конкретной версии библиотеки.

1. 1
   Убедитесь, что дополнительный реквизит создан и включён в набор свойств вида документа
2. 2
   Получите ссылку на свойство по предопределённому имени или заголовку
3. 3
   Найдите строку в табличной части ДополнительныеРеквизиты через НайтиСтроки или запросом
4. 4
   Прочитайте колонку Значение найденной строки
5. 5
   Обработайте случай, когда строка не найдена — значение считается незаполненным

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

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

ДокОбъект = ДокументСсылка.ПолучитьОбъект();

Строки = ДокОбъект.ДополнительныеРеквизиты.НайтиСтроки(
Новый Структура("Свойство", Свойство));

Если Строки.Количество() > 0 Тогда
Строки[0].Значение = НовоеЗначение;
Иначе
НоваяСтрока = ДокОбъект.ДополнительныеРеквизиты.Добавить();
НоваяСтрока.Свойство = Свойство;
НоваяСтрока.Значение = НовоеЗначение;
КонецЕсли;

ДокОбъект.Записать();

Тип записываемого значения должен совпадать с типом, указанным в настройках свойства. Если свойство имеет тип «Строка», а вы пытаетесь записать число или ссылку, платформа либо приведёт значение, либо запишет пустое — поведение зависит от состава типов. Перед записью проверяйте тип через ТипЗнч() и описание типов свойства.

Обращение к реквизиту на управляемой форме

На форме документа в конфигурациях с БСП дополнительные реквизиты обычно выведены динамически подсистемой свойств — элементы создаются программно при открытии. Обращаться к ним через Элементы.ИмяЭлемента нельзя, потому что имя генерируется. Работайте с данными объекта: Объект.ДополнительныеРеквизиты доступен в модуле формы как часть реквизита формы «Объект».

Типовой сценарий — обработка изменения значения. Подсистема свойств вызывает переопределяемые процедуры вида Подключаемый_СвойстваВыполнитьКоманду или обработчики обновления, в которых можно перехватить изменение. Если нужна своя логика — найдите строку по свойству в Объект.ДополнительныеРеквизиты внутри этих обработчиков и среагируйте на новое значение.

Для проверки заполненности перед записью документа удобно использовать обработчик ОбработкаПроверкиЗаполнения в модуле объекта: там табличная часть доступна напрямую, и можно отказать в записи с понятным сообщением, если обязательный дополнительный реквизит не заполнен по вашим правилам.

Дополнительные реквизиты и дополнительные сведения: не перепутайте

Механизмы похожи по интерфейсу, но хранятся по-разному. Дополнительный реквизит — строка в табличной части самого документа. Дополнительное сведение — запись в регистре сведений ДополнительныеСведения, где измерение «Объект» — ссылка на документ, а «Свойство» — та же ссылка на план видов характеристик. Обращение к сведениям делается через менеджер регистра или запрос, а не через табличную часть.

Сравнение вариантов

Дополнительный реквизит

Хранится в табличной части объекта, виден на форме, попадает в типовые печатные формы и обмены. Подходит для данных, которые должны жить вместе с документом.

Дополнительное сведение

Хранится в регистре сведений ДополнительныеСведения, читается и пишется через РегистрыСведений.ДополнительныеСведения. Подходит для служебных атрибутов, не требующих изменения документа.

Обычный реквизит конфигурации

Добавляется через конфигуратор, доступен через точку. Подходит, когда поле нужно в запросах, индексах и отчётах без соединений, но требует доработки конфигурации.

Чтение дополнительного сведения выглядит так:

Запрос = Новый Запрос(
"ВЫБРАТЬ
|	Сведения.Значение КАК Значение
|ИЗ
|	РегистрСведений.ДополнительныеСведения КАК Сведения
|ГДЕ
|	Сведения.Объект = &Объект
|	И Сведения.Свойство = &Свойство");

Если вы ищете значение в табличной части и не находите его, хотя на форме поле заполнено — почти наверняка это дополнительное сведение, а не реквизит. Проверить можно в настройках: сведения заводятся в разделе «Дополнительные сведения», реквизиты — в «Дополнительные реквизиты».

Типичные ошибки и как их избежать

Ещё одна частая проблема — дубли строк с одинаковым свойством, которые появляются после обменов или внешних обработок, добавляющих строки без проверки. Перед записью всегда ищите существующую строку и обновляйте её, а не добавляйте новую безусловно. Периодически полезно проверять базу запросом с группировкой по ссылке и свойству с КОЛИЧЕСТВО(*) > 1.

Контрольные точки

Как проверить результат

Открыть документ в режиме Предприятия после записи

Норма

Значение дополнительного реквизита отображается на форме

Тревожный признак

Поле пустое — запись не выполнилась или записана в другое свойство

Тип значения в строке табличной части

Норма

Совпадает с типом, заданным в настройках свойства

Тревожный признак

Пустое значение или значение другого типа

Количество строк с одним свойством

Норма

Одна строка на свойство

Тревожный признак

Дубли строк — нужна чистка и исправление кода записи

FAQ

Можно ли обратиться к дополнительному реквизиту в запросе по имени, без ссылки на свойство?

Напрямую по имени — нет, запрос работает со ссылками. Сначала получите ссылку на свойство (например, НайтиПоНаименованию или через предопределённое имя) и передайте её в запрос параметром. Альтернатива — соединение табличной части с планом видов характеристик по полю Наименование прямо в тексте запроса, но это медленнее и чувствительно к переименованиям.

Почему НайтиСтроки возвращает пустой массив, хотя реквизит на форме заполнен?

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

Как обратиться к дополнительному реквизиту в печатной форме или макете?

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

Можно ли сделать дополнительный реквизит обязательным программно?

Да, в свойстве есть признак обязательности заполнения — подсистема свойств сама выполнит проверку при записи. Если нужны свои условия (например, обязательность только для определённого вида операции), добавьте проверку в ОбработкаПроверкиЗаполнения модуля объекта с поиском строки по свойству.

Как массово заполнить дополнительный реквизит у многих документов?

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

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

Да, если в плане обмена зарегистрированы и сам документ, и план видов характеристик ДополнительныеРеквизитыИСведения с наборами свойств. При типовом обмене между идентичными конфигурациями свойства синхронизируются по имени; при расхождении имён значения могут не сопоставиться — проверяйте правила конвертации.