1С: как обратиться к дополнительным свойствам объекта

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

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

Важно понимать: дополнительные свойства существуют только в оперативной памяти и только у конкретного экземпляра объекта. Они не сохраняются в базу данных и не передаются между серверными вызовами автоматически. Это инструмент для временного обмена данными внутри одного сеанса работы с объектом.

Что такое ДополнительныеСвойства и когда их применять

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

Типичные сценарии использования: передача признака из подписки «ПередЗаписью» в подписку «ПриЗаписи», отключение стандартных проверок при загрузке данных из внешних источников, передача параметров из обработки в модуль объекта, обмен данными между обработчиками проведения. Многие типовые конфигурации активно используют этот механизм — например, ключ НеВыполнятьКонтрольУдаляемых в процедурах обновления.

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

Для записи используется метод структуры Вставить(). Он принимает имя ключа (строку без пробелов, соответствующую правилам именования идентификаторов) и значение любого типа:

ОбъектДокумента.ДополнительныеСвойства.Вставить("РежимЗагрузки", Истина);
ОбъектДокумента.ДополнительныеСвойства.Вставить("КомментарийЗагрузки", "Загружено из XML");

Если ключ с таким именем уже существует, метод Вставить() перезапишет значение без предупреждения. Если нужно сохранить прежнее значение, сначала проверьте наличие ключа методом Свойство().

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

Как прочитать дополнительное свойство с проверкой

Безопасное чтение выполняется через метод Свойство(). Он возвращает Истина, если ключ найден, и помещает значение во второй параметр:

РежимЗагрузки = Ложь;
Если Объект.ДополнительныеСвойства.Свойство("РежимЗагрузки", РежимЗагрузки)
И РежимЗагрузки = Истина Тогда
// Пропускаем стандартные проверки
Возврат;
КонецЕсли;

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

1. 1
   Объявите переменную для значения и задайте ей значение по умолчанию
2. 2
   Вызовите Объект.ДополнительныеСвойства.Свойство("ИмяКлюча", Переменная)
3. 3
   Проверьте, что метод вернул Истина
4. 4
   Дополнительно проверьте тип и значение переменной перед использованием
5. 5
   При записи используйте Вставить() и уникальные понятные имена ключей

Передача данных между подписками и обработчиками

Из «ПередЗаписью» в «ПриЗаписи»

Классическая задача — в событии ПередЗаписью вычислить какие-то данные (например, прежние значения реквизитов из базы), а использовать их в ПриЗаписи или в ОбработкеПроведения. Дополнительные свойства решают её без глобальных переменных:

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

// Подписка ПриЗаписи
ПрежнийСтатус = Неопределено;
Если Источник.ДополнительныеСвойства.Свойство("ПрежнийСтатус", ПрежнийСтатус) Тогда
// Сравниваем старый и новый статус
КонецЕсли;

Из внешней обработки в модуль объекта

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

ДокОбъект.ДополнительныеСвойства.Вставить("ЗагрузкаИзОбработки", Истина);
ДокОбъект.Записать(РежимЗаписиДокумента.Проведение);

В модуле объекта этот признак читается через ДополнительныеСвойства.Свойство("ЗагрузкаИзОбработки", ...). Главное условие: и обработка, и запись должны выполняться в одном серверном вызове — при переходе «клиент–сервер» контекст объекта не переносится.

Дополнительные свойства наборов записей и типовые ключи БСП

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

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

Частые ошибки при работе с дополнительными свойствами

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

Ещё одна проблема — конфликт имён ключей. Если ваша подписка и типовой код используют одинаковое имя ключа, значения перезапишут друг друга. Используйте префиксы, например Преф_РежимЗагрузки, чтобы исключить пересечения.

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

Для отладки удобно выводить содержимое структуры в сообщение или журнал регистрации. Простой приём — перебрать структуру циклом:

Для Каждого КлючЗначение Из Объект.ДополнительныеСвойства Цикл
Сообщить(КлючЗначение.Ключ + " = " + КлючЗначение.Значение);
КонецЦикла;

В конфигураторе поставьте точку останова в обработчике записи и посмотрите ДополнительныеСвойства в табло: видно, какие ключи уже установлены типовым кодом до вашего обработчика. Это помогает понять, в каком порядке выполняются подписки и какие данные уже доступны.

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

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

Наличие ключа перед чтением

Норма

Метод Свойство() вернул Истина, значение ожидаемого типа

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

Метод вернул Ложь — ключ не был записан или объект получен заново

Поведение обработчика записи

Норма

Ветка кода, зависящая от ключа, выполняется

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

Ветка пропускается — проверьте, в том ли экземпляре объекта установлен ключ

Конфликт имён

Норма

Имя ключа уникально, в глобальном поиске встречается только в вашем коде

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

Ключ совпадает с типовым — значения перезаписываются

Чем дополнительные свойства отличаются от дополнительных реквизитов

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

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

Сравнение вариантов хранения данных

ДополнительныеСвойства

Временные служебные данные в памяти на время работы с объектом. Не сохраняются в базе

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

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

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

Произвольные пары «свойство-значение» в регистре сведений, не меняют структуру объекта

Параметры сеанса / фоновые механизмы

Для данных, нужных на протяжении всего сеанса, а не одной операции записи

Частые вопросы

Почему возникает ошибка «Поле объекта не обнаружено» при обращении к дополнительному свойству?

Ошибка означает, что ключ с таким именем не был добавлен в структуру ДополнительныеСвойства текущего экземпляра объекта. Либо запись выполнялась в другом экземпляре (объект получен заново), либо ветка кода с Вставить() не выполнилась. Читайте значение через метод Свойство() с проверкой результата.

Сохраняются ли дополнительные свойства при записи объекта в базу?

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

Можно ли передать дополнительные свойства с клиента на сервер?

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

Есть ли ДополнительныеСвойства у ссылки или у менеджера объекта?

Нет. Свойство доступно у объектов данных (ДокументОбъект, СправочникОбъект и т.п.) и у наборов записей. У типов ДокументСсылка, ДокументМенеджер, СправочникВыборка этого свойства нет — сначала нужно получить объект методом ПолучитьОбъект().

Как узнать, какие ключи уже установлены типовой конфигурацией?

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